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.
Record call Records audio for the entire call.
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": "+46700000000"
}
// The ”play” action
{
  "play": "https://yourapp.example/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": "+46700000000",
  "next": "https://yourapp.example/elks/calls"
}

Once the ”connect” action has completed, the API will read the response of POST https://yourapp.example/elks/calls to find out what to do next. Note that this happens regardless of whether the connect 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 be set multiple times, overwriting the the value, but it is only triggered once per call (since a call can only end once).

POST https://yourapp.example/elks/whenhangup
Example payload
direction=outgoing&
from=%2B46766862965&
start=2020-05-25T10%3A09%3A03.246556&
created=2020-05-25T10%3A08%3A54.367600&
actions=%5B%7B%22play%22%3A+%22https%3A%2F%2Ffiles.46elks.com%2Fben%2Fcustomer-service.mp3%22%2C+%22result%22%3A+%22failed%22%2C+%22why%22%3A+%22hangup%22%7D%5D&
to=%2B46766866966&
state=success&
cost=5700&
duration=5&
id=c52eb46be23533b89110d703e5976d38a'
Parameter Type Description
direction string The direction of the call. Set to "outgoing" for calls initated by the API and "incoming" for calls initated by phones.
from string The sender of the call.
start string Time the call was picked up.
created string The time in UTC when the call object was created in our systems.
actions list Array of actions taken by the API during the call, such as action connect or action play.
to string The phone number receiving the call.
state string Either ”success”, ”failed” or ”busy”.
cost integer Cost of the call. Specified in 10000s of the currency of your account. For an account with currency SEK a cost of 5700 means that the price for making this call was 0.57 SEK.
duration integer The length of the call, in seconds.
id string The unique ID of the call 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.example/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.