Voice API

The Voice API lets you create outboud calls, control in progress calls and get information about historical calls.

Download OpenAPI 3 Definition

Calls

Create and search calls

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

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


Must be one of: 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


Must be one of: sip
sip None
uri
string

The SIP URI to connect to

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

The type of connection. Must be websocket


Must be one of: 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
None
Key Description Example Default
customer_id
string

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

ABC123 None
from
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


Must be one of: 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


Must be one of: sip
sip None
uri
string

The SIP URI to connect to

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

The type of connection. Must be websocket


Must be one of: 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
None
Key Description Example Default
customer_id
string

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

ABC123 None
answer_url
Required | array
of string's

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

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
array
of string's

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

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

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

The status of the call. See possible values

direction

Possible values are outbound or inbound

conversation_uuid

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

The total number of records returned by your request.

page_size

The amount of records returned in this response.

record_index

The record_index used in your request.

_embedded

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

{
  "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"
      }
    ]
  }
}

Call

Manage a specific call

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

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

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

to

The single or mixed collection of endpoint types you connected to

from

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

status

The status of the call. See possible values

direction

Possible values are outbound or inbound

rate

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

price

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

duration

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

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.

end_time

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

network

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

None


Must be one of: hangup, mute, unmute, earmuff, unearmuff or transfer
mute None
destination
object
None
Key Description Example Default
type
string

None


Must be one of: ncco
ncco None
url
array
of string's

None

None
No content

Stream

Stream audio to an active call

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

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

Request body application/json

Key Description Example Default
stream_url
array
of string's

None

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 None

View response field descriptions

Response Fields

Field Description
message

Description of the action taken

uuid

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

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

View response field descriptions

Response Fields

Field Description
message

Description of the action taken

uuid

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"
}

Talk

Send a synthesized speech message to an active call

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

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

Request body application/json

Key Description Example Default
text
string

The text to read

Hello. How are you today? None
voice_name
string

None


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 with 0 being the default.

0 None

View response field descriptions

Response Fields

Field Description
message

Description of the action taken

uuid

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

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

View response field descriptions

Response Fields

Field Description
message

Description of the action taken

uuid

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"
}

DTMF

Send Dual-tone multi-frequency (DTMF) tones to an active call

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

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

Request body application/json

Key Description Example Default
digits
string

The digits to send

1713 None

View response field descriptions

Response Fields

Field Description
message

Description of the action taken

uuid

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"
}