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.
Fetch, Create and Modify voice calls
Start or stop streaming audio in to an active call
Start or stop playing Text to Speech in to an active call
Play DTMF tones in to an active call
Fetch, Create and Modify voice calls
Get details of your calls
GET
https://api.nexmo.com/v1/calls
Host
https://api.nexmo.com
GET
/v1/calls
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Filter by call status
Must be one of:started
, ringing
, answered
, machine
, completed
, busy
, cancelled
, failed
, rejected
, timeout
or unanswered
Return the records that occurred after this point in time
Return the records that occurred before this point in time
Return this amount of records in the response
Return calls from this index in the response
Either ascending or descending order.
Must be one of:asc
or desc
Return all the records associated with a specific conversation.
A list of call objects. See the get details of a specific call response fields for a description of the nested objects
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
The unique identifier for the conversation this call leg is part of.
The single or mixed collection of endpoint types you connected to
The endpoint you called from. Possible values are the same as to
.
Possible values are outbound
or inbound
outbound
or inbound
The price per minute for this call. This is only sent if status
is completed
.
The total price charged for this call. This is only sent if status
is completed
.
The time elapsed for the call to take place in seconds. This is only sent if status
is completed
.
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
.
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
.
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"
}
]
}
}
Create an outbound Call
POST
https://api.nexmo.com/v1/calls
Host
https://api.nexmo.com
POST
/v1/calls
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Call Details
The Nexmo Call Control Object to use for this call.
The type of connection. Must be phone
The phone number to connect to
Provide DTMF digits to send when the call is answered
The type of connection. Must be sip
The SIP URI to connect to
The type of connection. Must be websocket
Connect to a Websocket
Must be one of:audio/l16;rate=8000
or audio/l16;rate=16000
Connect to a Websocket
Details of the Websocket you want to connect to
This is an example header. You can provide any headers you may need
The type of connection. Must be vbc
Connect to a VBC extension
Connect to a Phone (PSTN) number
The type of connection. Must be phone
The phone number to connect to
Required unless event_url
is configured at the application
level, see Create an Application
The webhook endpoint where call progress events are sent to. For more information about the values sent, see Event webhook.
The HTTP method used to send event information to event_url
.
POST
or GET
Configure the behavior when Vonage detects that the call is answered by voicemail. If continue
, Vonage sends an HTTP request to event_url
with the Call event machine. If hangup
, Vonage ends the call.
continue
or hangup
Set the number of seconds that elapse before Vonage hangs up after the call state changes to answered.
Set the number of seconds that elapse before Vonage hangs up after the call state changes to ‘ringing’.
The webhook endpoint where you provide the Nexmo Call Control Object that governs this call.
The type of connection. Must be phone
The phone number to connect to
Provide DTMF digits to send when the call is answered
The type of connection. Must be sip
The SIP URI to connect to
The type of connection. Must be websocket
Connect to a Websocket
Must be one of:audio/l16;rate=8000
or audio/l16;rate=16000
Connect to a Websocket
Details of the Websocket you want to connect to
This is an example header. You can provide any headers you may need
The type of connection. Must be vbc
Connect to a VBC extension
Connect to a Phone (PSTN) number
The type of connection. Must be phone
The phone number to connect to
The HTTP method used to send event information to answer_url.
Must be one of:POST
or GET
Required unless event_url
is configured at the application
level, see Create an Application
The webhook endpoint where call progress events are sent to. For more information about the values sent, see Event webhook.
The HTTP method used to send event information to event_url
.
POST
or GET
Configure the behavior when Vonage detects that the call is answered by voicemail. If continue
, Vonage sends an HTTP request to event_url
with the Call event machine. If hangup
, Vonage ends the call.
continue
or hangup
Set the number of seconds that elapse before Vonage hangs up after the call state changes to answered.
Set the number of seconds that elapse before Vonage hangs up after the call state changes to ‘ringing’.
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
Possible values are outbound
or inbound
outbound
or inbound
The unique identifier for the conversation this call leg is part of.
{
"ncco": [
{
"action": "talk",
"text": "Hello World"
}
],
"to": [
{
"type": "phone",
"number": "14155550100"
}
],
"from": {
"type": "phone",
"number": "14155550100"
}
}
{
"ncco": [
{
"action": "talk",
"text": "Hello World"
}
],
"to": [
{
"type": "phone",
"number": "14155550100",
"dtmfAnswer": "p*123#"
}
],
"from": {
"type": "phone",
"number": "14155550100"
},
"event_url": [
"https://example.com/event"
],
"machine_detection": "continue"
}
{
"answer_url": [
"https://example.com/answer"
],
"to": [
{
"type": "phone",
"number": "14155550100"
}
],
"from": {
"type": "phone",
"number": "14155550100"
}
}
{
"answer_url": [
"https://example.com/answer"
],
"to": [
{
"type": "phone",
"number": "14155550100",
"dtmfAnswer": "p*123#"
}
],
"from": {
"type": "phone",
"number": "14155550100"
},
"event_url": [
"https://example.com/event"
],
"machine_detection": "continue"
}
{
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
"status": "started",
"direction": "outbound",
"conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22"
}
Get detail of a specific call
GET
https://api.nexmo.com/v1/calls/:uuid
Host
https://api.nexmo.com
GET
/v1/calls/:uuid
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
The unique identifier for the conversation this call leg is part of.
The single or mixed collection of endpoint types you connected to
The endpoint you called from. Possible values are the same as to
.
Possible values are outbound
or inbound
outbound
or inbound
The price per minute for this call. This is only sent if status
is completed
.
The total price charged for this call. This is only sent if status
is completed
.
The time elapsed for the call to take place in seconds. This is only sent if status
is completed
.
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
.
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
.
The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call.
{
"_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"
}
Modify an in progress call
PUT
https://api.nexmo.com/v1/calls/:uuid
Host
https://api.nexmo.com
PUT
/v1/calls/:uuid
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call
Transfer the call to a new NCCO
Must be one of:transfer
Always ncco
Refer to the NCCO Guide for a description of possible NCCO parameters.
Transfer the call to a new NCCO
Must be one of:transfer
Always ncco
The URL that Vonage makes a request to. Must return an NCCO.
End the call for the specified UUID
Must be one of:hangup
Mute the specified UUID
Must be one of:mute
Unmute the specified UUID
Must be one of:mute
Prevent the specified UUID from hearing audio
Must be one of:earmuff
Allow the specified UUID to hear audio
Must be one of:unearmuff
{
"action": "transfer",
"destination": {
"type": "ncco",
"ncco": [
{
"action": "talk",
"text": "Hello World"
}
]
}
}
{
"action": "transfer",
"destination": {
"type": "ncco",
"url": [
"https://example.com/ncco.json"
]
}
}
{
"action": "hangup"
}
{
"action": "mute"
}
{
"action": "unmute"
}
{
"action": "earmuff"
}
{
"action": "unearmuff"
}
No Content
This endpoint does not support application/json
This endpoint does not support application/json
Start or stop streaming audio in to an active call
Play an audio file into a call
PUT
https://api.nexmo.com/v1/calls/:uuid/stream
Host
https://api.nexmo.com
PUT
/v1/calls/:uuid/stream
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call Leg
action to perform
the number of times to play the file, 0 for infinite
Set the audio level of the stream in the range -1 >= level <= 1
with a precision of 0.1. The default value is 0.
Description of the action taken
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
{
"stream_url": [
"https://example.com/waiting.mp3"
]
}
{
"stream_url": [
"https://example.com/waiting.mp3"
],
"level": "0.4"
}
{
"message": "Stream started",
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}
Stop playing an audio file into a call
DELETE
https://api.nexmo.com/v1/calls/:uuid/stream
Host
https://api.nexmo.com
DELETE
/v1/calls/:uuid/stream
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call Leg
Description of the action taken
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
{
"message": "Stream stopped",
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}
Start or stop playing Text to Speech in to an active call
Play text to speech into a call
PUT
https://api.nexmo.com/v1/calls/:uuid/talk
Host
https://api.nexmo.com
PUT
/v1/calls/:uuid/talk
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call Leg
Action to perform
The text to read
The language to use
Must be one of:ar
, ca-ES
, cmn-CN
, cmn-TW
, cs-CZ
, cy-GB
, da-DK
, de-DE
, el-GR
, en-AU
, en-GB
, en-GB-WLS
, en-IN
, en-US
, en-ZA
, es-ES
, es-MX
, es-US
, eu-ES
, fi-FI
, fil-PH
, fr-CA
, fr-FR
, he-IL
, hi-IN
, hu-HU
, id-ID
, is-IS
, it-IT
, ja-JP
, ko-KR
, nb-NO
, nl-NL
, no-NO
, pl-PL
, pt-BR
, pt-PT
, ro-RO
, ru-RU
, sk-SK
, sv-SE
, th-TH
, tr-TR
, uk-UA
, vi-VN
or yue-CN
The vocal style (vocal range, tessitura, and timbre) to use
DEPRECATED The voice & language to use
Must be one of:Aditi
, Agnieszka
, Alva
, Amy
, Astrid
, Bianca
, Brian
, Carla
, Carmen
, Carmit
, Catarina
, Celine
, Cem
, Chantal
, Chipmunk
, Conchita
, Cristiano
, Damayanti
, Dora
, Emma
, Empar
, Enrique
, Eric
, Ewa
, Felipe
, Filiz
, Geraint
, Giorgio
, Gwyneth
, Hans
, Henrik
, Ines
, Ioana
, Iveta
, Ivy
, Jacek
, Jan
, Jennifer
, Joana
, Joanna
, Joey
, Jordi
, Justin
, Kanya
, Karl
, Kendra
, Kimberly
, Laila
, Laura
, Lea
, Lekha
, Liv
, Lotte
, Lucia
, Luciana
, Mads
, Maged
, Maja
, Mariska
, Marlene
, Mathieu
, Matthew
, Maxim
, Mei-Jia
, Melina
, Mia
, Miguel
, Miren
, Mizuki
, Montserrat
, Naja
, Nicole
, Nikos
, Nora
, Oskar
, Penelope
, Raveena
, Ricardo
, Ruben
, Russell
, Salli
, Satu
, Seoyeon
, Sin-Ji
, Sora
, Takumi
, Tarik
, Tatyana
, Tessa
, Tian-Tian
, Vicki
, Vitoria
, Yelda
, Zeina
, Zhiyu
or Zuzana
The number of times to repeat the text the file, 0 for infinite
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.
Description of the action taken
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
{
"text": "Hello. How are you today?"
}
{
"text": "Hello. How are you today?",
"level": "0.4"
}
{
"message": "Talk started",
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}
Stop text to speech in a call
DELETE
https://api.nexmo.com/v1/calls/:uuid/talk
Host
https://api.nexmo.com
DELETE
/v1/calls/:uuid/talk
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call Leg
Description of the action taken
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
{
"message": "Talk stopped",
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}
Play DTMF tones in to an active call
Play DTMF tones into a call
PUT
https://api.nexmo.com/v1/calls/:uuid/dtmf
Host
https://api.nexmo.com
PUT
/v1/calls/:uuid/dtmf
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
UUID of the Call Leg
action to perform
The digits to send
Description of the action taken
The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage. You use the UUID in all requests for individual live calls
{
"digits": 1713
}
{
"message": "DTMF sent",
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356"
}