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)

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