Voice API BETA

This is the beta version of the Voice API. Calls created with v2 must be managed using v1 endpoints.

Voice v2 is provided to allow users to create IP calls. If you do not have this requirement we recommend that you stay on v1 for now.

This API may break backwards compatibility at short notice (60 days)

Download OpenAPI 3 Definition
Improve this specification

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/v2/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

 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 an App User
Key Description Example Default
type
string

The type of connection. Must be app

 app None
user
string

The username to connect to

 jamie 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 callback

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

Call Placed Callback Callback

Each time a leg is created you'll receive a webhook containing the leg ID (uuid) and the conversation ID (conversation_uuid) in addition to the to and from addresses.

POST https://example.com /webhooks/event_url

Request body application/json

Key Description Example
from
string

The source of the call

 14155550100
to
string

The destination endpoint. This can be a PSTN, SIP, IP or Websocket address

 14155550105 / jamie
uuid
string

The UUID of the Conversion that the event relates to

 63f61863-4a51-4f6b-86e1-46edebcf9356
conversation_uuid
string

The UUID of the call leg that the event relates to

 CON-f972836a-550f-45fa-956c-12a2ab5b7d22
status
string

None

 started
direction
string

Possible values are outbound or inbound


One of: outbound or inbound 		outbound
timestamp
string | (date-time)

None

 2018-01-12 15:01:55 UTC
Request model
{
  "from": 14155550100,
  "to": "14155550105 / jamie",
  "uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
  "conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
  "status": "started",
  "direction": "outbound",
  "timestamp": "2018-01-12T15:01:55.315Z"
}