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)

Télécharger la spécification OpenAPI
Opérations disponibles

Create an outbound call

Create an outbound Call

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

Authentification

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>

Corps de la demande
Type de contenu
application/json

L'un des
ncco
array
Exigée

The Nexmo Call Control Object to use for this call.

to
array
Exigée
L'un des
type
string
Exigée
exemplephone

The type of connection. Must be phone

number
string
Exigée
Min7
Max15
exemple14155550100

The phone number to connect to

dtmfAnswer
string
exemplep*123#

Provide DTMF digits to send when the call is answered

shaken
string
exempleeyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.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
Exigée

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
Exigée
exemplephone

The type of connection. Must be phone.

number
string
Exigée
exemple14155550100

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
DéfautPOST

The HTTP method used to send event information to event_url.

Il doit s'agir de l'un d'entre eux :POSTGET
machine_detection
string
exemplecontinue

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.

Il doit s'agir de l'un d'entre eux :continuehangup
length_timer
integer
Min1
Max7200
Défaut7200

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

ringing_timer
integer
Min1
Max120
Défaut60

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

Exemple Demande

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

Réponses
Type de contenu
application/json

Accepted

Exemple Réponse

{}

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

Corps de la demande
Type de contenu
application/json

from
string
exemple14155550100

The source of the call

to
string
exemple14155550105 / jamie

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

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

The UUID of the Conversion that the event relates to

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

The UUID of the call leg that the event relates to

client_ref
string
exempleclient-ref

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

status
string
exemplestarted
direction
string
exempleoutbound

Possible values are outbound or inbound

Il doit s'agir de l'un d'entre eux :outboundinbound
timestamp
string(date-time)
exemple2018-01-12T15:01:55.315Z

Exemple Charge utile

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

Réponses

Your server returns this code if it accepts the callback