Voice API BETA

Versão 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)

Baixar a especificação OpenAPI
Operações disponíveis

Create an outbound call

Create an outbound Call

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Seu token JSON da Web.
Saiba mais sobre os JWTs

Headers

Bearer <JWT>

Corpo da solicitação
Tipo de conteúdo
application/json

Um dos
ncco
array
Obrigatório

The Nexmo Call Control Object to use for this call.

to
array
Obrigatório
Um dos
type
string
Obrigatório
exemplophone

The type of connection. Must be phone

number
string
Obrigatório
Mín.7
Max15
exemplo14155550100

The phone number to connect to

dtmfAnswer
string
exemplop*123#

Provide DTMF digits to send when the call is answered

shaken
string
exemploeyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.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
Obrigatório

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
Obrigatório
exemplophone

The type of connection. Must be phone.

number
string
Obrigatório
exemplo14155550100

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
PadrãoPOST

The HTTP method used to send event information to event_url.

Deve ser uma das seguintes opções:POSTGET
machine_detection
string
exemplocontinue

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.

Deve ser uma das seguintes opções:continuehangup
length_timer
integer
Mín.1
Max7200
Padrão7200

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

ringing_timer
integer
Mín.1
Max120
Padrão60

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

Exemplo Solicitação

{
   "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
}
{
   "ncco": [
      {
         "action": "talk",
         "text": "Hello World"
      }
   ],
   "to": [
      {
         "type": "phone",
         "number": "14155550100"
      }
   ],
   "from": {
      "type": "phone",
      "number": "14155550100"
   }
}

Respostas
Tipo de conteúdo
application/json

Accepted

Exemplo Resposta

{}

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

Corpo da solicitação
Tipo de conteúdo
application/json

from
string
exemplo14155550100

The source of the call

to
string
exemplo14155550105 / jamie

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

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

The UUID of the Conversion that the event relates to

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

The UUID of the call leg that the event relates to

client_ref
string
exemploclient-ref

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

status
string
exemplostarted
direction
string
exemplooutbound

Possible values are outbound or inbound

Deve ser uma das seguintes opções:outboundinbound
timestamp
string(date-time)
exemplo2018-01-12T15:01:55.315Z

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

Respostas

Your server returns this code if it accepts the callback