{ "openapi": "3.0.0", "info": { "version": "2.2.2", "title": "Voice API BETA", "x-metaTitle": "Voice v2 API Reference (BETA) | Vonage API Documentation", "description": "This is the *beta* version of the Voice API. Calls created with v2 must be managed\nusing [v1 endpoints](/api/voice).\n\nVoice v2 is provided to allow users to create IP calls. If you do not have this requirement\nwe recommend that you stay on v1 for now.\n\n> This API may break backwards compatibility at short notice (60 days)\n", "x-metaDescription": "Our Voice v2 API Reference includes details for Version 2.0 of the Vonage Voice API, now in BETA. Learn more in Vonage's API documentation.", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.nexmo.com/" } }, "servers": [ { "url": "https://api.nexmo.com/v2/calls" } ], "paths": { "/": { "post": { "security": [ { "bearerAuth": [] } ], "summary": "Create an outbound call", "description": "Create an outbound Call", "operationId": "createCall", "requestBody": { "$ref": "#/components/requestBodies/CreateCallRequestBody" }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "callbacks": { "delivery-receipt": { "{$request.body#/event_url}": { "post": { "summary": "Call Placed Callback", "operationId": "call-placed", "x-example-path": "/webhooks/event_url", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallPlacedWebhook" } } } }, "responses": { "200": { "description": "Your server returns this code if it accepts the callback" } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "requestBodies": { "CreateCallRequestBody": { "description": "Call Details", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateCallRequestNcco" }, { "$ref": "#/components/schemas/CreateCallRequestAnswerUrl" } ] } } } } }, "schemas": { "CreateCallRequestBaseV2": { "type": "object", "required": [ "to", "from" ], "properties": { "to": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/EndpointPhoneTo" }, { "$ref": "#/components/schemas/EndpointSip" }, { "$ref": "#/components/schemas/EndpointWebsocket" }, { "$ref": "#/components/schemas/EndpointVBCExtension" }, { "$ref": "#/components/schemas/EndpointApp" } ] } }, "from": { "$ref": "#/components/schemas/EndpointPhoneFrom" }, "event_url": { "description": "**Required** unless `event_url` is configured at the application\nlevel, see [Create an Application](/api/application.v2#createApplication)\n\nThe webhook endpoint where call progress events are\nsent to. For more information about the values sent, see\n[Event webhook](/voice/voice-api/webhook-reference#event-webhook).\n", "type": "array", "x-nexmo-developer-collection-description-shown": true, "example": [ "https://example.com/event" ], "items": { "type": "string", "format": "uri" } }, "event_method": { "description": "The HTTP method used to send event information to `event_url`.", "type": "string", "default": "POST", "enum": [ "POST", "GET" ] }, "machine_detection": { "description": "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.", "type": "string", "enum": [ "continue", "hangup" ], "example": "continue" }, "length_timer": { "description": "Set the number of seconds that elapse before Vonage hangs up after the call state changes to answered.", "minimum": 1, "maximum": 7200, "default": 7200, "type": "integer" }, "ringing_timer": { "description": "Set the number of seconds that elapse before Vonage hangs up after the call state changes to `ringing`.", "minimum": 1, "maximum": 120, "default": 60, "type": "integer" } } }, "CreateCallRequestNcco": { "allOf": [ { "title": "With NCCO", "required": [ "ncco" ] }, { "properties": { "ncco": { "description": "The [Nexmo Call Control Object](/voice/voice-api/ncco-reference) to use for this call.\n", "type": "array", "x-nexmo-developer-collection-description-shown": true, "example": [ { "action": "talk", "text": "Hello World" } ], "items": { "type": "object" } } } }, { "$ref": "#/components/schemas/CreateCallRequestBaseV2" } ] }, "CreateCallRequestAnswerUrl": { "allOf": [ { "title": "With Answer URL", "required": [ "answer_url" ] }, { "properties": { "answer_url": { "description": "The webhook endpoint where you provide the [Nexmo Call Control Object](/voice/voice-api/ncco-reference) that governs this call.\n", "type": "array", "x-nexmo-developer-collection-description-shown": true, "example": [ "https://example.com/answer" ], "items": { "type": "string" } }, "answer_method": { "description": "The HTTP method used to send event information to answer_url.", "type": "string", "default": "GET", "enum": [ "POST", "GET" ] } } }, { "$ref": "#/components/schemas/CreateCallRequestBaseV2" } ] }, "CallPlacedWebhook": { "properties": { "from": { "type": "string", "description": "The source of the call", "example": 14155550100 }, "to": { "type": "string", "description": "The destination endpoint. This can be a PSTN, SIP, IP or Websocket address", "example": "14155550105 / jamie" }, "uuid": { "type": "string", "description": "The UUID of the Conversion that the event relates to", "example": "63f61863-4a51-4f6b-86e1-46edebcf9356" }, "conversation_uuid": { "type": "string", "description": "The UUID of the call leg that the event relates to", "example": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22" }, "client_ref": { "type": "string", "description": "The client reference number that the event relates to. This is returned for outbound IP calls instead of a UUID.", "example": "client-ref" }, "status": { "type": "string", "example": "started" }, "direction": { "type": "string", "description": "Possible values are `outbound` or `inbound`", "example": "outbound", "enum": [ "outbound", "inbound" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2018-01-12T15:01:55.315Z" } } }, "AddressE164": { "description": "The phone number to connect to", "type": "string", "minLength": 7, "maxLength": 15, "example": "14155550100", "pattern": "\\d{7,15}" }, "EndpointPhoneTo": { "type": "object", "description": "Connect to a Phone (PSTN) number", "required": [ "number", "type" ], "properties": { "type": { "type": "string", "example": "phone", "description": "The type of connection. Must be `phone`" }, "number": { "$ref": "#/components/schemas/AddressE164" }, "dtmfAnswer": { "description": "Provide [DTMF digits](https://developer.nexmo.com/voice/voice-api/concepts/dtmf) to send when the call is answered", "type": "string", "example": "p*123#" }, "shaken": { "description": "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.", "type": "string", "example": "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=;alg=ES256;ppt=\"shaken\"" } } }, "AddressSip": { "description": "The SIP URI to connect to", "type": "string", "minLength": 1, "maxLength": 50, "example": "sip:rebekka@sip.example.com" }, "EndpointSip": { "type": "object", "description": "Connect to a SIP Endpoint", "required": [ "type", "uri" ], "properties": { "type": { "description": "The type of connection. Must be `sip`", "type": "string", "example": "sip" }, "uri": { "$ref": "#/components/schemas/AddressSip" }, "headers": { "description": "Metadata to include in the request. The headers are transmitted as part of the SIP INVITE as `X-key: value` headers.", "type": "object", "example": { "location": "New York City", "occupation": "developer" } }, "standard_headers": { "description": "Standard SIP INVITE headers. Unlike the `headers` property, these are not prepended with `X-`.", "type": "object", "required": [ "User-to-User" ], "properties": { "User-to-User": { "description": "Transmit user-to-user information if supported by the CC / PBX vendor, as per [RFC 7433](https://datatracker.ietf.org/doc/html/rfc7433).", "type": "string" } } } } }, "AddressWebsocket": { "type": "string", "minLength": 1, "example": "wss://example.com/socket" }, "EndpointWebsocket": { "type": "object", "description": "Connect to a Websocket", "required": [ "type", "content-type" ], "properties": { "type": { "description": "The type of connection. Must be `websocket`", "type": "string", "example": "websocket" }, "uri": { "$ref": "#/components/schemas/AddressWebsocket" }, "content-type": { "type": "string", "example": "audio/l16;rate=16000", "enum": [ "audio/l16;rate=8000", "audio/l16;rate=16000", "audio/l16;rate=24000" ] }, "headers": { "description": "Details of the Websocket you want to connect to", "type": "object", "properties": { "customer_id": { "type": "string", "example": "ABC123", "description": "This is an example header. You can provide any headers you may need" } } }, "authorization": { "description": "Optional configuration defining how the Authorization HTTP header is set in the WebSocket opening handshake.", "type": "object", "properties": { "type": { "type": "string", "default": "vonage", "example": "vonage", "description": "Defines the authorization mode. \"vonage\" – the Voice API includes the same JWT used for signed webhooks in the Authorization header ('Bearer {JWT}'). \"custom\" – a developer-supplied Authorization header value is sent verbatim.", "enum": [ "vonage", "custom" ] }, "value": { "type": "string", "example": "Bearer abc123", "description": "Required only when authorization.type = \"custom\". The raw header value to include, e.g. \"Bearer abc123\" or \"ApiKey X9Z...\". Ignored when authorization.type = \"vonage\"." } } } } }, "EndpointVBCExtension": { "type": "object", "description": "Connect to a VBC extension", "required": [ "type", "extension" ], "properties": { "type": { "type": "string", "example": "vbc", "description": "The type of connection. Must be `vbc`" }, "extension": { "type": "string", "example": "1234" } } }, "EndpointApp": { "type": "object", "description": "Connect to an App User", "required": [ "type", "user" ], "properties": { "type": { "type": "string", "example": "app", "description": "The type of connection. Must be `app`" }, "user": { "type": "string", "example": "jamie", "description": "The username to connect to" } } }, "EndpointPhoneFrom": { "type": "object", "description": "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`).", "required": [ "number", "type" ], "properties": { "type": { "type": "string", "example": "phone", "description": "The type of connection. Must be `phone`." }, "number": { "type": "string", "example": "14155550100", "description": "The phone number to connect to. It can be either an E.164 formatted number or a SIP URI." } } } } } }