Conversation API

Version 1

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.

Download OpenAPI Specification

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.

Available Operations

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

gethttps://api.nexmo.com/v1/conversations

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Query Parameters

date_start

string(dateTime)

example2018-01-01 10:00:00

Return the records that occurred after this point in time.

date_end

string(dateTime)

example2018-01-01 12:00:00

Return the records that occurred before this point in time.

page_size

integer

Min1

Max100

Default10

example10

Return this amount of records in the response

order

string

Defaultasc

Return the records in ascending or descending order.

Must be one of:ascdescASCDESC

cursor

string

The 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.

Responses
Content Type
application/json

page_size

integer

Required

Min1

Max100

Default10

example10

The amount of records returned in this response

_embedded

object

Required

A list of conversation objects. See the get details of a specific conversation response fields for a description of the nested objects

conversations

array

Required

List of conversations matching the provided filter

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

timestamp

object

created

string

example2019-09-03T18:40:24.324Z

The time that the conversation was created

updated

string

example2019-09-03T18:50:24.324Z

The time that the conversation was updated

destroyed

string

example2019-09-05T18:40:24.324Z

The time that the conversation was destroyed

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9

_links

object

Required

A series of links between resources in this API in the HAL Specification.

first

object

href

string

examplehttps://api.nexmo.com/v1/conversations?order=desc&page_size=10

self

object

Required

href

string

example

https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=G%2B62WaHsQs7j85CkpyDW2TPwiyfOlRFNtZUyA2hb6eZYlCphM4erOEY%3D

object

href

string

example

https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

object

href

string

example

https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

Example Response

{
   "page_size": 10,
   "_embedded": {
      "conversations": [
         {
            "id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
            "name": "customer_chat",
            "display_name": "Customer Chat",
            "image_url": "https://example.com/image.png",
            "timestamp": {
               "created": "2019-09-03T18:40:24.324Z",
               "updated": "2019-09-03T18:50:24.324Z",
               "destroyed": "2019-09-05T18:40:24.324Z"
            },
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9"
               }
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v1/conversations?order=desc&page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=G%2B62WaHsQs7j85CkpyDW2TPwiyfOlRFNtZUyA2hb6eZYlCphM4erOEY%3D"
      },
      "next": {
         "href": "https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "prev": {
         "href": "https://api.nexmo.com/v1/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      }
   }
}

Create a conversation

Create a conversation with a unique name. The name must be unique across all conversations.

posthttps://api.nexmo.com/v1/conversations

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Request Body
Content Type
application/json

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

properties

object

Conversation properties

ttl

integer

Max2147483648

example60

Time to leave. After how many seconds an empty conversation is deleted.

custom_data

object

Custom Key value pairs to be included with conversation data

numbers

One Of

type

string

examplephone

Must be one of:phone

number

string

example447700900000

callback

object

url

string(uri)

Max2048

examplehttps://example.com/eventcallback

The URL to send conversation events to.

event_mask

string

Max200

examplemember:invited, member:joined

A comma separated string detailing the events to send to the callback URL. If not supplied all events will be sent.

params

object

applicationId

string

Max200

The application ID that the event is associated with.

ncco_url

string(uri)

Max2048

examplehttps://example.com/ncco

The URL to send the NCCO to.

method

string

DefaultPOST

The HTTP method to use when sending events to the callback URL.

Must be one of:POSTGET

Example Request

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {
      "type": "phone",
      "number": "447700900000"
   },
   "callback": {
      "url": "https://example.com/eventcallback",
      "event_mask": "member:invited, member:joined",
      "params": {
         "applicationId": "string",
         "ncco_url": "https://example.com/ncco"
      },
      "method": "POST"
   }
}

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {
      "type": "phone",
      "number": "447700900000"
   },
   "callback": {
      "url": "https://example.com/eventcallback",
      "event_mask": "member:invited, member:joined",
      "params": {
         "applicationId": "string",
         "ncco_url": "https://example.com/ncco"
      },
      "method": "POST"
   }
}

