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)
Create an outbound Call
POST
https://api.nexmo.com/v2/calls
Host
https://api.nexmo.com
POST
/v2/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
The type of connection. Must be app
The username to connect to
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
The type of connection. Must be app
The username to connect to
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
.
{
"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"
}
{}
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
The source of the call
The destination endpoint. This can be a PSTN, SIP, IP or Websocket address
The UUID of the Conversion that the event relates to
The UUID of the call leg that the event relates to
The client reference number that the event relates to. This is returned for outbound IP calls instead of a UUID.
Possible values are outbound
or inbound
outbound
or inbound
{
"from": 14155550100,
"to": "14155550105 / jamie",
"uuid": "63f61863-4a51-4f6b-86e1-46edebcf9356",
"conversation_uuid": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
"client_ref": "client-ref",
"status": "started",
"direction": "outbound",
"timestamp": "2018-01-12 15:01:55 +0000"
}