Permalink
Branch: master
Find file Copy path
b7e07db Jan 5, 2019
3 contributors

Users who have contributed to this file

@mheap @adambutler @lornajane
1134 lines (1131 sloc) 37.1 KB
openapi: 3.0.0
servers:
- url: 'https://api.nexmo.com/beta'
info:
version: 1.6.0
title: Nexmo Conversation API
description: 'The Nexmo Conversation API enables you to build conversation features where communication can take place across multiple mediums including IP Messaging, PSTN Voice, SMS and WebRTC Audio and Video. The context of the conversations is maintained though each communication event taking place within a conversation, no matter the medium.'
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url: 'https://developer.nexmo.com/'
x-label: Developer Preview
paths:
/conversations:
post:
operationId: createConversation
tags:
- conversation
summary: Create a conversation
responses:
'200':
$ref: '#/components/responses/ConversationLite'
requestBody:
$ref: '#/components/requestBodies/Conversation'
get:
operationId: listConversations
tags:
- conversation
summary: List conversations
description: >
List all conversations associated with your application.
This endpoint required an admin JWT. To find all conversations for
the currently logged in user, see [GET /users/:id/conversations](#getuserConversations)
parameters:
- $ref: '#/components/parameters/date_start'
- $ref: '#/components/parameters/date_end'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/record_index'
- $ref: '#/components/parameters/order'
responses:
'200':
description: List Conversations Response Payload Object.
content:
application/json:
schema:
type: object
properties:
count:
type: number
example: '100'
description: The total number of records returned by your request.
page_size:
$ref: '#/components/schemas/page_size'
record_index:
$ref: '#/components/schemas/record_index'
_links:
$ref: '#/components/schemas/_links_conversations_list'
_embedded:
description: 'A list of conversation objects. See the [get details of a specific conversation](#retrieveConversation) response fields for a description of the nested objects'
type: object
properties:
conversations:
type: array
items:
type: object
properties:
uuid:
$ref: '#/components/schemas/conversation_id'
name:
$ref: '#/components/schemas/name_conversation'
href:
$ref: '#/components/schemas/href_conversation'
required:
- uuid
- name
- href
required:
- conversations
required:
- count
- page_size
- record_index
- _links
- _embedded
'/conversations/{conversation_id}':
parameters:
- $ref: '#/components/parameters/conversation_id'
put:
operationId: replaceConversation
tags:
- conversation
summary: Update a conversation
responses:
'200':
$ref: '#/components/responses/ConversationLite'
requestBody:
$ref: '#/components/requestBodies/Conversation'
get:
operationId: retrieveConversation
tags:
- conversation
summary: Retrieve a conversation
responses:
'200':
description: Retrieve a conversation
content:
application/json:
schema:
type: object
description: Conversation Object
properties:
uuid:
$ref: '#/components/schemas/conversation_id'
name:
$ref: '#/components/schemas/name_conversation'
numbers:
type: object
properties: {}
properties:
type: object
properties:
video:
type: boolean
example: false
display_name:
$ref: '#/components/schemas/display_name'
timestamp:
$ref: '#/components/schemas/timestamp_res_conversation'
sequence_number:
type: string
example: '1'
description: 'The last Event ID in this conversation. This ID can be used to [retrieve a specific event](#getEvent)'
members:
type: array
description: Users associated to this conversation as members
items:
type: object
properties:
member_id:
$ref: '#/components/schemas/member_id'
user_id:
$ref: '#/components/schemas/user_id'
name:
$ref: '#/components/schemas/name_user'
state:
$ref: '#/components/schemas/member_state'
timestamp:
$ref: '#/components/schemas/timestamp_res_member'
initiator:
$ref: '#/components/schemas/initiator'
channel:
$ref: '#/components/schemas/channel'
api_key:
type: string
description: The API key for your account
_links:
$ref: '#/components/schemas/_links_conversation'
required:
- uuid
delete:
operationId: deleteConversation
tags:
- conversation
summary: Delete a conversation
responses:
'200':
$ref: '#/components/responses/SuccessEmptyJSON'
'/conversations/{conversation_id}/events':
parameters:
- $ref: '#/components/parameters/conversation_id'
post:
operationId: createEvent
tags:
- event
summary: Create an event
requestBody:
content:
application/json:
schema:
type: object
description: Create New Event Request Payload Object
properties:
type:
$ref: '#/components/schemas/event_type'
to:
$ref: '#/components/schemas/member_id'
from:
$ref: '#/components/schemas/member_id'
body:
$ref: '#/components/schemas/event_body'
required:
- type
- from
responses:
'201':
description: Create New Event Response Payload Object
content:
application/json:
schema:
type: object
description: Create New Event Response Payload Object
properties:
id:
$ref: '#/components/schemas/event_id'
timestamp:
$ref: '#/components/schemas/timestamp_res_event'
href:
$ref: '#/components/schemas/href_event'
get:
operationId: getEvents
tags:
- event
summary: List events
responses:
'200':
description: Retrieve Events Response Payload Object
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/event_retrieved'
'/conversations/{conversation_id}/events/{event_id}':
parameters:
- $ref: '#/components/parameters/conversation_id'
- $ref: '#/components/parameters/event_id'
get:
operationId: getEvent
tags:
- event
summary: Retrieve an event
responses:
'200':
description: Retrieve an event Content Payload
content:
application/json:
schema:
$ref: '#/components/schemas/event_retrieved'
delete:
operationId: deleteEvent
tags:
- event
summary: Delete an event
responses:
'200':
$ref: '#/components/responses/SuccessEmptyJSON'
'/conversations/{conversation_id}/members':
parameters:
- $ref: '#/components/parameters/conversation_id'
get:
operationId: getMembers
tags:
- member
summary: List members
responses:
'200':
description: Members List Object
content:
application/json:
schema:
type: array
items:
type: object
properties:
user_id:
$ref: '#/components/schemas/user_id'
user_name:
$ref: '#/components/schemas/name_user'
name:
$ref: '#/components/schemas/name_user'
state:
$ref: '#/components/schemas/member_state'
required:
- user_id
- name
- user_name
- state
post:
operationId: createMember
tags:
- member
summary: Create a member
responses:
'201':
description: 'Create or invite Member in invite state '
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/member_id'
user_id:
$ref: '#/components/schemas/user_id'
state:
$ref: '#/components/schemas/member_state'
timestamp:
$ref: '#/components/schemas/timestamp_res_member'
channel:
$ref: '#/components/schemas/channel'
href:
$ref: '#/components/schemas/href_member'
initiator:
$ref: '#/components/schemas/initiator'
requestBody:
content:
application/json:
schema:
type: object
description: 'Create a Member in invite state '
required:
- user_id
- channel
properties:
action:
$ref: '#/components/schemas/member_action'
user_id:
$ref: '#/components/schemas/user_id'
member_id:
$ref: '#/components/schemas/member_id'
channel:
$ref: '#/components/schemas/channel'
media:
$ref: '#/components/schemas/media'
knocking_id:
$ref: '#/components/schemas/knocker_id'
member_id_inviting:
$ref: '#/components/schemas/member_id_inviting'
'/conversations/{conversation_id}/members/{member_id}':
parameters:
- $ref: '#/components/parameters/conversation_id'
- $ref: '#/components/parameters/member_id'
get:
operationId: getMember
tags:
- member
summary: Retrieve a member
responses:
'200':
description: Retrieve member payload
content:
application/json:
schema:
properties:
id:
$ref: '#/components/schemas/member_id'
href:
$ref: '#/components/schemas/href_member'
put:
operationId: updateMember
tags:
- member
summary: Update a member
responses:
'200':
description: Member retrieved
content:
application/json:
schema:
properties:
id:
$ref: '#/components/schemas/member_id'
href:
$ref: '#/components/schemas/href_member'
requestBody:
content:
application/json:
schema:
properties:
action:
$ref: '#/components/schemas/member_action'
channel:
$ref: '#/components/schemas/channel'
delete:
operationId: deleteMember
tags:
- member
summary: Delete a member
responses:
'200':
$ref: '#/components/responses/SuccessEmptyJSON'
/users:
get:
operationId: getUsers
tags:
- user
summary: List users
responses:
'200':
description: List of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
$ref: '#/components/schemas/user_id'
name:
$ref: '#/components/schemas/name_user'
href:
$ref: '#/components/schemas/href_user'
post:
operationId: createUser
tags:
- user
summary: Create a user
description: 'Note: Users must be created with an admin JWT.'
responses:
'200':
description: Create a user response
content:
application/json:
schema:
type: object
properties:
name:
$ref: '#/components/schemas/name_user'
display_name:
$ref: '#/components/schemas/display_name_user'
href:
$ref: '#/components/schemas/href_user'
requestBody:
content:
application/json:
schema:
type: object
description: 'Create a Member in invite state '
properties:
name:
$ref: '#/components/schemas/name_user'
display_name:
$ref: '#/components/schemas/display_name_user'
image_url:
$ref: '#/components/schemas/image_url'
channels:
$ref: '#/components/schemas/channel'
'/users/{user_id}':
parameters:
- $ref: '#/components/parameters/user_id'
get:
operationId: getUser
tags:
- user
summary: Retrieve a user
responses:
'200':
description: Retrieve a user
content:
application/json:
schema:
properties:
id:
$ref: '#/components/schemas/user_id'
name:
$ref: '#/components/schemas/name_user'
channels:
type: object
href:
type: string
example: 'https://api.nexmo.com/beta/users/USR-63f61863-4a51-4f6b-86e1-46edebio0391'
put:
operationId: updateUser
tags:
- user
summary: Update a user
responses:
'200':
description: Retrieve a user
content:
application/json:
schema:
properties:
id:
$ref: '#/components/schemas/user_id'
href:
$ref: '#/components/schemas/href_user'
requestBody:
content:
application/json:
schema:
properties:
name:
$ref: '#/components/schemas/name_user'
display_name:
$ref: '#/components/schemas/display_name_user'
image_url:
$ref: '#/components/schemas/image_url'
channels:
$ref: '#/components/schemas/channel'
delete:
operationId: deleteUser
tags:
- user
summary: Delete a user
responses:
'200':
$ref: '#/components/responses/SuccessEmptyJSON'
'/users/{user_id}/conversations':
parameters:
- $ref: '#/components/parameters/user_id'
get:
operationId: getuserConversations
tags:
- user
summary: List user conversations
responses:
'200':
description: List user conversations
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
$ref: '#/components/schemas/name_conversation'
image_url:
$ref: '#/components/schemas/image_url'
display_name:
$ref: '#/components/schemas/display_name'
state:
$ref: '#/components/schemas/member_state'
member_id:
$ref: '#/components/schemas/member_id'
sequence_number:
type: integer
format: url
description: the id of the last event of the conversation (event's id is an incremental number
example: '123'
href:
$ref: '#/components/schemas/href'
id:
$ref: '#/components/schemas/conversation_id'
timestamp:
type: object
properties:
created:
$ref: '#/components/schemas/timestamp'
/legs:
get:
operationId: listLegs
tags:
- leg
summary: List legs
responses:
'200':
description: List Legs Successfully
content:
application/json:
schema:
type: object
description: List Legs Response Payload Object
properties:
count:
type: number
example: '100'
description: The total number of records returned by your request.
page_size:
$ref: '#/components/schemas/page_size'
record_index:
$ref: '#/components/schemas/record_index'
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
required:
- href
required:
- self
_embedded:
description: 'A list of conversation objects. See the [get details of a specific conversation](#retrieveConversation) response fields for a description of the nested objects'
type: object
properties:
conversations:
type: array
items:
type: object
properties:
uuid:
$ref: '#/components/schemas/leg_id'
type:
$ref: '#/components/schemas/channel_type'
conversation_uuid:
$ref: '#/components/schemas/conversation_id'
state:
$ref: '#/components/schemas/leg_state'
from:
type: object
to:
type: object
start_time:
$ref: '#/components/schemas/timestamp_leg_start_time'
start_end:
$ref: '#/components/schemas/timestamp_leg_end_time'
_links:
type: object
_embedded:
type: object
required:
- uuid
- name
- href
required:
- legs
required:
- count
- page_size
- record_index
- _links
- _embedded
example:
count: 1
page_size: 10
record_index: 0
_links:
self:
href: 'https://api.nexmo.com/beta/legs'
_embedded:
legs:
- uuid: 2a71f8a1-b6f1-42b3-9eef-c69729e17513
type: app
conversation_uuid: CON-511d076b-9d39-498c-baa7-b7a4bfbd6e32
status: completed
from:
type: app
to:
type: app
start_time: ''
end_time: ''
rtc:
session_id: SES-84ebef0d-321a-47e6-8446-f4fcc5ca74b9
state: terminated
_links:
self:
href: 'https://api.nexmo.com/beta/legs/2a71f8a1-b6f1-42b3-9eef-c69729e17513'
'/legs/{leg_id}':
parameters:
- $ref: '#/components/parameters/leg_id'
delete:
operationId: deleteLeg
tags:
- leg
summary: Delete a leg
responses:
'200':
$ref: '#/components/responses/SuccessEmptyJSON'
components:
schemas:
initiator:
type: object
properties:
joined:
type: object
properties:
isSystem:
type: boolean
description: '`true` if the user was invited by an admin JWT. `user_id` and `member_id` will not exist if `true`'
user_id:
$ref: '#/components/schemas/user_id'
member_id:
$ref: '#/components/schemas/member_id'
leg_state:
type: string
example: terminated
description: Leg Status
enum:
- terminated
conversation_id:
type: string
example: CON-63f61863-4a51-4f6b-86e1-46edebio0391
description: The unique identifier for this conversation
member_id:
type: string
example: MEM-63f61863-4a51-4f6b-86e1-46edebio0391
description: Member ID
member_id_inviting:
type: string
example: MEM-63f61863-4a51-4f6b-86e1-46edebio0391
description: Member ID of the member that sends the invitation
member_action:
type: string
description: Invite or join a member to a conversation
example: join
enum:
- invite
- join
user_id_or_user_name:
type: string
description: user name or user id of the inviter
example: someone_else_user_name
user_id:
type: string
example: USR-63f61863-4a51-4f6b-86e1-46edebio0391
description: User ID
name:
type: string
example: my_unique_name
description: Unique name
name_conversation:
type: string
example: customer_chat
description: Unique name for a conversation
name_user:
type: string
example: my_user_name
description: Unique name for a user
href:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391'
description: A link towards a resources included in Conversation Service API
href_conversation:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391'
description: A link towards a conversation included in Conversation Service API
href_conversations_list:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations?page_size=2&record_index=10&'
description: A link towards a conversations list included in Conversation Service API
href_member:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391'
description: A link towards a member included in Conversation Service API
href_user:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations/USR-63f61863-4a51-4f6b-86e1-46edebio0391'
description: A link towards a user included in Conversation Service API
href_event:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1'
description: A link towards a conversation event included in Conversation Service API
href_rtc:
type: string
format: url
example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/rtc/7777777777777'
description: A link towards a rtc (leg) included in Conversation Service API
event_id:
type: string
example: '5'
description: Event id. This is a progressive integer
image_url:
type: string
format: url
example: 'https://example.com/image.png'
description: A link to an image for conversations' and users' avatars
display_name:
type: string
example: Customer Chat
description: The display name for the conversation. It does not have to be unique
display_name_user:
type: string
example: My User Name
description: A string to be displayed as user name. It does not need to be unique
numbers:
type: object
description: 'An object containing number on different channels. '
example:
pstn: 14155550100
sms: 442079460000
properties:
sms:
type: string
description: phone number used for sms channel
example: 442079460000
pstn:
type: string
description: phone number used for pstn channel
example: 14155550100
conversation_properties:
type: object
description: Conversation properties
properties:
speaking_detection_level:
type: number
example: 0
ttl:
type: number
example: 60
description: 'Time to leave'
_links_conversations_list:
type: object
description: 'A series of links between resources in this API in the http://stateless.co/hal_specification.html.'
properties:
self:
type: object
properties:
href:
$ref: '#/components/schemas/href_conversations_list'
required:
- href
required:
- self
_links_conversation:
type: object
properties:
self:
type: object
properties:
href:
$ref: '#/components/schemas/href_conversation'
page_size:
type: number
description: The amount of records returned in this response
minimum: 1
maximum: 100
default: 10
record_index:
type: number
description: 'Return `page_size` amount of conversations from this index in the response. That is, if your request returns 300 conversations, set `record_index` to 5 in order to return conversations 50 to 59. The default value is 0. That is, the first `page_size` calls.'
default: 0
minimum: 0
timestamp:
type: string
example: '2020-01-01T14:00:00.00Z'
description: Timestamp
timestamp_created:
type: string
example: '2020-01-01T14:00:00.00Z'
description: Time of creation
timestamp_updated:
type: string
example: '2020-01-01T14:05:00.00Z'
description: Time of last update
timestamp_destroyed:
type: string
example: '2020-01-01T14:20:00.00Z'
description: Time of last update
timestamp_leg_start_time:
type: string
example: '2020-01-01T14:00:00.00Z'
description: Time of leg start
timestamp_leg_end_time:
type: string
example: '2020-01-01T14:00:00.00Z'
description: Time of leg end
timestamp_res_event:
type: string
example: '2020-01-01T14:00:00.00Z'
description: Time of event creation
timestamp_res_conversation:
type: object
properties:
created:
$ref: '#/components/schemas/timestamp_created'
updated:
$ref: '#/components/schemas/timestamp_updated'
destroyed:
$ref: '#/components/schemas/timestamp_destroyed'
timestamp_res_member:
type: object
properties:
invited:
$ref: '#/components/schemas/timestamp'
joined:
$ref: '#/components/schemas/timestamp'
left:
$ref: '#/components/schemas/timestamp'
timestamp_obj_leg:
type: object
properties:
start:
$ref: '#/components/schemas/timestamp_created'
end:
$ref: '#/components/schemas/timestamp'
request:
$ref: '#/components/schemas/timestamp'
member_state:
type: string
description: 'The state that the member is in. Possible values are `invited`, `joined`, `left`, or `unknown`'
example: invited
enum:
- invited
- joined
- left
- unknown
leg_id:
type: string
example: a595959595959595995
description: The id of the leg. rtc_id and call_id are leg id
channel_number:
type: string
example: a447700900585
description: this can be a phone number or a random string
channel_type:
type: string
example: phone
description: Channel type
enum:
- app
- phone
- sip
- websocket
channel:
type: object
description: 'When a user joins a conversation as a member, they can have one channel per membership. Channels can be `app`, `phone`, `sip`, or `websocket`'
properties:
type:
$ref: '#/components/schemas/channel_type'
leg_id:
$ref: '#/components/schemas/leg_id'
from:
type: object
properties:
type:
$ref: '#/components/schemas/channel_type'
number:
$ref: '#/components/schemas/channel_number'
to:
type: object
properties:
type:
$ref: '#/components/schemas/channel_type'
number:
$ref: '#/components/schemas/channel_number'
leg_ids:
type: array
items:
properties:
leg_id:
$ref: '#/components/schemas/leg_id'
media:
type: object
description: Media Object
properties: {}
example:
audio_settings:
enabled: false
earmuffed: false
muted: false
event_type:
type: string
description: Event type
example: text
event_body:
type: object
description: Event Body
example:
text: My Text
event_retrieved:
type: object
description: Retrieve Events Response Payload Object Item
properties:
id:
$ref: '#/components/schemas/event_id'
type:
$ref: '#/components/schemas/event_type'
from:
$ref: '#/components/schemas/member_id'
to:
$ref: '#/components/schemas/member_id'
body:
$ref: '#/components/schemas/event_body'
state:
$ref: '#/components/schemas/member_state'
timestamp:
$ref: '#/components/schemas/timestamp_created'
href:
$ref: '#/components/schemas/href_event'
required:
- id
- type
- body
- timestamp
- href
knocker_id:
type: string
description: Knocker ID. A knocker is a pre-member of a conversation who does not exist yet
example: a972836a-450f-35fa-156c-52a2ab5b7d25
parameters:
leg_id:
name: leg_id
in: path
required: true
description: Leg ID
schema:
type: string
user_id:
name: user_id
in: path
required: true
description: User ID
schema:
type: string
conversation_id:
name: conversation_id
in: path
required: true
description: Conversation ID
example: CON-f972836a-550f-45fa-956c-12a2ab5b7d22
schema:
type: string
member_id:
name: member_id
in: path
required: true
description: Member ID
schema:
type: string
event_id:
name: event_id
in: path
description: Event ID
required: true
schema:
type: string
date_start:
name: date_start
in: query
required: false
description: Return the records that occurred after this point in time.
schema:
example: '2018-01-01 10:00:00'
type: string
format: dateTime
date_end:
name: date_end
in: query
required: false
description: Return the records that occurred before this point in time.
schema:
example: '2018-01-01 12:00:00'
type: string
format: dateTime
page_size:
name: page_size
in: query
description: Return this amount of records in the response
required: false
schema:
$ref: '#/components/schemas/page_size'
record_index:
name: record_index
in: query
description: Return calls from this index in the response
required: false
schema:
$ref: '#/components/schemas/record_index'
order:
name: order
in: query
description: Return the records in ascending or descending order.
required: false
schema:
type: string
default: asc
enum:
- asc
- desc
- ASC
- DESC
responses:
ConversationLite:
description: Create / Update Conversation Response Payload Object
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/conversation_id'
href:
$ref: '#/components/schemas/href_conversation'
required:
- id
- href
SuccessEmptyJSON:
description: Success response with empty JSON
content:
application/json:
schema:
type: object
description: Empty JSON payload
example: {}
requestBodies:
EmptyBody:
description: Conversation Request Payload Object
required: true
content:
application/json:
schema:
type: object
example: {}
Conversation:
description: Conversation Request Payload Object
content:
application/json:
schema:
type: object
properties:
name:
$ref: '#/components/schemas/name_conversation'
display_name:
$ref: '#/components/schemas/display_name'
image_url:
$ref: '#/components/schemas/image_url'
numbers:
$ref: '#/components/schemas/numbers'
properties:
$ref: '#/components/schemas/conversation_properties'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
tags:
- name: Conversation
description: A conversation is a shared core component that Nexmo APIs rely on. Conversations happen over multiple mediums and and can have associated Users through Memberships.
- name: User
description: 'The concept of a user exists in Nexmo APIs, you can associate one with a user in your own application if you choose. A user can have multiple memberships to conversations and can communicate with other users through various different mediums.'
- name: Member
description: Memberships connect users with conversations. Each membership has one conversation and one user however a user can have many memberships to conversations just as conversations can have many members.
- name: Event
description: 'Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users'
- name: Leg
description: 'A leg can be a video call, IP call, or PSTN call that users participate in using multiple platforms. With this endpoint you can retrieve the details about all of the legs that took place in your application.'
- name: Rtc
description: Rtc actions. Any rtc action related (like starting a new rtc connection).