Responses
Content Type
application/json

Created

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

state

string

exampleACTIVE

The state the conversation is in.

Must be one of:ACTIVEINACTIVEDELETED

sequence_number

integer

The last Event ID in this conversation. This ID can be used to retrieve a specific event.

timestamp

object

created

string

example2019-09-03T18:40:24.324Z

The time that the conversation was created

updated

string

example2019-09-03T18:50:24.324Z

The time that the conversation was updated

destroyed

string

example2019-09-05T18:40:24.324Z

The time that the conversation was destroyed

properties

object

Conversation properties

ttl

integer

Max2147483648

example60

Time to leave. After how many seconds an empty conversation is deleted.

custom_data

object

Custom Key value pairs to be included with conversation data

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9

Example Response

{
   "id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "state": "ACTIVE",
   "sequence_number": 0,
   "timestamp": {
      "created": "2019-09-03T18:40:24.324Z",
      "updated": "2019-09-03T18:50:24.324Z",
      "destroyed": "2019-09-05T18:40:24.324Z"
   },
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9"
      }
   }
}

Retrieve a conversation

gethttps://api.nexmo.com/v1/conversations/:conversation_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Responses
Content Type
application/json

Retrieve a conversation

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

state

string

exampleACTIVE

The state the conversation is in.

Must be one of:ACTIVEINACTIVEDELETED

sequence_number

integer

The last Event ID in this conversation. This ID can be used to retrieve a specific event.

timestamp

object

created

string

example2019-09-03T18:40:24.324Z

The time that the conversation was created

updated

string

example2019-09-03T18:50:24.324Z

The time that the conversation was updated

destroyed

string

example2019-09-05T18:40:24.324Z

The time that the conversation was destroyed

properties

object

Conversation properties

ttl

integer

Max2147483648

example60

Time to leave. After how many seconds an empty conversation is deleted.

custom_data

object

Custom Key value pairs to be included with conversation data

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9

Example Response

{
   "id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "state": "ACTIVE",
   "sequence_number": 0,
   "timestamp": {
      "created": "2019-09-03T18:40:24.324Z",
      "updated": "2019-09-03T18:50:24.324Z",
      "destroyed": "2019-09-05T18:40:24.324Z"
   },
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9"
      }
   }
}

Update a conversation

puthttps://api.nexmo.com/v1/conversations/:conversation_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Request Body
Content Type
application/json

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

properties

object

Conversation properties

ttl

integer

Max2147483648

example60

Time to leave. After how many seconds an empty conversation is deleted.

custom_data

object

Custom Key value pairs to be included with conversation data

numbers

One Of

type

string

examplephone

Must be one of:phone

number

string

example447700900000

callback

object

url

string(uri)

Max2048

examplehttps://example.com/eventcallback

The URL to send conversation events to.

event_mask

string

Max200

examplemember:invited, member:joined

A comma separated string detailing the events to send to the callback URL. If not supplied all events will be sent.

params

object

applicationId

string

Max200

The application ID that the event is associated with.

ncco_url

string(uri)

Max2048

examplehttps://example.com/ncco

The URL to send the NCCO to.

method

string

DefaultPOST

The HTTP method to use when sending events to the callback URL.

Must be one of:POSTGET

Example Request

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {
      "type": "phone",
      "number": "447700900000"
   },
   "callback": {
      "url": "https://example.com/eventcallback",
      "event_mask": "member:invited, member:joined",
      "params": {
         "applicationId": "string",
         "ncco_url": "https://example.com/ncco"
      },
      "method": "POST"
   }
}

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {
      "type": "phone",
      "number": "447700900000"
   },
   "callback": {
      "url": "https://example.com/eventcallback",
      "event_mask": "member:invited, member:joined",
      "params": {
         "applicationId": "string",
         "ncco_url": "https://example.com/ncco"
      },
      "method": "POST"
   }
}

