Call flow

Overview

The Routee Voice API handles two types of phone calls: inbound and outbound.
Inbound calls are calls made to a Routee number from another regular phone anywhere in the world.
Outbound calls are calls made from Routee to a regular phone number or SIP address. Outbound calls are usually initiated in response to a request made via the REST API to create a new call. Outbound calls may also be made from within the call flow of an existing call (either inbound or outbound) using the DIAL verb within the Dialplan. This scenario is generally used for forwarding calls.
Both inbound and outbound calls follow the same call flow once answered. This call flow is controlled by a Dialplan. A Dialplan is a JSON representation of actions to be run within the context of the call. Actions are executed in the order they appear in the JSON, with the next action starting when the previous action has finished executing. For more information about Dialplans, see the Dialplan reference.
When a call is answered, Routee makes a call to the DialplanUrl provided. For inbound calls the DialplanUrl is fetched from the configuration of the number is linked to. For outbound calls, Dialplan can be included in the body of the request. If you want to change that Dialplan you can do it in two ways. The first one is with the COLLECT verb. If the COLLECT verb is represented inside a Dialplan, all the DTMF tones which are sent (by pressing the buttons) from the user during the call, will be collected and transferred to eventUrl, with an HTTP POST request. At this point, Routee will wait for a response for 3 seconds. The response can only be a valid Dialplan. If a valid Dialplan is returned, Routee will execute it and skip the initial one.

Call states

Each call goes through a sequence of states in its lifecycle:

• Initiated
• Ringing
• Completed
• Busy
• Failed
• No Answer

Event objects

As the call progresses through the various call states, the Routee platform will send event objects to your eventUrl. Like the dialplanUrl , the Inbound Voice Callback URL is associated with the number for inbound calls or is supplied as an eventUrl parameter when the call is created.

The following table shows possible values for the status field of an event object:

An example event object is shown here:

{
  "messageId": "string",
  "conversationTrackingId": "string",
  "to": "string",
  "from": "string",
  "status": {
    "name": "string",
    "updatedDate": "string"
  },
  "direction": "string",
  "originatingService": "string",
  "respectQuietHours": "boolean",
  "duration": "number",
  "price": "number"
}

Dialplan URL payload

When an inbound call is answered a payload is POSTed to your DialplanUrl webhook.
The payload delivered to the DialplanUrl is in the form of query parameters and these are shown in the following table:

In general, useful information such as the calling number and destination number is extracted from the query string. For more information, refer to the Webhooks Reference.

Synchronous vs Asynchronous Actions

Each action within a Dialplan verb has certain conditions on which it will be considered "complete" and the call will progress to the next action. For some actions, this complete state can depend on how they are configured.

Dial

A Dial action will progress to the next action in the Dialplan when the call is completed.

Say

A Say action will finish when the requested text has been read the requested number of times. However, if bargeIn is set to true and the following action is an input, then the call will progress to accepting input as soon as the text starts to be played.

Play

A Play action will finish when the requested audio file has been played the requested number of times. However, if bargeIn is set to true and the following action is an input, then the call will progress to accepting input as soon as the file starts to be played.

Collect

A collect event will complete when one of the following conditions have been met:
The maxDigits number of digits are entered.
A # is sent and submitOnHash is set.
All Dialplan verb is finished.
The collect verb will then send a payload to the eventUrl webhook, containing the submitted digits.
Input is unique in that when the webhook is sent with the entered digits, the remote application can then return a new Dialplan to be executed. If no Dialplan is returned, then the call will continue to the next item in the Dialplan.

Transferring to a new Dialplan verb

You can replace the currently executing Dialplan with a new one by making an HTTP POST request to the REST API at https://connect.routee.net/voice/conversation/messageId/transfer with the number which you want to transfer the call inside the body of the request. This will overwrite all the actions that are currently executing or queued within the current Dialplan. One such use case for this is to transfer a call that is on hold (looping an audio file). After the transfer, no Dialplan verb will be executed and the active call will finish.

Machine Detection

With Machine Detection you are able to recognize whether a Human or a Machine (eg Voicemail system) has answered the call and set specific actions (Strategy) for those cases.
You can enable machineDetection when executing a Voice Conversation or when using the Dial Verb inside a Dialplan.

Machine detection can be configured by a Dial verb within a Dialplan or by performing an HTTP request to the REST API responsible for creating an outbound call. This can be set to one of two values, hangup or continue. If either of these values is set when the call is answered, Routee will attempt to determine if the call was answered by a human, or a machine such as voicemail. This normally takes a few seconds to be determined. At this point Routee will send an event to your eventUrl with either Human or Machine included.
If machine detection was set to hangup and Routee determined that a machine answered the call, then the call will be ended.
If set to continue then the call will remain connected. You can then modify the call, using a new dialplan as a response in enentUrl of machine detection or you can consume the API for handling an active call