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

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.

array | Required

Choose an option:

Connect to a Phone (PSTN) number
Connect to a SIP Endpoint
Connect to a Websocket
Connect to a VBC extension

string | Required

The type of connection. Must be phone

string | Required

The phone number to connect to

string

Provide DTMF digits to send when the call is answered

string | Required

The type of connection. Must be sip

string

The SIP URI to connect to

string | Required

The type of connection. Must be websocket

string | Required

Connect to a Websocket

Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000

string

Connect to a Websocket

object

Details of the Websocket you want to connect to

string

This is an example header. You can provide any headers you may need

string | Required

The type of connection. Must be vbc

string | Required

Connect to a VBC extension

from

object | Required

Connect to a Phone (PSTN) number

string | Required

The type of connection. Must be phone

string | Required

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 in_progress.

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.

array | Required

Choose an option:

Connect to a Phone (PSTN) number
Connect to a SIP Endpoint
Connect to a Websocket
Connect to a VBC extension

string | Required

The type of connection. Must be phone

string | Required

The phone number to connect to

string

Provide DTMF digits to send when the call is answered

string | Required

The type of connection. Must be sip

string

The SIP URI to connect to

string | Required

The type of connection. Must be websocket

string | Required

Connect to a Websocket

Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000

string

Connect to a Websocket

object

Details of the Websocket you want to connect to

string

This is an example header. You can provide any headers you may need

string | Required

The type of connection. Must be vbc

string | Required

Connect to a VBC extension

from

object | Required

Connect to a Phone (PSTN) number

string | Required

The type of connection. Must be phone

string | Required

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 in_progress.

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

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