API Dashboard
Vonage.com
Pricing
Support
Documentation
Blog
Code Hub

Voice API

Version 1

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. To create IP calls please check the following page: https://developer.vonage.com/en/api/voice.v2.

Download OpenAPI Specification

Calls

Fetch, Create and Modify voice calls

Available Operations

Get details of your calls

Get details of your calls

gethttps://api.nexmo.com/v1/calls/

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Query Parameters

status
string
examplestarted

Filter by call status

Must be one of:startedringingansweredmachinecompletedbusycancelledfailedrejectedtimeoutunanswered
date_start
string(date-time)
example2016-11-14T07:45:14Z

Return the records available after this point in time. Please use Reports API for older call information.

date_end
string(date-time)
example2016-11-14T07:45:14Z

Return the records that occurred before this point in time

page_size
integer
Min1
Max100
Default10

Return this amount of records in the response

record_index
integer

Return calls from this index in the response

order
string
Defaultasc

Either ascending or descending order.

Must be one of:ascdesc
conversation_uuid
string(uuid)
exampleCON-f972836a-550f-45fa-956c-12a2ab5b7d22

Return all the records associated with a specific conversation.

Responses
Content Type
application/json

OK

count
integer
example100
page_size
integer
example10
record_index
integer
_links
object
self
object
href
string
example/calls?page_size=10&record_index=20&order=asc
first
object
href
string
example/calls?page_size=10&record_index=20&order=asc
last
object
href
string
example/calls?page_size=10&record_index=20&order=asc
next
object
href
string
example/calls?page_size=10&record_index=20&order=asc
prev
object
href
string
example/calls?page_size=10&record_index=20&order=asc
_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
_links
object
self
object
href
string
example/calls/63f61863-4a51-4f6b-86e1-46edebcf9356
uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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(uuid)
exampleCON-f972836a-550f-45fa-956c-12a2ab5b7d22

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

to
One Of
type
string
Required
examplephone

The type of connection. Must be phone

number
string
Required
Min7
Max15
example14155550100

The phone number to connect to

dtmfAnswer
string
examplep*123#

Provide DTMF digits to send when the call is answered

from
object

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

type
string
examplephone
number
string
example447700900001
status
string
examplecompleted

The status of the call. See possible values

direction
string
exampleoutbound

Possible values are outbound or inbound

Must be one of:outboundinbound
rate
string
example0.39

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

price
string
example23.40

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

duration
string
example60

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

start_time
string(timestamp)
example2020-01-01 12:00:00

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(timestamp)
example2020-01-01 12:00:00

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
example65512

The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call. This is only sent if status is completed.

Example Response

