Voice API BETA

Version 2

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 Specification
Available Operations

Create an outbound call

Create an outbound Call

posthttps://api.nexmo.com/v2/calls/

Authentication

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>

Request Body
Content Type
application/json

One Of
ncco
array
Required

The Nexmo Call Control Object to use for this call.

to
array
Required
One Of
type
string
Required
examplephone

The type of connection. Must be phone

number
string
Required
Min7
Max15
example14155550100

The phone number to connect to

dtmfAnswer
string
examplep*123#

Provide DTMF digits to send when the call is answered

shaken
string
exampleeyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt="shaken"

For Vonage customers who are required by the FCC to sign their own calls to the USA, we allow you to place Voice API calls with your own signature. This feature is available by request only. Please be aware calls with an invalid signature will be rejected. For more information please contact us. In this option, you must place the STIR/SHAKEN Identity Header content that Vonage must use for this call. Expected format is composed of the JWT with the header, payload and signature, an info parameter with a link for the certificate, the algorithm (alg) parameter indicating which encryption type was used and the passport type (ppt) which should be shaken.

from
object
Required

Connect to a Phone (PSTN) number. This property is mutually exclusive with random_from_number: you must specify one (from) or the other (random_from_number: true).

type
string
Required
examplephone

The type of connection. Must be phone.

number
string
Required
example14155550100

The phone number to connect to. It can be either an E.164 formatted number or a SIP URI.

event_url
array

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
DefaultPOST

The HTTP method used to send event information to event_url.

Must be one of:POSTGET
machine_detection
string
examplecontinue

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.

Must be one of:continuehangup
length_timer
integer
Min1
Max7200
Default7200

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

ringing_timer
integer
Min1
Max120
Default60

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

Example Request

{
   "ncco": [
      {
         "action": "talk",
         "text": "Hello World"
      }
   ],
   "to": [
      {
         "type": "phone",
         "number": "14155550100",
         "dtmfAnswer": "p*123#",
         "shaken": "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt=\"shaken\""
      }
   ],
   "from": {
      "type": "phone",
      "number": "14155550100"
   },
   "event_url": [
      "https://example.com/event"
   ],
   "event_method": "POST",
   "machine_detection": "continue",
   "length_timer": 7200,
   "ringing_timer": 60
}

Responses
Content Type
application/json

Accepted

Example Response

{}

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.

posthttps://example.com/webhooks/event_url

Request Body
Content Type
application/json

from
string
example14155550100

The source of the call

to
string
example14155550105 / jamie

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

uuid
string
example63f61863-4a51-4f6b-86e1-46edebcf9356

The UUID of the Conversion that the event relates to

conversation_uuid
string
exampleCON-f972836a-550f-45fa-956c-12a2ab5b7d22

The UUID of the call leg that the event relates to

client_ref
string
exampleclient-ref

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

status
string
examplestarted
direction
string
exampleoutbound

Possible values are outbound or inbound

Must be one of:outboundinbound
timestamp
string(date-time)
example2018-01-12T15:01:55.315Z

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-12T15:01:55.315Z"
}

Responses

Your server returns this code if it accepts the callback