Voice Callbacks Explained

Overview

Restcomm provides several ways for an application to receive status updates for a call. Upon receiving those events, applications may provide a new set of instructions (RCML) that dictate the next actions in the call flow.

By registering to Restcomm status callback, applications can receive notifications for:

  • Incoming calls for a given number

  • Outgoing calls triggered by the Calls API

  • Outgoing calls triggered by Dial RCML verb

Applications will also receive a status update on any RCML action URL where they can provide a new set of instructions for the call. Restcomm exposes the following action URL:

  • Dial action for outgoing calls

  • Record action for incoming calls

  • Gather action for incoming calls

The purpose of this document is not to repeat the details already described in the existing documentation, but to provide the big picture and to clarify some corner cases.

Understanding Bridged Calls

Restcomm uses the RCML Dial verb to connect two participants so they can communicate with each other.

Bridging two participants means connecting two distinct call legs. It is important to understand what a Call leg is in the context of Restcomm and what kind of status updates we can have for each call leg.

Consider the call flow depicted in the following diagram:

Bridge calls

In this diagram, call Leg A represents the incoming call from Alice to Restcomm while call leg B represents the outgoing call from Restcomm to Bob.

Both call legs are connected to each other in such way that media can flow both ways, but still remain two independent resources in the sense that they can be manipulated and observed separately. As such, Restcomm status callbacks will provide details for each call leg using different parameters.

In the above call flow, where Bob answers the call from Alice, there will be two final status notifications:

  • one for call leg A, with status completed and direction inbound

  • another for call leg B, with status completed and direction outbound

Let’s then consider another example, where Bob is busy and cannot answer the call from Alice:

Bridge Calls - Bob is busy

In this scenario the inbound call leg final status is completed because Restcomm answered the call from Alice and executed the RCML. On the other hand, the final status for the outbound call leg will be busy because the client Bob refused to answer the call.

Bridged call consists of two distinct call legs and the state of each leg is reported individually.

The fact that Restcomm keeps a separate state per call leg provides great flexibility to application developers and enables dynamic call flows.

In the previous example and after the call leg to Bob terminates, Restcomm will send a request to the Application Server (AS) informing that the Dial operation terminates and that the status of the outbound leg was busy and requesting the AS to provide the next set of RCML instructions. At this point, the AS understands that the call to Bob failed so it can provide RCML that allows to reach a fallback contact:

<Response>
<Dial>
    <Client>Carol</Client>
</Dial>
</Response>

The Application Server can provide different RCML instructions based on the status of a Call leg.

The Dial action feature will be further discussed later in this document.

Call Status callback

The Call Status callback is way for Restcomm to notify the Application Server about the progress of a call leg.

A status callback request does not expect a response.

If the application server needs to act on a call based on the status callback, it can use the Live Call Modification API to modify or terminate the call (read Calls API documentation on how to manipulate a live call).

IncomingPhoneNumber Status Callback

The IncomingPhoneNumber resources allows users to set the StatusCallback URL and StatusCallbackMethod in order to receive status notifications for every incoming call that targets that number.

For every request, Restcomm will send the following parameters (among others):

  • The call-sid

  • The caller and callee

  • The state of the inbound call leg

  • The state of the outbound call leg (if exists)

For example, consider the call flow depicted in the following diagram where Restcomm will send a notification for every state change during the call lifecycle.

Incoming Phone number Status callback

Outgoing Voice Calls

Restcomm can create an outgoing call either by using the RCML Dial verb or by using the Calls API. Each mechanism has its own way of providing status notifications.

Call event and Call status

In the lifetime of a call, several call events will occur that will trigger the call state change.

It is important to understand that the call event type doesn’t always match the call state.

For example, for call event answered the relevant call state is in-progress.

Let’s elaborate on the call event completed which is more complex than the other events.

The final state for a call could be one of the following:

  • completed - he dial completed with no issues

  • busy - the dial destination was busy

  • failed - the dial failed for a reason

  • no-answer - there was no answer to the dial

The call event completed includes any of the call final states, which means that if we register a status callback for event type completed, the call state in the callback could be any of the listed above.

Below is a detailed table with the list of call events and relevant call states.

Call Event Call State

initiated

initiated

ringing

ringing

answered

in-progress

completed

completed, busy, failed, no-answer

Dial Verb Status Callback

The Dial verb exposes the following parameters that users can configure to enable and tailor the status callback notifications:

  • Status callback URL

  • Status callback method: GET or POST

  • Status callback events: initiated, ringing, answered, completed

The status callback parameters are set in the child elements of the Dial verb (Client, Sip, Number) and not in the Dial verb itself.

This allows users to setup different webhooks for each outbound leg.

For example, RCML Dial to client Bob with status callback will look like:

<Dial>
    <Client statusCallback="/notify-me" statusCallbackEvent="initiated,ringing,answered,completed">
        Bob
    </Client>
</Dial>

The sequence diagram bellow depicts the call flow for the above RCML, showing the various status callback from both the IncomingPhoneNumber and the Dial verb.

Dial verb Status Callback

Calls API Status Callback

Using the Calls API we can create an outgoing call and ask Restcomm to connect to an RCML application.

In the Calls API POST request we can provide the following parameters regarding the status callback:

  • Status callback URL

  • Status callback method: GET or POST

  • Status callback events: initiated, ringing, answered, completed

For example, consider the following Calls API request to create a call to Bob:

curl -X POST https://www.yourcompany.com/api/2012-04-24/Accounts/AccountSid/Calls.json  \
   -d 'From=alice' \
   -d 'To=client:bob' \
   -d 'Url=https://application-server.com/hello-play.xml' \
   -d 'StatusCallback=http://notify.me' \
   -d 'StatusCallbackEvents=initiated,ringing,answered,completed' \
   -d 'StatusCallbackMethod=POST' \
   -u 'AccountSid:AuthToken'

Notice that the response from Restcomm will contain details for the created call, such as CallSid and CallStatus.

Restcomm will handle the status callback for an outgoing call generated via Calls API in the exact same way as in the Dial verb.

The following sequence diagram demonstrates the call flow for the above Calls API request.

Calls API create call status callback

Dial Action Callback

The Dial verb action callback will provide only the final status for both the inbound and the outbound legs through the CallStatus and DialCallStatus parameters, respectively.

An action url can be set for the Dial, Gather or Record verb and the following parameters can be set:

  • Action URL

  • Action method

After executing a verb that contains an action url, Restcomm will send a request to that url with the usual call parameters (including the call state) and will then wait for a response containing a new set of RCML instructions for how to proceed.

If a verb contains an action URL then the following verbs in the same RCML document will never be executed.

In this example, the last Say verb will never be executed because the Dial action invocation returns a new RCML document that is executed.

<Response>
  <Say>Welcome!</Say>
  <Dial action="http://appserver.com/action" method="POST">
    <Client>Bob</Client>
  </Dial>
  <Say>This is the end of the RCML</Say>
</Response>

Consider the following sequence diagram that demonstrate the Dial action. In the example here there is no status callback set at the incoming phone number or at the Dial verb.

Dial action