Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
216 lines (206 sloc) 7.21 KB
---
openapi: 3.0.0
info:
version: 2.2.2
title: Voice API BETA
description: |
This is the *beta* version of the Voice API. Calls created with v2 must be managed
using [v1 endpoints](/api/voice).
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)
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:
"$ref": "voice.yml#/paths/~1/post/summary"
description:
"$ref": "voice.yml#/paths/~1/post/description"
operationId:
"$ref": "voice.yml#/paths/~1/post/operationId"
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": "voice.yml#/components/schemas/EndpointPhoneTo"
- "$ref": "voice.yml#/components/schemas/EndpointSip"
- "$ref": "voice.yml#/components/schemas/EndpointWebsocket"
- "$ref": "voice.yml#/components/schemas/EndpointVBCExtension"
- "$ref": "voice.yml#/components/schemas/EndpointApp"
from:
"$ref": "voice.yml#/components/schemas/EndpointPhoneFrom"
event_url:
description: |
**Required** unless `event_url` is configured at the application
level, see [Create an Application](/api/application.v2#createApplication)
The webhook endpoint where call progress events are
sent to. For more information about the values sent, see
[Event webhook](/voice/voice-api/webhook-reference#event-webhook).
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.
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.
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