Conversation API
The Vonage 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. The context of the conversations is maintained though each communication event taking place within a conversation, no matter the medium.
Conversation
A conversation is a shared core component that Vonage APIs rely on. Conversations happen over multiple mediums and and can have associated Users through Memberships.
List conversations
Get a list of all conversations that the provided JWT has access to. Please note that not all data is available in the list endpoint. Once you've identified the conversation you need to work with, use the GET /conversations/:id endpoint to fetch all of the conversation details
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Query Parameters
2018-01-01 10:00:00Return the records that occurred after this point in time.
2018-01-01 12:00:00Return the records that occurred before this point in time.
11001010Return this amount of records in the response
ascReturn the records in ascending or descending order.
ascdescASCDESCThe cursor to start returning results from.
You are not expected to provide this manually, but to follow the url provided in _links.next.href or _links.prev.href in the response which contains a cursor value.
11001010The amount of records returned in this response
A list of conversation objects. See the get details of a specific conversation response fields for a description of the nested objects
List of conversations matching the provided filter
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
2019-09-03T18:40:24.324ZThe time that the conversation was created
2019-09-03T18:50:24.324ZThe time that the conversation was updated
2019-09-05T18:40:24.324ZThe time that the conversation was destroyed
https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9A series of links between resources in this API in the HAL Specification.
https://api.nexmo.com/v1/conversations?order=desc&page_size=10https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=G%2B62WaHsQs7j85CkpyDW2TPwiyfOlRFNtZUyA2hb6eZYlCphM4erOEY%3Dhttps://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3Dhttps://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3DExample Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
Conversation properties
214748364860Time to leave. After how many seconds an empty conversation is deleted.
Custom Key value pairs to be included with conversation data
phonephone4477009000002048https://example.com/eventcallbackThe URL to send conversation events to.
200member:invited, member:joinedA comma separated string detailing the events to send to the callback URL. If not supplied all events will be sent.
200The application ID that the event is associated with.
2048https://example.com/nccoThe URL to send the NCCO to.
POSTThe HTTP method to use when sending events to the callback URL.
POSTGETExample Request
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
ACTIVEThe state the conversation is in.
ACTIVEINACTIVEDELETEDThe last Event ID in this conversation. This ID can be used to retrieve a specific event.
2019-09-03T18:40:24.324ZThe time that the conversation was created
2019-09-03T18:50:24.324ZThe time that the conversation was updated
2019-09-05T18:40:24.324ZThe time that the conversation was destroyed
Conversation properties
214748364860Time to leave. After how many seconds an empty conversation is deleted.
Custom Key value pairs to be included with conversation data
https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
ACTIVEThe state the conversation is in.
ACTIVEINACTIVEDELETEDThe last Event ID in this conversation. This ID can be used to retrieve a specific event.
2019-09-03T18:40:24.324ZThe time that the conversation was created
2019-09-03T18:50:24.324ZThe time that the conversation was updated
2019-09-05T18:40:24.324ZThe time that the conversation was destroyed
Conversation properties
214748364860Time to leave. After how many seconds an empty conversation is deleted.
Custom Key value pairs to be included with conversation data
https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
Conversation properties
214748364860Time to leave. After how many seconds an empty conversation is deleted.
Custom Key value pairs to be included with conversation data
phonephone4477009000002048https://example.com/eventcallbackThe URL to send conversation events to.
200member:invited, member:joinedA comma separated string detailing the events to send to the callback URL. If not supplied all events will be sent.
200The application ID that the event is associated with.
2048https://example.com/nccoThe URL to send the NCCO to.
POSTThe HTTP method to use when sending events to the callback URL.
POSTGETExample Request
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
ACTIVEThe state the conversation is in.
ACTIVEINACTIVEDELETEDThe last Event ID in this conversation. This ID can be used to retrieve a specific event.
2019-09-03T18:40:24.324ZThe time that the conversation was created
2019-09-03T18:50:24.324ZThe time that the conversation was updated
2019-09-05T18:40:24.324ZThe time that the conversation was destroyed
Conversation properties
214748364860Time to leave. After how many seconds an empty conversation is deleted.
Custom Key value pairs to be included with conversation data
https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
User
The concept of a user exists in Vonage 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, below are the conversation specific user end points. CRUD operations for users are carried out in the Application API.
Available Operations
List user conversations
Please note that not all data is available in the list endpoint. Once you've identified the conversation you need to work with, use the GET /conversations/:id endpoint to fetch all of the conversation details
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Query Parameters
INVITEDJOINEDLEFTcreatedcreated2018-01-01 10:00:00Return the records that occurred after this point in time.
11001010Return this amount of records in the response
ascReturn the records in ascending or descending order.
ascdescASCDESCThe cursor to start returning results from.
You are not expected to provide this manually, but to follow the url provided in _links.next.href or _links.prev.href in the response which contains a cursor value.
11001010The amount of records returned in this response
A list of conversation objects. See the get details of a specific conversation response fields for a description of the nested objects
List of conversations matching the provided filter
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
100customer_chatYour internal conversation name. Must be unique. If not supplied a randomly generated name will be used.
50Customer ChatThe public facing name of the conversation
2048https://example.com/image.pngAn image URL that you associate with the conversation
The last Event ID in this conversation. This ID can be used to retrieve a specific event.
Conversation properties
214748364860Time to leave. After how many seconds an empty conversation is deleted.
Custom Key value pairs to be included with conversation data
2019-09-03T18:40:24.324ZThe time that the conversation was created
2019-09-03T18:50:24.324ZThe time that the conversation was updated
2019-09-05T18:40:24.324ZThe time that the conversation was destroyed
https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
JOINEDThe state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN
INVITEDJOINEDLEFTUNKNOWNA series of links between resources in this API in the http://stateless.co/hal_specification.html.
https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3Dhttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3Dhttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3DExample Response
Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Query Parameters
11001010Return this amount of records in the response
ascReturn the records in ascending or descending order.
ascdescASCDESCThe cursor to start returning results from.
You are not expected to provide this manually, but to follow the url provided in _links.next.href or _links.prev.href in the response which contains a cursor value.
10The number of results returned on this page
List of members matching the provided filter
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
JOINEDThe state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN
INVITEDJOINEDLEFTUNKNOWNUSR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471echttps://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391A link towards a member included in Conversation API
https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edbExample Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
invitedInvite or join a member to a conversation
invitedjoinedEither the user id or name is required.
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
Channel type
appWhich channel types this member accepts messages from (if not set, all are accepted)
Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger
Settings which control who this member can send messages to.
appThe user ID of the member that this member can send messages to.
Details about the current media setting states
is audio currently enabled
is audio currently earmuffed
is audio currently muted
Is an audio connection possible
a972836a-450f-35fa-156c-52a2ab5b7d25Knocker ID. A knocker is a pre-member of a conversation who does not exist yet
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID of the member that sends the invitation
Example Request
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ecJOINEDThe state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN
INVITEDJOINEDLEFTUNKNOWN2020-01-01T14:00:00.00ZThe time that the member was invited to a conversation
2020-01-01T14:00:00.00ZThe time that the member joined the conversation
2020-01-01T14:00:00.00ZThe time that the member left the conversation
false if the user was invited by a user.
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
Channel type
appWhich channel types this member accepts messages from (if not set, all are accepted)
Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger
Settings which control who this member can send messages to.
appThe user ID of the member that this member can send messages to.
Details about the current media setting states
is audio currently enabled
is audio currently earmuffed
is audio currently muted
Is an audio connection possible
The ID of the original knocker request (if applicable).
MEM-63f61863-4a51-4f6b-86e1-46edebio0378The member ID of the member that invited this member to the conversation (if applicable).
https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391A link towards a member included in Conversation API
Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ecJOINEDThe state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN
INVITEDJOINEDLEFTUNKNOWN2020-01-01T14:00:00.00ZThe time that the member was invited to a conversation
2020-01-01T14:00:00.00ZThe time that the member joined the conversation
2020-01-01T14:00:00.00ZThe time that the member left the conversation
false if the user was invited by a user.
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
Channel type
appWhich channel types this member accepts messages from (if not set, all are accepted)
Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger
Settings which control who this member can send messages to.
appThe user ID of the member that this member can send messages to.
Details about the current media setting states
is audio currently enabled
is audio currently earmuffed
is audio currently muted
Is an audio connection possible
The ID of the original knocker request (if applicable).
MEM-63f61863-4a51-4f6b-86e1-46edebio0378The member ID of the member that invited this member to the conversation (if applicable).
https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391A link towards a member included in Conversation API
Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ecJOINEDThe state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN
INVITEDJOINEDLEFTUNKNOWN2020-01-01T14:00:00.00ZThe time that the member was invited to a conversation
2020-01-01T14:00:00.00ZThe time that the member joined the conversation
2020-01-01T14:00:00.00ZThe time that the member left the conversation
false if the user was invited by a user.
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
Channel type
appWhich channel types this member accepts messages from (if not set, all are accepted)
Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger
Settings which control who this member can send messages to.
appThe user ID of the member that this member can send messages to.
Details about the current media setting states
is audio currently enabled
is audio currently earmuffed
is audio currently muted
Is an audio connection possible
The ID of the original knocker request (if applicable).
MEM-63f61863-4a51-4f6b-86e1-46edebio0378The member ID of the member that invited this member to the conversation (if applicable).
https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391A link towards a member included in Conversation API
Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
joinedExample Request
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9aThe unique identifier for this conversation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ecJOINEDThe state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN
INVITEDJOINEDLEFTUNKNOWN2020-01-01T14:00:00.00ZThe time that the member was invited to a conversation
2020-01-01T14:00:00.00ZThe time that the member joined the conversation
2020-01-01T14:00:00.00ZThe time that the member left the conversation
false if the user was invited by a user.
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
MEM-63f61863-4a51-4f6b-86e1-46edebio0391Member ID
Channel type
appWhich channel types this member accepts messages from (if not set, all are accepted)
Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger
Settings which control who this member can send messages to.
appThe user ID of the member that this member can send messages to.
Details about the current media setting states
is audio currently enabled
is audio currently earmuffed
is audio currently muted
Is an audio connection possible
The ID of the original knocker request (if applicable).
MEM-63f61863-4a51-4f6b-86e1-46edebio0378The member ID of the member that invited this member to the conversation (if applicable).
https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391A link towards a member included in Conversation API
Example Response
Available Operations
Create an event
Events are used to record actions that take place within a conversation. Some events are created automatically when carrying out actions such as adding a user to a conversation, but you can also create custom events to record other actions that take place within a conversation. For more details on event types and how they should be used please see the event concept documentation.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
messageMember ID
textExample Request»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)
Event id. This is a progressive integer
messageMember ID
text2020-01-01T14:00:00.00ZTime of creation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://example.com/image.pngAn image URL that you associate with the user
Example Response»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Query Parameters
The ID to start returning events at
The ID to end returning events at
The type of event to search for. Does not currently support custom events
leg:status:updateaudio:dtmfaudio:earmuff:offaudio:earmuff:onaudio:mute:offaudio:mute:onaudio:play:stopaudio:play:doneaudio:playaudio:record:stopaudio:record:doneaudio:recordaudio:asr:doneaudio:asr:record:doneaudio:say:stopaudio:say:doneaudio:sayaudio:speaking:onaudio:speaking:offmessagemessage:submittedmessage:rejectedmessage:undeliverablemessage:seenmessage:deliveredmember:joinedmember:leftmember:mediamember:message:statusmember:invitedconversation:updatedevent:deletertc:statusrtc:transferrtc:hanguprtc:answeredrtc:ringingrtc:answerrtc:terminatesip:statussip:hangupsip:answeredsip:machinesip:amd_machinesip:ringing11001010Return this amount of records in the response
ascReturn the records in ascending or descending order.
ascdescASCDESCThe cursor to start returning results from.
You are not expected to provide this manually, but to follow the url provided in _links.next.href or _links.prev.href in the response which contains a cursor value.
Exclude deleted events from the response
11001010The amount of records returned in this response
A series of links between resources in this API in the http://stateless.co/hal_specification.html.
Event id. This is a progressive integer
messageMember ID
text2020-01-01T14:00:00.00ZTime of creation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://example.com/image.pngAn image URL that you associate with the user
Example Response
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Event id. This is a progressive integer
messageMember ID
text2020-01-01T14:00:00.00ZTime of creation
USR-82e028d9-5201-4f1e-8188-604b2d3471ecUser ID
my_user_nameUnique name for a user
My User NameA string to be displayed as user name. It does not need to be unique
https://example.com/image.pngAn image URL that you associate with the user
Example Response»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Hello. How are you today?The text to read
en-USThe language to use
arca-EScmn-CNcmn-TWcs-CZcy-GBda-DKde-DEel-GRen-AUen-GBen-GB-WLSen-INen-USen-ZAes-ESes-MXes-USeu-ESfi-FIfil-PHfr-CAfr-FRhe-ILhi-INhu-HUid-IDis-ISit-ITja-JPko-KRnb-NOnl-NLno-NOpl-PLpt-BRpt-PTro-ROru-RUsk-SKsv-SEth-THtr-TRuk-UAvi-VNyue-CNThe vocal style (vocal range, tessitura, and timbre) to use
falsetrueSet to true to use the premium version of the specified style if available, otherwise the standard version will be used. You can find more information about Premium Voices in the Text-To-Speech guide.
1The number of times to repeat the text the file, 0 for infinite
00.4The 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 Request
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
1the number of times to play the file, 0 for infinite
00.4Set the audio level of the stream in the range -1 >= level <= 1 with a precision of 0.1. The default value is 0.
Example Request
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
Errors
The following is a non-exhaustive list of error codes that may occur while using this API.
These codes are in addition to any of our generic error codes.
| Code | Information |
|---|---|
| device:error:invalid | The request failed due to incorrect device parameters. |
| device:error:not-found | The request failed due to unknown device. |
| device:error:max-device-limit | The request failed due to registered devices exceeding max devices limit per user |
| session:error:internal | An internal error occurred with the session. Please try again shortly. |
| session:error:invalid-event | |
| session:error:not-found | Session does not exist, or you do not have access. |
| session:error:bad-request-ttl | The request cannot be processed due to malformed ttl. |
| session:error:max-open-sessions | The maximum amount of open sessions has been established. Please delete them by logging out and try again. |
| knocking:error:not-found | Knocker does not exist, or you do not have access. |
| knocking:error:invalid | The current knocker could not be processed. This can be due to an invalid state or an invalid channel type. |
| knocking:error:invalid-channel | The request failed due to either malformed or missing channel. Please provide a valid channel and try again. |
| knocking:error:missing-from-name | The request failed due to missing 'from' user. Please provide a valid user and try again. |
| knocking:error:legs-not-match | The leg id in knocker doesn't match the leg to join. Please provide a valid leg id. |
| application:error:internal | An internal error occurred with the application. Please try again shortly. |
| application:error:invalid-event | Application event does not exist, or you do not have access. |
| application:error:not-found | Application does not exist, or you do not have access. |
| application:error:permission-denied | Permission denied |
| conversation:error:bad-request | The request failed due to validation errors. Please provide a valid request and try again. |
| conversation:error:invalid-action | The request failed because the current action is not valid. Please provide a valid action and try again. |
| conversation:error:not-allowed | The request failed because the current state of the conversation is INACTIVE. Only GET and DELETE actions are allowed. |
| conversation:error:duplicate-name | The request failed because the conversation name already exists. Please provide a unique conversation name and try again. |
| conversation:error:internal | An internal error occurred with the conversation. Please try again shortly. |
| conversation:error:internal-media | An internal error occurred with the conversation media. Please try again shortly. |
| conversation:error:invalid-channel | The request failed due to either malformed or missing channel. Please provide a valid channel and try again. |
| conversation:error:invalid-member | The request failed due to an invalid member. Please provide a valid member and try again. |
| conversation:error:invalid-member-state | The conversation membership has already ended |
| conversation:error:member-already-joined | The request failed due to the user already having a member joined with that channel content. Please provide a valid user and try again. |
| conversation:error:member-already-invited | The request failed due to the user already having a member invited with that channel content. Please provide a valid user and try again. |
| conversation:error:member-not-found | Member does not exist, or you do not have access. |
| conversation:error:invalid-event | The request failed due to an invalid conversation event. Please provide a valid event and try again. |
| conversation:error:not-found | Conversation does not exist, or you do not have access. |
| conversation:error:permission-denied | expired JWT, invalid application. |
| conversation:error:maximum-number-of-members | The request failed due to the maximum number of joined/invited members in the conversation. Please reduce the number of members and try again. |
| conversation:error:member:permission-denied | You did not provide a correct token. Please provide a valid token. |
| conversation:error:member:channel-not-found | The request failed due to a non-existent requested channel. Please provide a valid channel id/number and try again. |
| user:error:invalid-event | The request failed due to an invalid user event. Please provide a valid event and try again. |
| user:error:duplicate-name | The request failed because the user name already exists. Please provide a unique user name and try again. |
| user:error:internal | An internal error occurred with the user. Please try again shortly. |
| user:error:invalid-state-lookup | The request failed due to an invalid member state filter value. Please provide a valid state name and try again. |
| user:error:not-found | User does not exist, or you do not have access. |
| user:error:invalid-user | The request failed due to an invalid user name. Please provide a valid user name and try again. |
| user:error:invalid-user-token | Token does not contain a user name. |
| user:error:invalid-user-name | Username must not be 'me' and it must not start with 'USR-'. |
| user:error:invalid-application | Application does not exist, or you do not have access. |
| user:notification:error:not-found | Notification does not exist, or you do not have access. |
| user:device:error:not-found | The request failed due to non-existent user devices. Please register a device and try again. |
| event:error:internal | An internal error occurred with the event. Please try again shortly. |
| event:error:bad-request | The request failed due to an invalid event. Please provide a valid event and try again. |
| event:error:unknown-event | The request failed due to an unknown event. Please provide a known event and try again. |
| event:error:not-found | Event does not exist, or you do not have access. |
| event:error:not-joined | The request failed due to the member not being in a 'JOINED' state. Please update the member state and try again. |
| event:error:permission-denied | You do not have access to the event. |
| event:error:invalid-filter-group | The request failed due to an invalid filtering. |
| event:error:delete-not-allowed | The request failed because the event is not allowed to be deleted. Only message and custom events are allowed. |
| text:error:unknown-event | The request failed due to an unknown text event. Please provide a known text event and try again. |
| text:error:permission-denied | You do not have access to the text event. |
| text:error:invalid-member | The request failed due to an invalid member. Please provide a valid member and try again. |
| text:error:not-joined | The request failed due to the member not being in a 'JOINED' state. Please update the member state and try again. |
| image:error:unknown-event | The request failed due to an unknown image event. Please provide a known image event and try again. |
| image:error:permission-denied | You do not have access to the image. |
| image:error:invalid-member | The request failed due to an invalid member. Please provide a valid member and try again. |
| image:error:not-joined | The request failed due to the member not being in a 'JOINED' state. Please update the member state and try again. |
| rtc:error:invalid-event | The request failed due to an invalid RTC event. Please provide a valid RTC event and try again. |
| rtc:error:invalid-member | The request failed due to an invalid member. Please provide a valid member and try again. |
| rtc:error:ice:failed | The request failed due to an invalid ICE candidate. Please provide a valid ICE candidate and try again. |
| rtc:error:missing-id | The request failed due to an invalid RTC id. Please provide a valid RTC id and try again. |
| rtc:error:permission-denied | You do not have access to the RTC object. |
| rtc:error:unprocessable | The request failed because the RTC content could not be processed. Please provide valid RTC content and try again. |
| rtc:error:internal | An internal error occurred with the RTC object. Please try again shortly. |
| rtc:error:not-joined | The request failed due to the member not being in a 'JOINED' state. Please update the member state and try again. |
| leg:error:db | A database error occurred with the conversation leg. Please try again shortly. |
| leg:error:invalid-action | The request failed due to an invalid leg action. Please provide a valid leg action and try again. |
| leg:error:internal | An internal error occurred with the conversation leg. Please try again shortly. |
| leg:error:not-found | Conversation leg does not exist, or you do not have access. |
| leg:error:not-answered | The request failed due to the leg not being in an 'answered' state. Please update the leg state and try again. |
| leg:error:invalid-event | The request failed due to an invalid leg event. Please provide a valid leg event and try again. |
| leg:error:invalid-application | Application does not exist, or you do not have access. |
| leg:error:conversation-not-found | Request failed due to leg not being linked to an active conversation |
| leg:error:complete | The request failed due to the leg being in a completed state and as a result no further action can be taken. |
| audio:error:not-found | Audio request does not exist, or you do not have access. |
| audio:error:invalid-event | The request failed due to an invalid audio event. Please provide a valid audio event and try again. |
| system:error:permission | You did not provide a correct token. Please provide a valid token. |
| system:error:missing-token | You did not provide a token. Please provide a valid token. |
| system:error:invalid-token | You did not provide a valid token. Please provide a valid token. |
| system:error:expired-token | You provided an expired token. Please provide a valid token. |
| system:error:internal | An internal error occurred. Please try again shortly. |
| system:error:invalid-event | The request failed due to an invalid event. Please provide a valid event and try again. |
| http:error:not-found | Endpoint does not exist, or you do not have access. |
| http:error:method-not-allowed | Request method not supported. |
| http:error:version-not-allowed | The request failed due to an invalid endpoint version. Please provide a valid endpoint version and try again. |
| http:error:unsupported-media-type | Invalid media type provided. |
| http:error:internal | An internal error occurred. Please try again shortly. |
| media:error:not-found | Media does not exist, or you do not have access. |
| media:error:too-many-request | You have exceeded your media request limit. You can try again shortly. |
| media:error:internal | An internal error occurred with the media object. Please try again shortly. |
| media:error:leg-already-answered | The request failed because the leg was already answered |
| media:error:bad-request | The request failed due to an invalid media request. Please provide a valid media request and try again. |
| paginator-builder:error:invalid-cursor | The request failed due to an invalid cursor |
| asr:error:max-duration | The request failed due to invalid range for the max_duration param. Please specify a range between 1 and 40. |
| asr:error:start-timeout | The request failed due to invalid range for the start_timeout param. Please specify a range between 1 and 10. |
| custom-data:error:max-data-limit | The request failed due to custom data exceeding max data limit |
| custom-data:error:max-data-sum-limit-exceeded | The request failed due to the sum of custom data exceeded max data limit |
| ephemeral:error:max-data-limit | The request failed due to ephemeral data exceeding max data limit |
| http:error:validation-fail | Input validation failure. |
| http:error:invalid-content-type | Invalid Content-Type. |
| message:error:invalid-event | The request failed due to an invalid message event. Please provide a valid event and try again. |
| message:error:user-undefined | The request failed due to an undefined user. Please provide a user and try again. |
| message:error:conversation-name-undefined | The request failed due to an undefined conversation_name. Please provide a conversation_name and try again. |
| message:error:permission-denied | You do not have access to the message. |
| message:error:invalid-member | The request failed due to an invalid member. Please provide a valid member and try again. |
| message:error:not-joined | The request failed due to the member not being in a 'JOINED' state. Please update the member state and try again. |
| message:error:permission | Request header 'Authorization' missing / Invalid Token. |
| message:error:not-found | External id does not exist, or you do not have access. |
| message:error:channel-unknown | The request failed due to an unknown channel type. Please provide a known channel and try again. |
| message:error:message-type-unknown | The request failed due to an unknown message type. Please provide a known message and try again. |
| nexmo-service:permission-denied | You did not provide a correct token. Please provide a valid token. |
| nexmo-service:error:invalid-event | The request failed due to an invalid nexmo-service event. Please provide a valid event and try again. |
| nexmo-service:error:datacenter-not-found | Datacenter id does not exist, or you do not have access. |