Call Flow

Overview

The Nexmo Voice API handles two types of phone call: inbound and outbound.

Inbound calls are calls made to a Nexmo number from another regular phone anywhere in the world.

Outbound calls are calls made from the Nexmo platform to a regular phone number. 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 connect action within the NCCO (Nexmo Call Control Object). 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 an NCCO. An NCCO is a script of actions to be run within the context of the call. Actions are executed in the order they appear in the script, with the next action starting when the previous action has finished executing. For more information about NCCOs, see the NCCO reference.

When a call is answered, Nexmo makes a call to the answer_url provided. For inbound calls the answer_url is fetched from the configuration of the application that the number is linked to. For outbound calls, an answer_url is provided in the API request made to create the call.

You may choose to provide your NCCO as part of the request you send to create a call instead of providing an answer_url. This is done by providing an NCCO in the ncco key of your request

Call states

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

1. started
2. ringing
3. answered
4. completed

Event objects

As the call progresses through the various call states, the Nexmo platform will send event objects to your event_url. Like the answer_url the event_url is associated with the application for inbound calls, or is supplied as an event_url parameter when the call is created.

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

The type field in the event object is used for the transfer event:

An example event object is shown here:

{
    'conversation_uuid': 'CON-4bf66420-d6cb-46e0-9ba9-f7eede9a7301',
    'direction': 'inbound',
    'from': '447700900000',
    'status': 'started',
    'timestamp': '2018-08-14T11:07:01.284Z',
    'to': '447700900001',
    'uuid': '688fd94bd0e1f59c36a4cbd36312fc28'
}

An example object for a transfer event is shown here:

{
    'conversation_uuid_from': 'CON-4bf66420-d6cb-46e0-9ba9-f7eede9a7301',
    'type': 'transfer',
    'uuid': '688fd94bd0e1f59c36a4cbd36312fc28',
    'conversation_uuid_to': 'CON-4bf66420-d6cb-46e0-9ba9-f8eeba9f5619',
    'timestamp': '2018-08-14T11:07:01.284Z'
}

In addition, certain errors are sent to the event_url such as when your answer_url returns an invalid NCCO. You can find more detail in the Webhooks Reference.

Answer URL payload

When a call is answered a payload is delivered to your answer_url webhook.

The payload delivered to the answer_url is in the form of query parameters and these are shown in the following table:

To illustrate this, an example GET request to the answer_url is given here:

/webhooks/answer?to=447700900000&from=447700900001&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789cd

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

Synchronous vs Asynchronous Actions

Each action within an NCCO has certain conditions on which it will be considered "complete" and the call progresses to the next action. For some actions this completed state depends on how they are configured.

Record

A record action will complete when either the endOnSilence timer has been reached, or the endOnKey key is sent. At this point the recording ends and a recording event is sent before the next action is executed.

If neither value is set then the record will work in an asynchronous manner and will instantly continue on to the next action while still recording the call. The recording will only then end and send the relevant event when either the timeout value is reached or the call is ended.

Conversation

The conversation action always acts in a synchronous manner where the call is merged into the named conversation (or conference). The action only ends when the call is ended, and therefore all actions in an NCCO after a conversation action will be ignored.

Connect

A connect action will progress to the next action in the NCCO when the call is answered. If you have multiple connect actions in an NCCO it will call each one in turn and when answered create a conference between each leg of the call.

Talk

A talk action will complete 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.

Stream

A stream action will complete 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 text starts to be played.

Input

An input event will complete when one of the following conditions has been met:

1. The timeOut is reached
2. The maxDigits number of digits are entered
3. A # is sent and submitOnHash is set

The input action will then send a webhook to the event_url 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 NCCO to be executed. If no NCCO is returned, then the call will continue to the next item in the NCCO.

Transferring to a new NCCO

You can replace the currently executing NCCO with a new one by making an HTTP PUT request to the REST API with the call UUID in it. This will replace whatever actions are being executed or queued in the current NCCO. One such use case for this is to transfer a call that is on hold (looping an audio file) to an agent by putting a new NCCO with a connect action. However, you can also use this approach to simply modify any aspect of an in progress call.

Machine Detection

Machine detection can be configured on either a connect action within an NCCO or on a REST API request to create 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, Nexmo 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 Nexmo will send an event to your event_url with either Human or Machine included.

If machine detection was set to hangup and Nexmo 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. For example, you could transfer the call to a new destination with the PUT feature described above in the section Transferring to a new NCCO.

---