Voice API BETA

Versión 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)

Descargar la especificación OpenAPI
Operaciones disponibles

Create an outbound call

Create an outbound Call

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

Autenticación

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>

Cuerpo de la solicitud
Tipo de contenido
application/json

Uno de
ncco
array
Requerido

The Nexmo Call Control Object to use for this call.

to
array
Requerido
Uno de
type
string
Requerido
ejemplophone

The type of connection. Must be phone

number
string
Requerido
Min7
Max15
ejemplo14155550100

The phone number to connect to

dtmfAnswer
string
ejemplop*123#

Provide DTMF digits to send when the call is answered

shaken
string
ejemploeyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.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
Requerido

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
Requerido
ejemplophone

The type of connection. Must be phone.

number
string
Requerido
ejemplo14155550100

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
Por defectoPOST

The HTTP method used to send event information to event_url.

Debe ser uno de:POSTGET
machine_detection
string
ejemplocontinue

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.

Debe ser uno de:continuehangup
length_timer
integer
Min1
Max7200
Por defecto7200

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

ringing_timer
integer
Min1
Max120
Por defecto60

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

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

Accepted

Ejemplo Respuesta

{}

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

Cuerpo de la solicitud
Tipo de contenido
application/json

from
string
ejemplo14155550100

The source of the call

to
string
ejemplo14155550105 / jamie

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

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

The UUID of the Conversion that the event relates to

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

The UUID of the call leg that the event relates to

client_ref
string
ejemploclient-ref

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

status
string
ejemplostarted
direction
string
ejemplooutbound

Possible values are outbound or inbound

Debe ser uno de:outboundinbound
timestamp
string(date-time)
ejemplo2018-01-12T15:01:55.315Z

Ejemplo Carga útil

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

Respuestas

Your server returns this code if it accepts the callback