Call actions

A phone call in 46elks is basically a set of callbacks and results. Whenever something happens on our side, such as a new incoming call or the user pressing a digit on their phone, we'll notify you via webhook about the change in state. Your webhook should respond with an action, which dictates what the next step of the call is.

This works the same both for incoming and outgoing calls.

Actions

The following actions are currently available:

Action Description
Connect Connects the call to a given number.
Play Plays an audio file, dial tone or beep.
IVR Plays a message and collects numerical input from the user.
Record Records audio from the user for immediate playback or permanent storage.
Hangup Ends the call.

Each action is just a JSON struct that your webhook code replies with to dictate the next step of the call:

// The ”connect” action
{
  "connect": "+46766861004"
}
// The ”play” action
{
  "play": "https://yourapp.io/welcome.mp3"
}
// And so on...

The next parameter

Each action (except hangup) can include an optional next parameter that specifies the webhook address that the API should call when that action is completed. This allows you to build complex action chains with relative ease. If no next is specified the call will end after the action is completed.

For example, consider the following JSON struct:

{
  "connect": "+46766861004",
  "next": "https://yourapp.io/elks/calls",
}

Once the ”connect” action has completed the API will read the response of POST https://yourapp.io/elks/calls to find out what to do next. Note that this happens regardless of whether the conenct action was successful or not — whether or not it was successful will be indicated by the POST parameters.

The whenhangup parameter

All actions support the whenhangup parameter, which accepts a webhook URL that will be called when the call ends. This can only be set once per call (since a call can only end once).

POST https://yourapp.io/elks/whenhangup
Parameter Type Description
callid string The unique id of the call in our systems.
length int The length of the call, in seconds.
state string Either ”success”, ”failed” or ”busy”.
from string The sender of the call.
to string The phone number receiving the call.
created string The time in UTC when the call object was created in our systems.

Recording calls

You can put the key recordcall at any level within your chain of voice actions to begin recording the call. Once the call ends we'll post to the URL specified in the same format as the Record action.

POST https://yourapp.io/elks/recordings
Parameter Type Description
callid string The unique id of the call in our systems.
created string The date and time the recording was completed.
duration integer The length of the recording, in seconds.
wav string A URL that you can fetch the WAV audio file from.
from string The phone number that initiated the call.
to string The phone number of the recipient of the call.

Static control flow in JSON

If you can't or don't want to run your own backend there is limited support for handling control flow directly in the JSON struct itself. This is primarily done with the ”failed”, ”success” and ”next” keywords — ”failed” triggers when the current actions fails, ”success” triggers when the current action succeeds, and ”next” triggers regardless of whether the action succeeds or not. Individual actions may have other keywords for control flow. The connect action has ”busy”, for instance.

{
  "connect":"+46766860001",
  "timeout":"15",
  "busy":{
    "connect":"+46766860002",
    "timeout":"15",
    "busy":{
      "connect":"+46766860003",
      "timeout":"15",
    }
  }
}

However, we strongly recommend you to use the webhook integration and avoid putting control flow directly in the JSON struct if at all possible. It's really easy to make a mess.