Responses
Content Type
application/json

Update a conversation

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

state

string

exampleACTIVE

The state the conversation is in.

Must be one of:ACTIVEINACTIVEDELETED

sequence_number

integer

The last Event ID in this conversation. This ID can be used to retrieve a specific event.

timestamp

object

created

string

example2019-09-03T18:40:24.324Z

The time that the conversation was created

updated

string

example2019-09-03T18:50:24.324Z

The time that the conversation was updated

destroyed

string

example2019-09-05T18:40:24.324Z

The time that the conversation was destroyed

properties

object

Conversation properties

ttl

integer

Max2147483648

example60

Time to leave. After how many seconds an empty conversation is deleted.

custom_data

object

Custom Key value pairs to be included with conversation data

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9

Example Response

{
   "id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "state": "ACTIVE",
   "sequence_number": 0,
   "timestamp": {
      "created": "2019-09-03T18:40:24.324Z",
      "updated": "2019-09-03T18:50:24.324Z",
      "destroyed": "2019-09-05T18:40:24.324Z"
   },
   "properties": {
      "ttl": 60,
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9"
      }
   }
}

Delete a conversation

deletehttps://api.nexmo.com/v1/conversations/:conversation_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Responses

Success response with no content

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

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

gethttps://api.nexmo.com/v1/users/:user_id/conversations

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

user_id

string

Required

User ID

Query Parameters

state

string

Must be one of:INVITEDJOINEDLEFT

order_by

string

Defaultcreated

Must be one of:created

include_custom_data

boolean

date_start

string(dateTime)

example2018-01-01 10:00:00

Return the records that occurred after this point in time.

page_size

integer

Min1

Max100

Default10

example10

Return this amount of records in the response

order

string

Defaultasc

Return the records in ascending or descending order.

Must be one of:ascdescASCDESC

cursor

string

The 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.

Responses
Content Type
application/json

page_size

integer

Required

Min1

Max100

Default10

example10

The amount of records returned in this response

_embedded

object

Required

A list of conversation objects. See the get details of a specific conversation response fields for a description of the nested objects

conversations

array

Required

List of conversations matching the provided filter

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

name

string

Max100

examplecustomer_chat

Your internal conversation name. Must be unique. If not supplied a randomly generated name will be used.

display_name

string

Max50

exampleCustomer Chat

The public facing name of the conversation

image_url

string(uri)

Max2048

examplehttps://example.com/image.png

An image URL that you associate with the conversation

sequence_number

integer

The last Event ID in this conversation. This ID can be used to retrieve a specific event.

properties

object

Conversation properties

ttl

integer

Max2147483648

example60

Time to leave. After how many seconds an empty conversation is deleted.

custom_data

object

Custom Key value pairs to be included with conversation data

timestamp

object

created

string

example2019-09-03T18:40:24.324Z

The time that the conversation was created

updated

string

example2019-09-03T18:50:24.324Z

The time that the conversation was updated

destroyed

string

example2019-09-05T18:40:24.324Z

The time that the conversation was destroyed

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9

_embedded

object

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

state

string

exampleJOINED

The state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN

Must be one of:INVITEDJOINEDLEFTUNKNOWN

_links

object

Required

A series of links between resources in this API in the http://stateless.co/hal_specification.html.

first

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10

self

object

Required

href

string

example

https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

object

href

string

example

https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

object

href

string

example

https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

Example Response

{
   "page_size": 10,
   "_embedded": {
      "conversations": [
         {
            "id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
            "name": "customer_chat",
            "display_name": "Customer Chat",
            "image_url": "https://example.com/image.png",
            "sequence_number": 0,
            "properties": {
               "ttl": 60,
               "custom_data": {
                  "property1": "string",
                  "property2": "string"
               }
            },
            "timestamp": {
               "created": "2019-09-03T18:40:24.324Z",
               "updated": "2019-09-03T18:50:24.324Z",
               "destroyed": "2019-09-05T18:40:24.324Z"
            },
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v1/conversations/CON-7f977ca5-6e86-46a8-bdc9-67b9d8c8dfa9"
               }
            },
            "_embedded": {
               "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
               "state": "JOINED"
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "next": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "prev": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      }
   }
}

