Voice API

The Voice API lets you create outbound calls, control in-progress calls and get information about historical calls. More information about the Voice API can be found at https://developer.nexmo.com/voice/voice-api/overview.

There are multiple versions of this API available

Version 1 | Version 2

Create an outbound call

Create an outbound Call

POST https://api.nexmo.com/v1/calls

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Request body application/json

Call Details

Key Description Example Default
to
Required | array
None

Any one of the following:

Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
from
Required | object
Key Description Example Default
type
Required | string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
ncco
array
of strings

Required unless answer_url is provided.

The Nexmo Call Control Object to use for this call.

[
  {
    "action":"talk",
    "text": "Hello World"
  }
]
None
answer_url
array
of strings

Required unless ncco is provided.

The webhook endpoint where you provide the Nexmo Call Control Object that governs this call.

["https://example.com/answer"]
None
answer_method
string

The HTTP method used to send event information to answer_url.


Must be one of: POST or GET
None GET
event_url
Required | array
of strings

The webhook endpoint where call progress events are sent to. For more information about the values sent, see Event webhook.

["https://example.com/event"]
None
event_method
string

The HTTP method used to send event information to event_url.


Must be one of: POST or GET
None POST
machine_detection
string

Configure the behavior when Nexmo detects that the call is answered by voicemail. If Continue Nexmo sends an HTTP request to event_url with the Call event machine. hangup end the call


Must be one of: continue or hangup
continue None
length_timer
integer

Set the number of seconds that elapse before Nexmo hangs up after the call state changes to in_progress.


Must be between 1 and 7200
None 7200
ringing_timer
integer

Set the number of seconds that elapse before Nexmo hangs up after the call state changes to ‘ringing’.


Must be between 1 and 120
None 60

View response field descriptions

Response Fields

Field Description
uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

status
string

The status of the call. See possible values

direction
string

Possible values are outbound or inbound

One of: outbound or inbound
conversation_uuid
string

The unique identifier for the conversation this call leg is part of.

{
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
  "status": "started",
  "direction": "outbound",
  "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22"
}

Get details of your calls

Get details of your calls

GET https://api.nexmo.com/v1/calls

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Query Parameter

Key Description Example Default
status
string

Filter by call status


Must be one of: started, ringing, answered, machine, completed, busy, cancelled, failed, rejected, timeout or unanswered
started None
date_start
string | (date-time)

Return the records that occurred after this point in time

2016-11-14 07:45:14 UTC None
date_end
string | (date-time)

Return the records that occurred before this point in time

2016-11-14 07:45:14 UTC None
page_size
integer

Return this amount of records in the response

None 10
record_index
integer

Return calls from this index in the response

None 0
order
string

Either ascending or descending order.


Must be one of: asc or desc
None asc
conversation_uuid
string | (uuid)

Return all the records associated with a specific conversation.

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

View response field descriptions

Response Fields

Field Description
count
integer
page_size
integer
record_index
integer
_embedded
object

A list of call objects. See the get details of a specific call response fields for a description of the nested objects

Field Description
calls
array of objects
Field Description
uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

conversation_uuid
string

The unique identifier for the conversation this call leg is part of.

to
array of objects

The single or mixed collection of endpoint types you connected to

Field Description
type
string
number
string
from
array of objects

The endpoint you called from. Possible values are the same as to.

Field Description
type
string
number
string
status
string

The status of the call. See possible values

direction
string

Possible values are outbound or inbound

One of: outbound or inbound
rate
string

The price per minute for this call. This is only sent if status is completed.

price
string

The total price charged for this call. This is only sent if status is completed.

duration
string

The time elapsed for the call to take place in seconds. This is only sent if status is completed.

start_time
string

The time the call started in the following format: YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00.

end_time
string

The time the call started in the following format: YYYY-MM-DD HH:MM:SS. For xample, 2020-01-01 12:00:00. This is only sent if status is completed.

network
string

The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call.

{
  "count": 100,
  "page_size": 10,
  "record_index": 0,
  "_links": {
    "self": {
      "href": "/calls?page_size=10&record_index=20&order=asc"
    }
  },
  "_embedded": {
    "calls": [
      {
        "_links": {
          "self": {
            "href": "/calls/63f61863-4a51-4f6b-86e1-46edebcf9356"
          }
        },
        "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
        "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
        "to": [
          {
            "type": "phone",
            "number": "447700900000"
          }
        ],
        "from": [
          {
            "type": "phone",
            "number": "447700900001"
          }
        ],
        "status": "started",
        "direction": "outbound",
        "rate": "0.39",
        "price": "23.40",
        "duration": "60",
        "start_time": "2020-01-01 12:00:00",
        "end_time": "2020-01-01 12:00:00",
        "network": "65512"
      }
    ]
  }
}

Get detail of a specific call

Get detail of a specific call

GET https://api.nexmo.com/v1/calls/:uuid

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call

63f61863-4a51-4f6b-86e1-46edebcf9356 None

View response field descriptions

Response Fields

Field Description
uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

conversation_uuid
string

The unique identifier for the conversation this call leg is part of.

to
array of objects

The single or mixed collection of endpoint types you connected to

Field Description
type
string
number
string
from
array of objects

The endpoint you called from. Possible values are the same as to.

