Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Handle call status

Each time the status of Call or Conversation changes Nexmo sends a JSON object with information about the Call to the event webhook endpoint for your application.

The event webhook is defined in the following:

  • Application configuration - POST /applications - the default event webhook endpoint for all Calls and Conversations that use this application
  • A Call request - POST /calls - the event webhook endpoint used for a particular Call
  • A connect NCCO action - when you use the connect NCCO action to connect a voice call to an endpoint

A call can be initiated via a request to POST /calls. The response from this request contains initial information about the call.

{
  "uuid": "ade7b1d3-6cb7-4350-8750-dfdee725f256",
  "status": "started",
  "direction": "outbound",
  "conversation_uuid": "17f767a5-c1d7-4e9e-a132-6b3f3289efff"
}

Further status changes for the Call are sent to your event_url webhook endpoint. Each leg of a Call has a different uuid. You use the uuid in all /calls requests that alter or retrieve information about a Call.

If you record your Calls and Conversations, the download URL for the mp3 recording is sent to your event webhook endpoint when status is complete.

The objects returned for the different Call status look like:

{
  "uuid": "7dd82abd-563e-4b0a-ba17-e5f0297a7c63",
  "conversation_uuid": "78fd94b9-19f0-4df1-a538-8b0eebb09a18",
  "status": "ringing",
  "direction": "outbound"
}

To inspect and debug state changes without writing your own server, use an online endpoint service such as requestb.in  or hookbin.com  .

Possible values are:

Key Value
conversation_uuid The unique identifier for the conversation this call leg is part of. This parameter is created when your request is accepted and the status sent to event_url is ringing.
to The single or mixed collection of endpoint types you connected to. Possible values.
from The endpoint you called from. Possible values are the same as to.
direction Possible values are outbound or inbound.
recording_url The URL to download a Call or Conversation recording from.
rate The price per minute for this call.
start_time The time the call started in the following format: YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00.
network The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call.
status The status of the call. Possible values.
price The total price charged for this Call.
duration The time elapsed for the Call to take place in seconds.
end_time The time the Call ended in the following format: YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00.

to Values

phone - phone numbers in e.164 format. Options are:

Value Description
number The phone number to connect to in E.164 format  .
dtmfAnswer Set the digits that are sent to the user as soon as the call is answered. The * and `# digits are respected. You create pauses using p. Each pause is 500ms.

Status Values

Value Description
started Platform has stared the call.
ringing the user's handset is ringing.
answered the user has answered your call.
machine Platform detected an answering machine.
complete Platform has terminated this call.
timeout your user did not answer your call with ringing_timer seconds.
failed the call failed to complete
rejected the call was rejected
unanswered the call was not answered
busy the person being called was on another call

When a Call enters a state of timeout, failed, rejected, unanswered or busy the event_url webhook endpoint can optionally return an NCCO to override the current NCCO. See Connect with fallback NCCO.