Member

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.

Available Operations

List members

gethttps://api.nexmo.com/v1/conversations/:conversation_id/members

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Query Parameters

page_size

integer

Min1

Max100

Default10

example10

Return this amount of records in the response

order

string

Defaultasc

Return the records in ascending or descending order.

Must be one of:ascdescASCDESC

cursor

string

The 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.

Responses
Content Type
application/json

Members List Object

page_size

integer

example10

The number of results returned on this page

_embedded

object

members

array

List of members matching the provided filter

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

state

string

exampleJOINED

The state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN

Must be one of:INVITEDJOINEDLEFTUNKNOWN

_embedded

object

user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

_links

object

href

string(url)

example

https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391

A link towards a member included in Conversation API

_links

object

first

object

href

string

examplehttps://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10

self

object

href

string

example

https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0

object

href

string

example

https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55

object

href

string

example

https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb

Example Response

{
   "page_size": 10,
   "_embedded": {
      "members": [
         {
            "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
            "state": "JOINED",
            "_embedded": {
               "user": {
                  "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
                  "name": "my_user_name",
                  "display_name": "My User Name",
                  "_links": {
                     "self": {
                        "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
                     }
                  }
               }
            },
            "_links": {
               "href": "https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
      },
      "next": {
         "href": "https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
      },
      "prev": {
         "href": "https://api.nexmo.com/v1/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
      }
   }
}

Create a member

posthttps://api.nexmo.com/v1/conversations/:conversation_id/members

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Request Body
Content Type
application/json

state

string

Required

exampleinvited

Invite or join a member to a conversation

Must be one of:invitedjoined

user

object

Required

Either the user id or name is required.

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

channel

Required

One Of

type

string

Required

Channel type

Must be one of:app

from

object

Which channel types this member accepts messages from (if not set, all are accepted)

type

string

Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger

object

Settings which control who this member can send messages to.

type

string

Must be one of:app

user

string

The user ID of the member that this member can send messages to.

media

object

Details about the current media setting states

audio_settings

object

enabled

boolean

is audio currently enabled

earmuffed

boolean

is audio currently earmuffed

muted

boolean

is audio currently muted

audio

boolean

Is an audio connection possible

knocking_id

string

examplea972836a-450f-35fa-156c-52a2ab5b7d25

Knocker ID. A knocker is a pre-member of a conversation who does not exist yet

member_id_inviting

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID of the member that sends the invitation

from

string

Example Request

{
   "state": "invited",
   "user": {
      "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
      "name": "my_user_name"
   },
   "channel": {
      "type": "app",
      "from": {
         "type": "string"
      },
      "to": {
         "type": "app",
         "user": "string"
      }
   },
   "media": {
      "audio_settings": {
         "enabled": true,
         "earmuffed": true,
         "muted": true
      },
      "audio": true
   },
   "knocking_id": "a972836a-450f-35fa-156c-52a2ab5b7d25",
   "member_id_inviting": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "from": "string"
}

{
   "state": "invited",
   "user": {
      "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
      "name": "my_user_name"
   },
   "channel": {
      "type": "app",
      "from": {
         "type": "string"
      },
      "to": {
         "type": "app",
         "user": "string"
      }
   },
   "media": {
      "audio_settings": {
         "enabled": true,
         "earmuffed": true,
         "muted": true
      },
      "audio": true
   },
   "knocking_id": "a972836a-450f-35fa-156c-52a2ab5b7d25",
   "member_id_inviting": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "from": "string"
}

Responses
Content Type
application/json

Create a member

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

conversation_id

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

_embedded

object

user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

exampleJOINED

The state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN

Must be one of:INVITEDJOINEDLEFTUNKNOWN

timestamp

object

invited

string

example2020-01-01T14:00:00.00Z

The time that the member was invited to a conversation

joined

string

example2020-01-01T14:00:00.00Z

The time that the member joined the conversation

left

string

example2020-01-01T14:00:00.00Z

The time that the member left the conversation

initiator

One Of

joined

object

is_system

boolean

false if the user was invited by a user.

user_id

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

member_id

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

channel

One Of

type

string

Required

Channel type

Must be one of:app

from

object

Which channel types this member accepts messages from (if not set, all are accepted)

type

string

Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger

object

Settings which control who this member can send messages to.

type

string

Must be one of:app

user

string

The user ID of the member that this member can send messages to.

media

object

Details about the current media setting states

audio_settings

object

enabled

boolean

is audio currently enabled

earmuffed

boolean

is audio currently earmuffed

muted

boolean

is audio currently muted

audio

boolean

Is an audio connection possible

knocking_id

string

The ID of the original knocker request (if applicable).

invited_by

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0378

The member ID of the member that invited this member to the conversation (if applicable).

_links

object

href

string(url)

example

https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391

A link towards a member included in Conversation API

Example Response

{
   "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "conversation_id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "_embedded": {
      "user": {
         "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "name": "my_user_name",
         "display_name": "My User Name",
         "_links": {
            "self": {
               "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
            }
         }
      }
   },
   "state": "JOINED",
   "timestamp": {
      "invited": "2020-01-01T14:00:00.00Z",
      "joined": "2020-01-01T14:00:00.00Z",
      "left": "2020-01-01T14:00:00.00Z"
   },
   "initiator": {
      "joined": {
         "is_system": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "app",
      "from": {
         "type": "string"
      },
      "to": {
         "type": "app",
         "user": "string"
      }
   },
   "media": {
      "audio_settings": {
         "enabled": true,
         "earmuffed": true,
         "muted": true
      },
      "audio": true
   },
   "knocking_id": "string",
   "invited_by": "MEM-63f61863-4a51-4f6b-86e1-46edebio0378",
   "_links": {
      "href": "https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
   }
}

Retrieve your member

This retrieves the member associated with the sub claim on the JWT

gethttps://api.nexmo.com/v1/conversations/:conversation_id/members/me

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Responses
Content Type
application/json

Retrieve member payload

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

conversation_id

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

_embedded

object

user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

exampleJOINED

The state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN

Must be one of:INVITEDJOINEDLEFTUNKNOWN

timestamp

object

invited

string

example2020-01-01T14:00:00.00Z

The time that the member was invited to a conversation

joined

string

example2020-01-01T14:00:00.00Z

The time that the member joined the conversation

left

string

example2020-01-01T14:00:00.00Z

The time that the member left the conversation

initiator

One Of

joined

object

is_system

boolean

false if the user was invited by a user.

user_id

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

member_id

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

channel

One Of

type

string

Required

Channel type

Must be one of:app

from

object

Which channel types this member accepts messages from (if not set, all are accepted)

type

string

Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger

object

Settings which control who this member can send messages to.

type

string

Must be one of:app

user

string

The user ID of the member that this member can send messages to.

media

object

Details about the current media setting states

audio_settings

object

enabled

boolean

is audio currently enabled

earmuffed

boolean

is audio currently earmuffed

muted

boolean

is audio currently muted

audio

boolean

Is an audio connection possible

knocking_id

string

The ID of the original knocker request (if applicable).

invited_by

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0378

The member ID of the member that invited this member to the conversation (if applicable).

_links

object

href

string(url)

example

https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391

A link towards a member included in Conversation API

Example Response

{
   "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "conversation_id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "_embedded": {
      "user": {
         "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "name": "my_user_name",
         "display_name": "My User Name",
         "_links": {
            "self": {
               "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
            }
         }
      }
   },
   "state": "JOINED",
   "timestamp": {
      "invited": "2020-01-01T14:00:00.00Z",
      "joined": "2020-01-01T14:00:00.00Z",
      "left": "2020-01-01T14:00:00.00Z"
   },
   "initiator": {
      "joined": {
         "is_system": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "app",
      "from": {
         "type": "string"
      },
      "to": {
         "type": "app",
         "user": "string"
      }
   },
   "media": {
      "audio_settings": {
         "enabled": true,
         "earmuffed": true,
         "muted": true
      },
      "audio": true
   },
   "knocking_id": "string",
   "invited_by": "MEM-63f61863-4a51-4f6b-86e1-46edebio0378",
   "_links": {
      "href": "https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
   }
}

Retrieve a member

gethttps://api.nexmo.com/v1/conversations/:conversation_id/members/:member_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

member_id

string

Required

Member ID

Responses
Content Type
application/json

Retrieve member payload

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

conversation_id

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

_embedded

object

user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

exampleJOINED

The state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN

Must be one of:INVITEDJOINEDLEFTUNKNOWN

timestamp

object

invited

string

example2020-01-01T14:00:00.00Z

The time that the member was invited to a conversation

joined

string

example2020-01-01T14:00:00.00Z

The time that the member joined the conversation

left

string

example2020-01-01T14:00:00.00Z

The time that the member left the conversation

initiator

One Of

joined

object

is_system

boolean

false if the user was invited by a user.

user_id

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

member_id

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

channel

One Of

type

string

Required

Channel type

Must be one of:app

from

object

Which channel types this member accepts messages from (if not set, all are accepted)

type

string

Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger

object

Settings which control who this member can send messages to.

type

string

Must be one of:app

user

string

The user ID of the member that this member can send messages to.

media

object

Details about the current media setting states

audio_settings

object

enabled

boolean

is audio currently enabled

earmuffed

boolean

is audio currently earmuffed

muted

boolean

is audio currently muted

audio

boolean

Is an audio connection possible

knocking_id

string

The ID of the original knocker request (if applicable).

invited_by

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0378

The member ID of the member that invited this member to the conversation (if applicable).

_links

object

href

string(url)

example

https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391

A link towards a member included in Conversation API

Example Response

{
   "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "conversation_id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "_embedded": {
      "user": {
         "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "name": "my_user_name",
         "display_name": "My User Name",
         "_links": {
            "self": {
               "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
            }
         }
      }
   },
   "state": "JOINED",
   "timestamp": {
      "invited": "2020-01-01T14:00:00.00Z",
      "joined": "2020-01-01T14:00:00.00Z",
      "left": "2020-01-01T14:00:00.00Z"
   },
   "initiator": {
      "joined": {
         "is_system": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "app",
      "from": {
         "type": "string"
      },
      "to": {
         "type": "app",
         "user": "string"
      }
   },
   "media": {
      "audio_settings": {
         "enabled": true,
         "earmuffed": true,
         "muted": true
      },
      "audio": true
   },
   "knocking_id": "string",
   "invited_by": "MEM-63f61863-4a51-4f6b-86e1-46edebio0378",
   "_links": {
      "href": "https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
   }
}

Update a member

Setting the state to left will result in the member leaving the conversation.

patchhttps://api.nexmo.com/v1/conversations/:conversation_id/members/:member_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

member_id

string

Required

Member ID

Request Body
Content Type
application/json

One Of

state

string

Must be one of:joined

from

string

Example Request

{
   "state": "joined",
   "from": "string"
}

{
   "state": "joined",
   "from": "string"
}

Responses
Content Type
application/json

Member updated

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

conversation_id

string

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The unique identifier for this conversation

_embedded

object

user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

exampleJOINED

The state that the member is in. Possible values are INVITED, JOINED, LEFT, or UNKNOWN

Must be one of:INVITEDJOINEDLEFTUNKNOWN

timestamp

object

invited

string

example2020-01-01T14:00:00.00Z

The time that the member was invited to a conversation

joined

string

example2020-01-01T14:00:00.00Z

The time that the member joined the conversation

left

string

example2020-01-01T14:00:00.00Z

The time that the member left the conversation

initiator

One Of

joined

object

is_system

boolean

false if the user was invited by a user.

user_id

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

member_id

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0391

Member ID

channel

One Of

type

string

Required

Channel type

Must be one of:app

from

object

Which channel types this member accepts messages from (if not set, all are accepted)

type

string

Comma sperated list, can include channel types app, phone, sms, mms, whatsapp , viber, or messenger

object

Settings which control who this member can send messages to.

type

string

Must be one of:app

user

string

The user ID of the member that this member can send messages to.

media

object

Details about the current media setting states

audio_settings

object

enabled

boolean

is audio currently enabled

earmuffed

boolean

is audio currently earmuffed

muted

boolean

is audio currently muted

audio

boolean

Is an audio connection possible

knocking_id

string

The ID of the original knocker request (if applicable).

invited_by

string

exampleMEM-63f61863-4a51-4f6b-86e1-46edebio0378

The member ID of the member that invited this member to the conversation (if applicable).

_links

object

href

string(url)

example

https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391

A link towards a member included in Conversation API

Example Response

{
   "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "conversation_id": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
   "_embedded": {
      "user": {
         "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "name": "my_user_name",
         "display_name": "My User Name",
         "_links": {
            "self": {
               "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
            }
         }
      }
   },
   "state": "JOINED",
   "timestamp": {
      "invited": "2020-01-01T14:00:00.00Z",
      "joined": "2020-01-01T14:00:00.00Z",
      "left": "2020-01-01T14:00:00.00Z"
   },
   "initiator": {
      "joined": {
         "is_system": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "app",
      "from": {
         "type": "string"
      },
      "to": {
         "type": "app",
         "user": "string"
      }
   },
   "media": {
      "audio_settings": {
         "enabled": true,
         "earmuffed": true,
         "muted": true
      },
      "audio": true
   },
   "knocking_id": "string",
   "invited_by": "MEM-63f61863-4a51-4f6b-86e1-46edebio0378",
   "_links": {
      "href": "https://api.nexmo.com/v1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
   }
}

Event

Events are actions that occur within a conversation. Examples of this includes: Text events from members, or Invite events from users

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.

posthttps://api.nexmo.com/v1/conversations/:conversation_id/events

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

Request Body
Content Type
application/json

One Of

type

string

Required

Must be one of:message

from

string

Member ID

body

Required

One Of

message_type

string

Must be one of:text

text

string

Example Request»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)

{
   "type": "message",
   "from": "string",
   "body": {
      "message_type": "text",
      "text": "string"
   }
}

{
   "type": "message",
   "from": "string",
   "body": {
      "message_type": "text",
      "text": "string"
   }
}

Responses
Content Type
application/json

Event Response Payload Object

One Of

integer

Event id. This is a progressive integer

type

string

Must be one of:message

from

string

Member ID

body

One Of

message_type

string

Must be one of:text

text

string

timestamp

string

example2020-01-01T14:00:00.00Z

Time of creation

_embedded

object

from_user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

custom_data

object

from_member

object

string

_links

object

self

object

href

string

Example Response»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)

{
   "id": 0,
   "type": "message",
   "from": "string",
   "body": {
      "message_type": "text",
      "text": "string"
   },
   "timestamp": "2020-01-01T14:00:00.00Z",
   "_embedded": {
      "from_user": {
         "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "name": "my_user_name",
         "display_name": "My User Name",
         "image_url": "https://example.com/image.png",
         "custom_data": {}
      },
      "from_member": {
         "id": "string"
      }
   },
   "_links": {
      "self": {
         "href": "string"
      }
   }
}

Get a list of events

gethttps://api.nexmo.com/v1/conversations/:conversation_id/events

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Query Parameters

start_id

string

The ID to start returning events at

end_id

string

The ID to end returning events at

event_type

string

The type of event to search for. Does not currently support custom events

Must be one of: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:ringing

page_size

integer

Min1

Max100

Default10

example10

Return this amount of records in the response

order

string

Defaultasc

Return the records in ascending or descending order.

Must be one of:ascdescASCDESC

cursor

string

The 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

boolean

Exclude deleted events from the response

Path Parameters

conversation_id

string

Required

Conversation ID

Responses
Content Type
application/json

Events Response Payload Object

page_size

integer

Min1

Max100

Default10

example10

The amount of records returned in this response

_links

object

A series of links between resources in this API in the http://stateless.co/hal_specification.html.

first

object

href

string

self

object

href

string

object

href

string

object

href

string

_embedded

array

One Of

integer

Event id. This is a progressive integer

type

string

Must be one of:message

from

string

Member ID

body

One Of

message_type

string

Must be one of:text

text

string

timestamp

string

example2020-01-01T14:00:00.00Z

Time of creation

_embedded

object

from_user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

custom_data

object

from_member

object

string

_links

object

self

object

href

string

Example Response

{
   "page_size": 10,
   "_links": {
      "first": {
         "href": "string"
      },
      "self": {
         "href": "string"
      },
      "next": {
         "href": "string"
      },
      "prev": {
         "href": "string"
      }
   },
   "_embedded": [
      {
         "id": 0,
         "type": "message",
         "from": "string",
         "body": {
            "message_type": "text",
            "text": "string"
         },
         "timestamp": "2020-01-01T14:00:00.00Z",
         "_embedded": {
            "from_user": {
               "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
               "name": "my_user_name",
               "display_name": "My User Name",
               "image_url": "https://example.com/image.png",
               "custom_data": {}
            },
            "from_member": {
               "id": "string"
            }
         },
         "_links": {
            "self": {
               "href": "string"
            }
         }
      }
   ]
}

Get an event

gethttps://api.nexmo.com/v1/conversations/:conversation_id/events/:event_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

Conversation ID

event_id

string

Required

Event ID

Responses
Content Type
application/json

Event Response Payload Object

One Of

integer

Event id. This is a progressive integer

type

string

Must be one of:message

from

string

Member ID

body

One Of

message_type

string

Must be one of:text

text

string

timestamp

string

example2020-01-01T14:00:00.00Z

Time of creation

_embedded

object

from_user

object

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

custom_data

object

from_member

object

string

_links

object

self

object

href

string

Example Response»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)

{
   "id": 0,
   "type": "message",
   "from": "string",
   "body": {
      "message_type": "text",
      "text": "string"
   },
   "timestamp": "2020-01-01T14:00:00.00Z",
   "_embedded": {
      "from_user": {
         "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "name": "my_user_name",
         "display_name": "My User Name",
         "image_url": "https://example.com/image.png",
         "custom_data": {}
      },
      "from_member": {
         "id": "string"
      }
   },
   "_links": {
      "self": {
         "href": "string"
      }
   }
}

Delete an event

Only message and custom events can be deleted, and then only events your user created or if you use an admin token

deletehttps://api.nexmo.com/v1/conversations/:conversation_id/events/:event_id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

conversation_id

string

Required

exampleCON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

The conversation ID

event_id

string

Required

example5

The event ID

Responses

Success response with no content

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.

Conversation API

Conversation

Available Operations

List conversations

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Create a conversation

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve a conversation

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update a conversation

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete a conversation

Authentication

Path Parameters

Responses

User

Available Operations

List user conversations

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Example Response

Member

Available Operations

List members

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Example Response

Create a member

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve your member

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Retrieve a member

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update a member

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Event

Available Operations

Create an event

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)

Responses Content Typeapplication/json

Example Response»message - Message (Text, Image, Audio, Video, File, Template, Custom, VCard, Location, Random)

Get a list of events

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json