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":"+46701740605",
  "timeout":"15",
  "busy":{
    "connect":"+46701740664",
    "timeout":"15",
    "busy":{
      "connect":"+46701740622",
      "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.