{
   "count": 100,
   "page_size": 10,
   "record_index": 0,
   "_links": {
      "self": {
         "href": "/calls?page_size=10&record_index=20&order=asc"
      },
      "first": {
         "href": "/calls?page_size=10&record_index=20&order=asc"
      },
      "last": {
         "href": "/calls?page_size=10&record_index=20&order=asc"
      },
      "next": {
         "href": "/calls?page_size=10&record_index=20&order=asc"
      },
      "prev": {
         "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": "14155550100",
               "dtmfAnswer": "p*123#"
            },
            "from": {
               "type": "phone",
               "number": "447700900001"
            },
            "status": "completed",
            "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

posthttps://api.nexmo.com/v1/calls/

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Request Body
Content Type
application/json

One Of
ncco
array
Required

The Nexmo Call Control Object to use for this call.

to
array
Required
One Of
type
string
Required
examplephone

The type of connection. Must be phone

number
string
Required
Min7
Max15
example14155550100

The phone number to connect to

dtmfAnswer
string
examplep*123#

Provide DTMF digits to send when the call is answered

from
object

Connect to a Phone (PSTN) number. This property is mutually exclusive with random_from_number: you must specify one (from) or the other (random_from_number: true).

type
string
Required
examplephone

The type of connection. Must be phone

number
string
Required
Min7
Max15
example14155550100

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. This property is mutually exclusive with from: you must specify one (random_from_number: true) or the other (from).

event_url
array

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
DefaultPOST

The HTTP method used to send event information to event_url.

Must be one of:POSTGET
machine_detection
string
examplecontinue

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:continuehangup
advanced_machine_detection
object

Configure the behavior of Vonage's advanced machine detection. Overrides machine_detection if both are set. Note that this is a beta feature which will be chargeable; exact rates can be found on the Voice API Pricing page under 'Programmable Features'.

behavior
string

When hangup is used, the call will be terminated if a machine is detected. When continue is used, the call will continue even if a machine is detected.

Must be one of:continuehangup
mode
string
Defaultdetect

Detect if machine answered and sends a human or machine status in the webhook payload. The modes are as follows:

  • default - async mode, the next NCCO action will be processed immediately in parallel with machine detection, the application will receive both machine detection status and beep events and can reply with new NCCO to any of them;

  • detect - sync mode, the next NCCO action will be processed only when machine detection is finished, the application will receive only machine detection status event;

  • detect_beep - sync mode, the next NCCO action will be processed only when machine detection is finished, the application will receive only a beep event.

Must be one of:defaultdetectdetect_beep
beep_timeout
integer
Min45
Max120

Maximum time in seconds Vonage should wait for a machine beep to be detected. A machine event with sub_state set to beep_timeout will be sent if the timeout is exceeded.

length_timer
integer
Min1
Max7200
Default7200

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

ringing_timer
integer
Min1
Max120
Default60

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

Example Request

{
   "ncco": [
      {
         "action": "talk",
         "text": "Hello World"
      }
   ],
   "to": [
      {
         "type": "phone",
         "number": "14155550100",
         "dtmfAnswer": "p*123#"
      }
   ],
   "from": {
      "type": "phone",
      "number": "14155550100"
   },
   "random_from_number": false,
   "event_url": [
      "https://example.com/event"
   ],
   "event_method": "POST",
   "machine_detection": "continue",
   "advanced_machine_detection": {
      "behavior": "continue",
      "mode": "default",
      "beep_timeout": 45
   },
   "length_timer": 7200,
   "ringing_timer": 60
}

Responses
Content Type
application/json

Created

uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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
examplecompleted

The status of the call. See possible values

direction
string
exampleoutbound

Possible values are outbound or inbound

Must be one of:outboundinbound
conversation_uuid
string(uuid)
exampleCON-f972836a-550f-45fa-956c-12a2ab5b7d22

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

Example Response

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

Get detail of a specific call

Get detail of a specific call

gethttps://api.nexmo.com/v1/calls/:uuid

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call

Responses
Content Type
application/json

Ok

_links
object
self
object
href
string
example/calls/63f61863-4a51-4f6b-86e1-46edebcf9356
uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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(uuid)
exampleCON-f972836a-550f-45fa-956c-12a2ab5b7d22

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

to
One Of
type
string
Required
examplephone

The type of connection. Must be phone

number
string
Required
Min7
Max15
example14155550100

The phone number to connect to

dtmfAnswer
string
examplep*123#

Provide DTMF digits to send when the call is answered

from
object

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

type
string
examplephone
number
string
example447700900001
status
string
examplecompleted

The status of the call. See possible values

direction
string
exampleoutbound

Possible values are outbound or inbound

Must be one of:outboundinbound
rate
string
example0.39

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

price
string
example23.40

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

duration
string
example60

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

start_time
string(timestamp)
example2020-01-01 12:00:00

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(timestamp)
example2020-01-01 12:00:00

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
example65512

The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call. This is only sent if status is completed.

Example Response

{
   "_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": "14155550100",
      "dtmfAnswer": "p*123#"
   },
   "from": {
      "type": "phone",
      "number": "447700900001"
   },
   "status": "completed",
   "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

puthttps://api.nexmo.com/v1/calls/:uuid

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call

Request Body
Content Type
application/json

One Of
action
string
Required
exampletransfer

Transfer the call to a new NCCO

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

Always ncco

ncco
array
Required

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

Example Request

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

Responses

No Content

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

puthttps://api.nexmo.com/v1/calls/:uuid/stream

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Request Body
Content Type
application/json

stream_url
array
Required
loop
integer
Default1

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

level
string
Default0
example0.4

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

Example Request

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

Responses
Content Type
application/json

Ok

message
string
exampleStream started

Description of the action taken

uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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 Response

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

deletehttps://api.nexmo.com/v1/calls/:uuid/stream

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Responses
Content Type
application/json

Ok

message
string
exampleStream stopped

Description of the action taken

uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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 Response

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

puthttps://api.nexmo.com/v1/calls/:uuid/talk

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Request Body
Content Type
application/json

text
string
Required
exampleHello. How are you today?

The text to read

language
string
Defaulten-US

The language to use

Must be one of:arca-EScmn-CNcmn-TWcs-CZcy-GBda-DKde-DEel-GRen-AUen-GBen-GB-WLSen-INen-USen-ZAes-ESes-MXes-USeu-ESfi-FIfil-PHfr-CAfr-FRhe-ILhi-INhu-HUid-IDis-ISit-ITja-JPko-KRnb-NOnl-NLno-NOpl-PLpt-BRpt-PTro-ROru-RUsk-SKsv-SEth-THtr-TRuk-UAvi-VNyue-CN
style
integer

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

premium
boolean
Defaultfalse
exampletrue

Set to true to use the premium version of the specified style if available, otherwise the standard version will be used. You can find more information about Premium Voices in the Text-To-Speech guide.

voice_name
string
DefaultKimberly

DEPRECATED The voice & language to use

Must be one of:AditiAgnieszkaAlvaAmyAstridBiancaBrianCarlaCarmenCarmitCatarinaCelineCemChantalChipmunkConchitaCristianoDamayantiDoraEmmaEmparEnriqueEricEwaFelipeFilizGeraintGiorgioGwynethHansHenrikInesIoanaIvetaIvyJacekJanJenniferJoanaJoannaJoeyJordiJustinKanyaKarlKendraKimberlyLailaLauraLeaLekhaLivLotteLuciaLucianaMadsMagedMajaMariskaMarleneMathieuMatthewMaximMei-JiaMelinaMiaMiguelMirenMizukiMontserratNajaNicoleNikosNoraOskarPenelopeRaveenaRicardoRubenRussellSalliSatuSeoyeonSin-JiSoraTakumiTarikTatyanaTessaTian-TianVickiVitoriaYeldaZeinaZhiyuZuzana
loop
integer
Default1

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

level
string
Default0
example0.4

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.

Example Request

{
   "text": "Hello. How are you today?",
   "language": "ar",
   "style": 0,
   "premium": true,
   "voice_name": "Aditi",
   "loop": 1,
   "level": "0.4"
}

Responses
Content Type
application/json

Ok

message
string
exampleTalk started

Description of the action taken

uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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 Response

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

Stop text to speech in a call

Stop text to speech in a call

deletehttps://api.nexmo.com/v1/calls/:uuid/talk

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Responses
Content Type
application/json

Ok

message
string
exampleTalk stopped

Description of the action taken

uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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 Response

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

DTMF

Send and subscribe to DTMF tones in an active call

Available Operations

Play DTMF tones into a call

Play DTMF tones into a call

puthttps://api.nexmo.com/v1/calls/:uuid/dtmf

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Request Body
Content Type
application/json

digits
string
example1713

The digits to send

Example Request

{
   "digits": 1713
}

Responses
Content Type
application/json

Ok

message
string
exampleDTMF sent

Description of the action taken

uuid
string(uuid)
example63f61863-4a51-4f6b-86e1-46edebcf9356

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 Response

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

Subscribe to real-time DTMF events

Register a listener to receive asynchronous DTMF inputs from a call. This is only applicable to Input NCCO events with the mode set to asynchronous. The payload delivered to this URL will be an Input webhook event with a single DTMF digit every time the callee enters DTMF into the call.

puthttps://api.nexmo.com/v1/calls/:uuid/input/dtmf

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Request Body
Content Type
application/json

event_url
array
example[ "https://example.com/ivr" ]

The URL (wrapped in an array) to send DTMF events to, as a POST request.

Example Request

{
   "event_url": [
      "https://example.com/ivr"
   ]
}

Responses

OK

Stop receiving real-time DTMF events

Removes the registered DTMF listener.

deletehttps://api.nexmo.com/v1/calls/:uuid/input/dtmf

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Path Parameters

uuid
string
Required

UUID of the Call Leg

Responses

OK