/api-specification

Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
Raw Blame History
840 lines (835 sloc) 26.4 KB
---
openapi: 3.0.0
info:
version: 1.0.1
title: Voice API
description: The Voice API lets you create outboud calls, control in progress calls
and get information about historical calls.
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url: 'https://developer.nexmo.com/'
servers:
- url: https://api.nexmo.com/v1
paths:
"/calls":
post:
security:
- bearerAuth: []
summary: Create an outbound call
description: Create an outbound Call
operationId: createCall
requestBody:
description: Call Details
content:
application/json:
schema:
required:
- to
- from
- event_url
properties:
to:
type: array
items:
oneOf:
- "$ref": "#/components/schemas/EndpointPhone"
- "$ref": "#/components/schemas/EndpointSip"
- "$ref": "#/components/schemas/EndpointWebsocket"
from:
"$ref": "#/components/schemas/EndpointPhone"
ncco:
description: |
**Required** unless `answer_url` is provided.
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: string
answer_url:
description: |
**Required** unless `ncco` is provided.
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
event_url:
description: The webhook endpoint where call progress events are
sent to. For more information about the values sent, see callback
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 Nexmo detects that the
call is answered by voicemail. If Continue Nexmo sends an HTTP
request to event_url with the Call event machine. hangup end
the call
type: string
enum:
- continue
- hangup
example: continue
length_timer:
description: Set the number of seconds that elapse before Nexmo
hangs up after the call state changes to in_progress.
minimum: 1
maximum: 7200
default: 7200
type: integer
ringing_timer:
description: Set the number of seconds that elapse before Nexmo
hangs up after the call state changes to ‘ringing’.
minimum: 1
maximum: 120
default: 60
type: integer
responses:
'201':
description: Created
content:
application/json:
schema:
properties:
uuid:
$ref: '#/components/schemas/uuid'
status:
$ref: '#/components/schemas/status'
direction:
$ref: '#/components/schemas/direction'
conversation_uuid:
$ref: '#/components/schemas/conversation_uuid'
get:
security:
- bearerAuth: []
summary: Get details of your calls
description: Get details of your calls
operationId: getCalls
parameters:
- name: status
in: query
description: Filter by call status
schema:
type: string
example: started
enum:
- started
- ringing
- answered
- machine
- completed
- busy
- cancelled
- failed
- rejected
- timeout
- unanswered
- name: date_start
in: query
description: Return the records that occurred after this point in time
schema:
type: string
format: date-time
example: 2016-11-14T07:45:14Z
- name: date_end
in: query
description: Return the records that occurred before this point in time
schema:
type: string
format: date-time
example: 2016-11-14T07:45:14Z
- name: page_size
in: query
description: Return this amount of records in the response
schema:
type: integer
maximum: 100
minimum: 1
default: 10
- name: record_index
in: query
description: Return calls from this index in the response
schema:
type: integer
default: 0
- name: order
in: query
description: Either ascending or descending order.
schema:
type: string
default: asc
enum:
- asc
- desc
- name: conversation_uuid
in: query
description: Return all the records associated with a specific conversation.
schema:
$ref: '#/components/schemas/conversation_uuid'
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
count:
type: integer
title: The total number of records returned by your request.
example: 100
page_size:
type: integer
title: The amount of records returned in this response.
example: 10
record_index:
type: integer
title: The `record_index` used in your request.
example: 0
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
title: Link to the object
example: "/calls?page_size=10&record_index=20&order=asc"
_embedded:
description: >-
A list of call objects. See the
[get details of a specific call](#getCall)
response fields for a description of the nested objects
type: object
properties:
calls:
type: array
items:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
title: The Link to the Call Object
example: "/calls/63f61863-4a51-4f6b-86e1-46edebcf9356"
uuid:
$ref: '#/components/schemas/uuid'
conversation_uuid:
$ref: '#/components/schemas/conversation_uuid'
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
status:
$ref: '#/components/schemas/status'
direction:
$ref: '#/components/schemas/direction'
rate:
$ref: '#/components/schemas/rate'
price:
$ref: '#/components/schemas/price'
duration:
$ref: '#/components/schemas/duration'
start_time:
$ref: '#/components/schemas/start_time'
end_time:
$ref: '#/components/schemas/end_time'
network:
$ref: '#/components/schemas/network'
"/calls/{uuid}":
parameters:
- in: path
name: uuid
schema:
type: string
required: true
description: UUID of the Call
example: 63f61863-4a51-4f6b-86e1-46edebcf9356
get:
security:
- bearerAuth: []
summary: Get detail of a specific call
description: Get detail of a specific call
operationId: getCall
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
title: Link to the object
example: "/calls?page_size=10&record_index=20&order=asc"
uuid:
$ref: '#/components/schemas/uuid'
conversation_uuid:
$ref: '#/components/schemas/conversation_uuid'
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
status:
$ref: '#/components/schemas/status'
direction:
$ref: '#/components/schemas/direction'
rate:
$ref: '#/components/schemas/rate'
price:
$ref: '#/components/schemas/price'
duration:
$ref: '#/components/schemas/duration'
start_time:
$ref: '#/components/schemas/start_time'
end_time:
$ref: '#/components/schemas/end_time'
network:
$ref: '#/components/schemas/network'
put:
security:
- bearerAuth: []
summary: Modify an in progress call
description: Modify an in progress call
operationId: updateCall
requestBody:
required: true
content:
application/json:
schema:
required:
- action
properties:
action:
type: string
example: mute
enum:
- hangup
- mute
- unmute
- earmuff
- unearmuff
- transfer
destination:
type: object
description: Required when action is `transfer`
properties:
type:
type: string
example: ncco
enum:
- ncco
url:
x-nexmo-developer-collection-description-shown: true
example: '["https://example.com/ncco.json"]'
type: array
items:
type: string
responses:
'204':
description: No Content
"/calls/{uuid}/stream":
parameters:
- in: path
name: uuid
schema:
type: string
required: true
description: UUID of the Call
example: 63f61863-4a51-4f6b-86e1-46edebcf9356
put:
security:
- bearerAuth: []
summary: Play an audio file into a call
description: Play an audio file into a call
operationId: startStream
requestBody:
description: action to perform
required: true
content:
application/json:
schema:
type: object
required:
- stream_url
properties:
stream_url:
x-nexmo-developer-collection-description-shown: true
example: '["https://example.com/waiting.mp3"]'
type: array
items:
type: string
loop:
type: integer
description: the number of times to play the file, 0 for infinite
default: 1
level:
type: string
description: Set the audio level of the stream in the range `-1 >= level <= 1` with a precision of 0.1. The default value is 0.
example: "0.4"
default: "0"
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
message:
description: Description of the action taken
type: string
example: Stream started
uuid:
$ref: '#/components/schemas/uuid'
delete:
security:
- bearerAuth: []
summary: Stop playing an audio file into a call
description: Stop playing an audio file into a call
operationId: stopStream
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
message:
description: Description of the action taken
type: string
example: Stream stopped
uuid:
$ref: '#/components/schemas/uuid'
"/calls/{uuid}/talk":
parameters:
- in: path
name: uuid
schema:
type: string
required: true
description: UUID of the Call
example: 63f61863-4a51-4f6b-86e1-46edebcf9356
put:
security:
- bearerAuth: []
summary: Play text to speech into a call
description: Play text to speech into a call
operationId: startTalk
requestBody:
description: Action to perform
content:
application/json:
schema:
required:
- text
properties:
text:
type: string
description: The text to read
example: Hello. How are you today?
voice_name:
$ref: "#/components/schemas/voice_name"
loop:
type: integer
description: The number of times to repeat the text the file, 0
for infinite
default: 1
level:
type: string
description: The volume level that the speech is played. This can be any value between `-1` to `1` in `0.1` increments, with `0` being the default.
example: "0.4"
default: "0"
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
message:
description: Description of the action taken
type: string
example: Talk started
uuid:
$ref: '#/components/schemas/uuid'
delete:
security:
- bearerAuth: []
summary: Stop text to speech in a call
description: Stop text to speech in a call
operationId: stopTalk
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
message:
description: Description of the action taken
type: string
example: Talk stopped
uuid:
$ref: '#/components/schemas/uuid'
"/calls/{uuid}/dtmf":
parameters:
- in: path
name: uuid
schema:
type: string
required: true
description: UUID of the Call
example: 63f61863-4a51-4f6b-86e1-46edebcf9356
put:
security:
- bearerAuth: []
summary: Play DTMF tones into a call
description: Play DTMF tones into a call
operationId: startDTMF
requestBody:
description: action to perform
required: true
content:
application/json:
schema:
properties:
digits:
type: string
example: 1713
description: The digits to send
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
message:
description: Description of the action taken
type: string
example: DTMF sent
uuid:
$ref: '#/components/schemas/uuid'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
network:
description: >-
The Mobile Country Code Mobile Network Code
([MCCMNC](https://en.wikipedia.org/wiki/Mobile_country_code)) for
the carrier network used to make this call.
type: string
title: 'The Network ID of the destination '
example: '65512'
start_time:
description: 'The time the call started in the following format: `YYYY-MM-DD HH:MM:SS`. For example, `2020-01-01 12:00:00`.'
type: string
format: timestamp
title: 'The Start Time of the call '
example: '2020-01-01 12:00:00'
end_time:
description: 'The time the call started in the following format: `YYYY-MM-DD HH:MM:SS`. For xample, `2020-01-01 12:00:00`. This is only sent if `status` is `completed`.'
type: string
format: timestamp
title: 'The End Time of the call '
example: '2020-01-01 12:00:00'
duration:
description: The time elapsed for the call to take place in seconds. This is only sent if `status` is `completed`.
type: string
title: 'The Duration of the call '
example: '60'
price:
description: The total price charged for this call. This is only sent if `status` is `completed`.
type: string
title: 'The total price of the call '
example: '23.40'
rate:
description: The price per minute for this call. This is only sent if `status` is `completed`.
type: string
title: The Price per minute of the called destination
example: '0.39'
direction:
type: string
description: Possible values are `outbound` or `inbound`
example: outbound
enum:
- outbound
- inbound
uuid:
type: string
format: uuid
title: The UUID of the Call
example: 63f61863-4a51-4f6b-86e1-46edebcf9356
description: >-
The unique identifier for this call leg. The UUID is created when
your call request is accepted by Nexmo. You use the UUID in all
requests for individual live calls
conversation_uuid:
type: string
format: uuid
title: The UUID of the Conversation
example: CON-f972836a-550f-45fa-956c-12a2ab5b7d22
description: The unique identifier for the conversation this call leg is part of.
from:
type: array
description: The endpoint you called from. Possible values are the same as `to`.
title: The number or address that has been called
items:
type: object
properties:
type:
type: string
title: The type of Endpoint that made the call
example: phone
number:
type: string
title: The number that made the call
example: '447700900001'
to:
type: array
description: The single or mixed collection of endpoint types you connected to
title: The number or address to call
items:
type: object
properties:
type:
type: string
title: The Type of Endpoint Called
example: phone
number:
type: string
title: The number of the endpoint called
example: '447700900000'
status:
type: string
title: The State of the call
example: started
description: The status of the call. [See possible values](https://developer.nexmo.com/voice/voice-api/guides/call-flow#event-objects)
EndpointPhone:
type: object
description: Connect to a Phone (PSTN) number
required:
- type
properties:
type:
type: string
example: phone
description: The type of connection. Must be `phone`
enum:
- phone
number:
"$ref": "#/components/schemas/AddressE164"
dtmfAnswer:
description: Provide [DTMF digits](https://developer.nexmo.com/voice/voice-api/guides/dtmf) to send when the call is answered
type: string
example: p*123#
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
enum:
- websocket
uri:
"$ref": "#/components/schemas/AddressWebsocket"
content-type:
type: string
example: audio/l16;rate=16000
enum:
- audio/l16;rate=8000
- audio/l16;rate=16000
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
EndpointSip:
type: object
description: Connect to a SIP Endpoint
required:
- type
properties:
type:
description: The type of connection. Must be `sip`
type: string
example: sip
enum:
- sip
uri:
"$ref": "#/components/schemas/AddressSip"
AddressE164:
description: The phone number to connect to
type: string
minLength: 7
maxLength: 15
example: '14155550100'
pattern: "\\d{7,15}"
AddressSip:
description: The SIP URI to connect to
type: string
minLength: 1
maxLength: 50
example: rebekka@sip.example.com
AddressWebsocket:
type: string
minLength: 1
maxLength: 50
example: wss://example.com/socket
callEvent:
type: object
required:
- conversation_uuid
- to
- from
- uuid
- status
properties:
conversation_uuid:
description: The UUID of the Conversion that the event relates to
type: string
format: uuid
example: CON-171b3991-49b0-4dfa-badd-2bc6e68b57b4
to:
$ref: '#/components/schemas/from'
from:
$ref: '#/components/schemas/from'
uuid:
description: The UUID of the call leg that the event relates to
type: string
format: uuid
example: 63f61863-4a51-4f6b-86e1-46edebcf9356
timestamp:
type: string
format: date-time
example: 2018-01-12T15:01:55.315Z
status:
type: string
example: started
enum:
- started
- ringing
- answered
- machine
- completed
- timeout
- failed
- rejected
- cancelled
- busy
direction:
type: string
enum:
- inbound
- outbound
voice_name:
description: The voice & language to use
type: string
default: Kimberly
enum:
- Salli
- Joey
- Naja
- Mads
- Marlene
- Hans
- Nicole
- Russell
- Amy
- Brian
- Emma
- Geraint
- Gwyneth
- Raveena
- Chipmunk
- Eric
- Ivy
- Jennifer
- Justin
- Kendra
- Kimberly
- Conchita
- Enrique
- Penelope
- Miguel
- Chantal
- Celine
- Mathieu
- Dora
- Karl
- Carla
- Giorgio
- Liv
- Lotte
- Ruben
- Agnieszka
- Jacek
- Ewa
- Jan
- Maja
- Vitoria
- Ricardo
- Cristiano
- Ines
- Carmen
- Maxim
- Tatyana
- Astrid
- Filiz
- Mizuki
- Seoyeon