Available Operations
 
 

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)

Available Operations:

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

type
string | Required

The type of connection. Must be app

user
string | Required

The username to connect to

from
object | Required

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

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

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 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
length_timer
integer | Min: 1 | Max: 7200

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

ringing_timer
integer | Min: 1 | Max: 120

Set the number of seconds that elapse before Nexmo 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:
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

type
string | Required

The type of connection. Must be app

user
string | Required

The username to connect to

from
object | Required

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

answer_method
string

The HTTP method used to send event information to answer_url.

Must be one of: POST or GET
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

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 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
length_timer
integer | Min: 1 | Max: 7200

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

ringing_timer
integer | Min: 1 | Max: 120

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

Responses

202 Accepted

Example Request » With NCCO

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

Example Request » With Answer URL

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

Example Responses

202
{}

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

from
string

The source of the call

to
string

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

uuid
string

The UUID of the Conversion that the event relates to

conversation_uuid
string

The UUID of the call leg that the event relates to

client_ref
string

The client reference number that the event relates to. This is returned for outbound IP calls instead of a UUID.

status
string
direction
string

Possible values are outbound or inbound

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

Example Payload

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