Skip to navigation
Calls Stream Audio Play TTS Play DTMF
 
 

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.

Download OAS 3 Definition
Improve this specification

Jump to:

Calls »

Fetch, Create and Modify voice calls

Stream Audio »

Start or stop streaming audio in to an active call

Play TTS »

Start or stop playing Text to Speech in to an active call

Play DTMF »

Play DTMF tones in to an active call

There are multiple versions of this API available

Version 1 | Version 2

Calls

Fetch, Create and Modify voice calls

Available Operations:

Get details of your calls

Get details of your calls

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

Authentication

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

Query Parameter

status
string

Filter by call status

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

Return the records that occurred after this point in time

date_end
string (date-time)

Return the records that occurred before this point in time

page_size
integer | Default: 10

Return this amount of records in the response

record_index
integer | Default: 0

Return calls from this index in the response

order
string | Default: asc

Either ascending or descending order.

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

Return all the records associated with a specific conversation.

Responses

200 OK
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

calls
array of objects
uuid
string

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

conversation_uuid
string

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

to
object

The single or mixed collection of endpoint types you connected to

type
string
number
string
from
object

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

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. This is only sent if status is completed.

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.

Example Responses

200 
{
  "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

Create an outbound Call

POST https://api.nexmo.com/v1/calls
Host https://api.nexmo.com
POST /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

ncco
array of objects | Required

The Nexmo Call Control Object to use for this call.

to
array | Required
Choose an option:
  • Connect to a Phone (PSTN) number
  • Connect to a SIP Endpoint
  • Connect to a Websocket
  • Connect to a VBC extension
type
string | Required

The type of connection. Must be phone

number
string | Required | Min: 7 | Max: 15

The phone number to connect to

dtmfAnswer
string

Provide DTMF digits to send when the call is answered

type
string | Required

The type of connection. Must be sip

uri
string | Min: 1 | Max: 50

The SIP URI to connect to

type
string | Required

The type of connection. Must be websocket

content-type
string | Required

Connect to a Websocket

Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
uri
string | Min: 1 | Max: 50

Connect to a Websocket

headers
object

Details of the Websocket you want to connect to

customer_id
string

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

type
string | Required

The type of connection. Must be vbc

extension
string | Required

Connect to a VBC extension

from
object

Connect to a Phone (PSTN) number

type
string | Required

The type of connection. Must be phone

number
string | Required | Min: 7 | Max: 15

The phone number to connect to

random_from_number
boolean

Set to true to use random phone number as from. The number will be selected from the list of the numbers assigned to the current application. random_from_number: true cannot be used together with from.

event_url
array of strings

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.

event_method
string | Default: POST

The HTTP method used to send event information to event_url.

Must be one of: POST or GET
machine_detection
string

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.

Must be one of: continue or hangup
length_timer
integer | Min: 1 | Max: 7200 | Default: 7200

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

ringing_timer
integer | Min: 1 | Max: 120 | Default: 60

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

answer_url
array of strings | Required

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

to
array | Required
Choose an option:
  • Connect to a Phone (PSTN) number
  • Connect to a SIP Endpoint
  • Connect to a Websocket
  • Connect to a VBC extension
type
string | Required

The type of connection. Must be phone

number
string | Required | Min: 7 | Max: 15

The phone number to connect to

dtmfAnswer
string

Provide DTMF digits to send when the call is answered

type
string | Required

The type of connection. Must be sip

uri
string | Min: 1 | Max: 50

The SIP URI to connect to

type
string | Required

The type of connection. Must be websocket

content-type
string | Required

Connect to a Websocket

Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
uri
string | Min: 1 | Max: 50

Connect to a Websocket

headers
object

Details of the Websocket you want to connect to

customer_id
string

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

type
string | Required

The type of connection. Must be vbc

extension
string | Required

Connect to a VBC extension

answer_method
string | Default: GET

The HTTP method used to send event information to answer_url.

Must be one of: POST or GET
from
object

Connect to a Phone (PSTN) number

type
string | Required

The type of connection. Must be phone

number
string | Required | Min: 7 | Max: 15

The phone number to connect to

random_from_number
boolean

Set to true to use random phone number as from. The number will be selected from the list of the numbers assigned to the current application. random_from_number: true cannot be used together with from.

event_url
array of strings

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.

event_method
string | Default: POST

The HTTP method used to send event information to event_url.

Must be one of: POST or GET
machine_detection
string

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.

Must be one of: continue or hangup
length_timer
integer | Min: 1 | Max: 7200 | Default: 7200

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

ringing_timer
integer | Min: 1 | Max: 120 | Default: 60

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

Responses

201 Created
uuid
string

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

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.

Example Request » With NCCO

{
  "ncco": [
    {
      "action": "talk",
      "text": "Hello World"
    }
  ],
  "to": [
    {
      "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"
}

Example Request » With Answer URL

{
  "answer_url": [
    "https://example.com/answer"
  ],
  "to": [
    {
      "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"
}

Example Responses

201 
{
  "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 detail of a specific call

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

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call

Responses

200 Ok
uuid
string

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

conversation_uuid
string

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

to
object

The single or mixed collection of endpoint types you connected to

type
string
number
string
from
object

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

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. This is only sent if status is completed.

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.

Example Responses

200 
{
  "_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

Modify an in progress call

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

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call

Request body application/json

action
string | Required

Transfer the call to a new NCCO

Must be one of: transfer
destination
object | Required
type
string | Required

Always ncco

ncco
array of objects | Required

Refer to the NCCO Guide for a description of possible NCCO parameters.

action
string | Required

Transfer the call to a new NCCO

Must be one of: transfer
destination
object | Required
type
string | Required

Always ncco

url
array of strings | Required

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

action
string

End the call for the specified UUID

Must be one of: hangup
action
string

Mute the specified UUID

Must be one of: mute
action
string

Unmute the specified UUID

Must be one of: mute
action
string

Prevent the specified UUID from hearing audio

Must be one of: earmuff
action
string

Allow the specified UUID to hear audio

Must be one of: unearmuff

Example Request » Transfer with NCCO

{
  "action": "transfer",
  "destination": {
    "type": "ncco",
    "ncco": [
      {
        "action": "talk",
        "text": "Hello World"
      }
    ]
  }
}

Example Request » Transfer with Answer URL

{
  "action": "transfer",
  "destination": {
    "type": "ncco",
    "url": [
      "https://example.com/ncco.json"
    ]
  }
}

Example Request » Hangup

{
  "action": "hangup"
}

Example Request » Mute

{
  "action": "mute"
}

Example Request » Unmute

{
  "action": "unmute"
}

Example Request » Earmuff

{
  "action": "earmuff"
}

Example Request » Unearmuff

{
  "action": "unearmuff"
}

Example Responses

204 401 404 
No Content

This endpoint does not support application/json

This endpoint does not support application/json

Stream Audio

Start or stop streaming audio in to an active call

Available Operations:

Play an audio file into a 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

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call Leg

Request body application/json

action to perform

stream_url
array of strings | Required
loop
integer | Default: 1

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

level
string | Default: 0

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

Responses

200 Ok
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 Vonage. You use the UUID in all requests for individual live calls

Example Request

{
  "stream_url": [
    "https://example.com/waiting.mp3"
  ]
}
{
  "stream_url": [
    "https://example.com/waiting.mp3"
  ],
  "level": "0.4"
}

Example Responses

200 
{
  "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
Host https://api.nexmo.com
DELETE /v1/calls/:uuid/stream

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call Leg

Responses

200 Ok
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 Vonage. You use the UUID in all requests for individual live calls

Example Responses

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

Play TTS

Start or stop playing Text to Speech in to an active call

Available Operations:

Play text to speech into a 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

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call Leg

Request body application/json

Action to perform

text
string | Required

The text to read

language
string | Default: en-US

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
style
integer | Default: 0

The vocal style (vocal range, tessitura, and timbre) to use

voice_name
string | Default: Kimberly | DEPRECATED : This field has been deprecated.

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
loop
integer | Default: 1

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

level
string | Default: 0

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.

Responses

200 Ok
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 Vonage. You use the UUID in all requests for individual live calls

Example Request

{
  "text": "Hello. How are you today?"
}
{
  "text": "Hello. How are you today?",
  "level": "0.4"
}

Example Responses

200 
{
  "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
Host https://api.nexmo.com
DELETE /v1/calls/:uuid/talk

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call Leg

Responses

200 Ok
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 Vonage. You use the UUID in all requests for individual live calls

Example Responses

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

Play DTMF

Play DTMF tones in to an active call

Available Operations:

Play DTMF tones into a 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

Authentication

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

Path Parameters

uuid
string | Required

UUID of the Call Leg

Request body application/json

action to perform

digits
string

The digits to send

Responses

200 Ok
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 Vonage. You use the UUID in all requests for individual live calls

Example Request

{
  "digits": 1713
}

Example Responses

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