Evil Martians Telephony

A cloud-based Martian swiss army knife for voice calls, VoIP, conferencing, and voicemail. Powered by VoxImplant.

<a href="https://evilmartians.com/?utm_source=telephony"> <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"> </a>

Overview

The code is for an open source version of Evil Martians' very own telephony platform that runs all our phone numbers.

This is a swiss army knife for everything we do with our phone numbers at Evil Martians. It currently runs on the VoxImplant cloud platform, is implemented in JavaScript, and is designed to run via continuous integration and continuous deployment tools.

You can use it to build your simple telephony solutions, with one or multiple office locations, managers scheduled to answer a call, conferencing, and short numbers.

It should be relatively easy to change the system for your specific usage requirements and integrations, or configure and run it as-is.

The application is mostly designed for engineering-friendly companies. It is intended for advanced users who know their way around Git and can alter the address book or schedule by editing JSON and pushing the code or making a pull request. This way, we can avoid monstrous integrations, and every single change is right there in the git repository.

Cheatsheet

| | | |--------------------------------|------------------------------------------------------| | Address book: | address_book.json | | Schedule: | ZONE-schedule.json | | Extension numbers: | 3 digits, dial immediately after the machine answers | | Forward and hang up: | #NUMBER, for instance, #001 | | Add to a conference, stay: | ##NUMBER, for instance ##001 |

Usage

Zones

The application shares code between zones. Think of "zone" as an office location or an application. Each zone is defined by its config and schedule. Some companies would only require a single zone.

In our use case, "US", "RU" and "JP" are the zones that we have—assigned to every country we have an office in.

Address book and schedule

The application requires a shared address book for all zones and one schedule per each zone.

N.B.: For end-users, it is advised to use a programming code editor to edit the file. Great if you have a JavaScript/JSON linter turned on. As soon as you commit the file into the repository, the software is designed to use the continuous integration server to build and push the configuration to the production environment. If there are any errors, syntax or otherwise, you will get an email. If everything is fine, changes will be applied in under a couple of minutes.

Address book

The address book is shared company-wide and available for all zones. That means that you can dial or forward calls to any user in the address book, no matter the phone number called or the current active zone.

Most importantly, everyone in the company should be encouraged to add themselves to the address book. You don't have any obligations when you pick a short number/extension code, so it's completely safe even if you're not a manager. You will get an extension number that works on all phones and all zones, an ability to forward calls to you or be invited to a conference, and a voicemail feature for your extension number.

The address book itself is a JSON file called address_book.json.

Example:

[
    {
        "email": "jane.doe@example.com",
        "ext": "001",
        "name": "Jane Doe",
        "number": "+1 206 555 0001"
    }
]

All fields are mandatory. email is the email address where you will get notifications about missed calls and voicemails. Use your primary corporate email address.

ext is your extension number. Three digits, no more, no less.

name is your name.

number is your phone number in full international form, starting with country code and a +. Make sure to update it frequently if you travel.

Schedule

A schedule is where the call queue/schedule is defined. When a call goes to a zone number, the system will try each person from the list, top to bottom, with respect to their schedule and timezone.

The schedule is a file called like ZONE-schedule.json.

Let's take a look:

[
  {
      "email": "jane.doe@example.com",
      "timeZone": "America/New_York",
      "schedule": {
          "Mon": [9, 18],
          "Tue": [9, 18],
          "Wed": [9, 18],
          "Thu": [9, 18],
          "Fri": [9, 18]
      }
  },
  {
      "email": "john.doe@example.com",
      "timeZone": "America/Los_Angeles",
      "schedule": {
          "All": [7, 20]
      }
  }
]

In this example, Jane is the first one to get a call. Her schedule is defined in the New York time zone, from Monday to Friday, from 9 to 18. In case Jane is not available on her phone—or the call was not received at business hours—John is next on the line, working at Los Angeles time zone (PST), from 7 to 20 every day. If John is unavailable as well, the call goes to voicemail.

email is a person's email, and it should be the same as the email in the Address book. It is also not possible to add a person to schedule if they are not in an Address book. Again, make sure to use your primary email.

timeZone is the time zone for the following schedule. Note that your time zone is not the same thing as the nearest larger city. For a precise list of time zone identifiers, check https://momentjs.com/timezone/. Usually, it's America/Los_Angeles for PST and America/New_York for EST.

schedule is your working hours schedule. You can use the All key to define a unified schedule for all days of the week or specify a different schedule for each day of the week using the three-letter short form. All hours are in 24-hour format, to prevent any mixup.

Calling in

As a caller, I will be greeted with a pre-recorded message telling me to stay on the line or dial an extension number.

General number

If I don't know any extension numbers, I will stay on the line, and the software will try each person from the schedule list for the zone. The software will seek only the people who can answer the call right now, according to the schedule. Each person will be tried for 15 seconds, there will be an outgoing call, and I will hear the beeps. If there was no answer, or there was an error of any kind, networking, cellular or otherwise, the software will automatically try the next number.

Once I am connected to a manager, I can have a regular old-fashioned talk. Once the manager or I hang up, the call will end. The manager could also redirect me to a different person or make a conference call, adding another person.

If nobody can answer or if the queue is empty (for instance, if the call is late at night and zero people are working at that time, according to schedule), my call will go straight to voicemail, with a helpful message. I can hang the phone immediately; in this case, managers will receive an SMS and an email message stating my number to get back to me. Alternatively, I can leave a voicemail, and in this case, the email with my info will also have a link to the voicemail.

Extension number

If I want to reach a specific person, I can use my tone dial to dial three digits (001, for instance).

If the number I dialed is wrong (no such number or I've made a mistake), there will be a helpful message advising me to hang up and try again or stay on the line. If I stay on the line, the call will be treated as a general call to a company number, and hopefully, one of the managers will pick up.

If the number is correct, I will hear the beeps while the software is trying to call a person. If the person picks up, I can have a regular call; the manager on the other side will be able to redirect me to someone or make a conference call as well.

If the number is correct, but the person did not answer, I will get a helpful message asking me to leave a voicemail. I can hang up immediately; in this case, the manager will get an SMS and an email with my number. Alternatively, I can leave a voicemail, and in this case, the email to the manager will include the recording.

Receiving the call

Manager

As a manager, I may be on one of the schedules for a zone. I must update my phone number each time it is changed and fine-tune my scheduling as discussed with other managers from my zone.

Once I get a call from the client to a general company phone number, my phone will display that client's number, so that I can get back to them later. When I pick the phone, a pre-recorded message will state that this is a call to a company. Following the message, I can have a regular call with a caller and hang up later. The call ends when one of us hangs up.

If it is not my turn to receive calls, according to the schedule, the software will never try to call me at all.

If I cannot answer, I can decline the call, and the software will try another manager automatically or go straight to voicemail.

If no one were able to answer, because of scheduling or unavailability, there would be an SMS stating that there was a missing call and an email; both will contain that person's number. The email will include the caller's phone number and call time in various timezones specific to each zone. If the person did leave a voicemail, the email would contain a link to the recording. Keep in mind that the file will be available for several months only, so make sure to download it if it is useful.

Extension number

As any person in the address book, I