Field Description
type
string
number
string
status
string

The status of the call. See possible values

direction
string

Possible values are outbound or inbound

One of: outbound or inbound
rate
string

The price per minute for this call. This is only sent if status is completed.

price
string

The total price charged for this call. This is only sent if status is completed.

duration
string

The time elapsed for the call to take place in seconds. This is only sent if status is completed.

start_time
string

The time the call started in the following format: YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00.

end_time
string

The time the call started in the following format: YYYY-MM-DD HH:MM:SS. For xample, 2020-01-01 12:00:00. This is only sent if status is completed.

network
string

The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call.

{
  "_links": {
    "self": {
      "href": "/calls?page_size=10&record_index=20&order=asc"
    }
  },
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
  "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
  "to": [
    {
      "type": "phone",
      "number": "447700900000"
    }
  ],
  "from": [
    {
      "type": "phone",
      "number": "447700900001"
    }
  ],
  "status": "started",
  "direction": "outbound",
  "rate": "0.39",
  "price": "23.40",
  "duration": "60",
  "start_time": "2020-01-01 12:00:00",
  "end_time": "2020-01-01 12:00:00",
  "network": "65512"
}

Modify an in progress call

Modify an in progress call

PUT https://api.nexmo.com/v1/calls/:uuid

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call

63f61863-4a51-4f6b-86e1-46edebcf9356 None

Request body application/json

Key Description Example Default
action
Required | string

The action to apply to the in-progress call


Must be one of: hangup, mute, unmute, earmuff, unearmuff or transfer
mute None
destination
object

Required when action is transfer

Key Description Example Default
type
string

Always ncco

ncco None
url
array
of strings

The URL that Nexmo makes a request to. Must return an NCCO.

["https://example.com/ncco.json"]
None
ncco
array
of strings

Can be used instead of url for the transfer action only.

[{"action": "talk", "text": "hello world"}]
None
No Content
Unauthorized
Not Found

Play an audio file into a call

Play an audio file into a call

PUT https://api.nexmo.com/v1/calls/:uuid/stream

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call Leg

63f61863-4a51-4f6b-86e1-46edebcf9356 None

Request body application/json

action to perform

Key Description Example Default
stream_url
Required | array
of strings

None

["https://example.com/waiting.mp3"]
None
loop
integer

the number of times to play the file, 0 for infinite

None 1
level
string

Set the audio level of the stream in the range -1 >= level <= 1 with a precision of 0.1. The default value is 0.

0.4 0

View response field descriptions

Response Fields

Field Description
message
string

Description of the action taken

uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

{
  "message": "Stream started",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Stop playing an audio file into a call

Stop playing an audio file into a call

DELETE https://api.nexmo.com/v1/calls/:uuid/stream

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call Leg

63f61863-4a51-4f6b-86e1-46edebcf9356 None

View response field descriptions

Response Fields

Field Description
message
string

Description of the action taken

uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

{
  "message": "Stream stopped",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Play text to speech into a call

Play text to speech into a call

PUT https://api.nexmo.com/v1/calls/:uuid/talk

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call Leg

63f61863-4a51-4f6b-86e1-46edebcf9356 None

Request body application/json

Action to perform

Key Description Example Default
text
Required | string

The text to read

Hello. How are you today? None
voice_name
string

The voice & language to use


Must be one of: Salli, Joey, Naja, Mads, Marlene, Hans, Nicole, Russell, Amy, Brian, Emma, Geraint, Gwyneth, Raveena, Chipmunk, Eric, Ivy, Jennifer, Justin, Kendra, Kimberly, Conchita, Enrique, Penelope, Miguel, Chantal, Celine, Mathieu, Dora, Karl, Carla, Giorgio, Liv, Lotte, Ruben, Agnieszka, Jacek, Ewa, Jan, Maja, Vitoria, Ricardo, Cristiano, Ines, Carmen, Maxim, Tatyana, Astrid, Filiz, Mizuki or Seoyeon
None Kimberly
loop
integer

The number of times to repeat the text the file, 0 for infinite

None 1
level
string

The volume level that the speech is played. This can be any value between -1 to 1 in 0.1 increments, with 0 being the default.

0.4 0

View response field descriptions

Response Fields

Field Description
message
string

Description of the action taken

uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

{
  "message": "Talk started",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Stop text to speech in a call

Stop text to speech in a call

DELETE https://api.nexmo.com/v1/calls/:uuid/talk

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call Leg

63f61863-4a51-4f6b-86e1-46edebcf9356 None

View response field descriptions

Response Fields

Field Description
message
string

Description of the action taken

uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

{
  "message": "Talk stopped",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}

Play DTMF tones into a call

Play DTMF tones into a call

PUT https://api.nexmo.com/v1/calls/:uuid/dtmf

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None

Path Parameters

Key Description Example Default
uuid
Required | string

UUID of the Call Leg

63f61863-4a51-4f6b-86e1-46edebcf9356 None

Request body application/json

action to perform

Key Description Example Default
digits
string

The digits to send

1713 None

View response field descriptions

Response Fields

Field Description
message
string

Description of the action taken

uuid
string

The unique identifier for this call leg. The UUID is created when your call request is accepted by Nexmo. You use the UUID in all requests for individual live calls

{
  "message": "DTMF sent",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}