Conversation API

Version 0

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 and Video. 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

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/v0.3/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

number

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

number

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

display_name

string

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

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

_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/v0.3/conversations?order=desc&page_size=10

self

object

Required

href

string

example

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

object

href

string

example

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

object

href

string

example

https://api.nexmo.com/v0.3/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"
            },
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a"
               }
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v0.3/conversations?order=desc&page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v0.3/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "next": {
         "href": "https://api.nexmo.com/v0.3/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "prev": {
         "href": "https://api.nexmo.com/v0.3/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      }
   }
}

Create a conversation

posthttps://api.nexmo.com/v0.3/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

display_name

string

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

number

example60

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

type

string

custom_data

object

numbers

array

example

[
  {
    "type": "phone",
    "number": "447700900000"
  },
  {
    "type": "sip",
    "uri": "sip:+Htg:;xa",
    "username": "string",
    "password": "string"
  },
  {
    "type": "app",
    "user": "string"
  },
  {
    "type": "websocket",
    "uri": "ws://example.com:8080",
    "content_type": "string"
  },
  {
    "type": "vbc",
    "extension": "447700900000"
  }
]

An array containing number on different channels.

callback

object

url

string(uri)

event_mask

string

params

object

applicationId

string

ncco_url

string(uri)

method

string

Must be one of:POSTGET

Example Request

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": [
      {
         "type": "phone",
         "number": "447700900000"
      },
      {
         "type": "sip",
         "uri": "sip:+Htg:;xa",
         "username": "string",
         "password": "string"
      },
      {
         "type": "app",
         "user": "string"
      },
      {
         "type": "websocket",
         "uri": "ws://example.com:8080",
         "content_type": "string"
      },
      {
         "type": "vbc",
         "extension": "447700900000"
      }
   ],
   "callback": {
      "url": "http://example.com",
      "event_mask": "string",
      "params": {
         "applicationId": "string",
         "ncco_url": "http://example.com"
      },
      "method": "POST"
   }
}

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": [
      {
         "type": "phone",
         "number": "447700900000"
      },
      {
         "type": "sip",
         "uri": "sip:+Htg:;xa",
         "username": "string",
         "password": "string"
      },
      {
         "type": "app",
         "user": "string"
      },
      {
         "type": "websocket",
         "uri": "ws://example.com:8080",
         "content_type": "string"
      },
      {
         "type": "vbc",
         "extension": "447700900000"
      }
   ],
   "callback": {
      "url": "http://example.com",
      "event_mask": "string",
      "params": {
         "applicationId": "string",
         "ncco_url": "http://example.com"
      },
      "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

display_name

string

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.

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

properties

object

Conversation properties

ttl

number

example60

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

type

string

custom_data

object

numbers

object

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

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"
   },
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {},
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a"
      }
   }
}

Retrieve a conversation

gethttps://api.nexmo.com/v0.3/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

display_name

string

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.

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

properties

object

Conversation properties

ttl

number

example60

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

type

string

custom_data

object

numbers

object

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

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"
   },
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {},
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a"
      }
   }
}

Update a conversation

puthttps://api.nexmo.com/v0.3/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

display_name

string

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

number

example60

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

type

string

custom_data

object

numbers

array

example

[
  {
    "type": "phone",
    "number": "447700900000"
  },
  {
    "type": "sip",
    "uri": "sip:+Htg:;xa",
    "username": "string",
    "password": "string"
  },
  {
    "type": "app",
    "user": "string"
  },
  {
    "type": "websocket",
    "uri": "ws://example.com:8080",
    "content_type": "string"
  },
  {
    "type": "vbc",
    "extension": "447700900000"
  }
]

An array containing number on different channels.

callback

object

url

string(uri)

event_mask

string

params

object

applicationId

string

ncco_url

string(uri)

method

string

Must be one of:POSTGET

Example Request

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": [
      {
         "type": "phone",
         "number": "447700900000"
      },
      {
         "type": "sip",
         "uri": "sip:+Htg:;xa",
         "username": "string",
         "password": "string"
      },
      {
         "type": "app",
         "user": "string"
      },
      {
         "type": "websocket",
         "uri": "ws://example.com:8080",
         "content_type": "string"
      },
      {
         "type": "vbc",
         "extension": "447700900000"
      }
   ],
   "callback": {
      "url": "http://example.com",
      "event_mask": "string",
      "params": {
         "applicationId": "string",
         "ncco_url": "http://example.com"
      },
      "method": "POST"
   }
}

{
   "name": "customer_chat",
   "display_name": "Customer Chat",
   "image_url": "https://example.com/image.png",
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": [
      {
         "type": "phone",
         "number": "447700900000"
      },
      {
         "type": "sip",
         "uri": "sip:+Htg:;xa",
         "username": "string",
         "password": "string"
      },
      {
         "type": "app",
         "user": "string"
      },
      {
         "type": "websocket",
         "uri": "ws://example.com:8080",
         "content_type": "string"
      },
      {
         "type": "vbc",
         "extension": "447700900000"
      }
   ],
   "callback": {
      "url": "http://example.com",
      "event_mask": "string",
      "params": {
         "applicationId": "string",
         "ncco_url": "http://example.com"
      },
      "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

display_name

string

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.

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

properties

object

Conversation properties

ttl

number

example60

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

type

string

custom_data

object

numbers

object

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

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"
   },
   "properties": {
      "ttl": 60,
      "type": "string",
      "custom_data": {
         "property1": "string",
         "property2": "string"
      }
   },
   "numbers": {},
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a"
      }
   }
}

Delete a conversation

deletehttps://api.nexmo.com/v0.3/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.

Available Operations

List user conversations

gethttps://api.nexmo.com/v0.3/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

date_start

string(dateTime)

example2018-01-01 10:00:00

Return the records that occurred after this point in time.

page_size

number

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

number

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

display_name

string

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

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a

_links

object

Required

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

self

object

Required

first

object

href

string

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

self

object

href

string

example

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

object

href

string

example

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

object

href

string

example

https://api.nexmo.com/v0.3/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",
            "timestamp": {
               "created": "2019-09-03T18:40:24.324Z"
            },
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a"
               }
            }
         }
      ]
   },
   "_links": {
      "self": {
         "first": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10"
         },
         "self": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
         },
         "next": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
         },
         "prev": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/conversations?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
         }
      }
   }
}

List user sessions

gethttps://api.nexmo.com/v0.3/users/:user_id/sessions

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

page_size

number

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

number

Required

Min1

Max100

Default10

example10

The amount of records returned in this response

_embedded

object

A list of session objects.

sessions

array

List of session matching the provided filter

string

Required

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

_embedded

object

Required

user

object

Required

string

Required

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

User ID

name

string

Required

examplemy_user_name

Unique name for a user

api_key

string

properties

object

Required

ttl

number(float)

Required

_links

object

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

self

object

Required

first

object

href

string

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

self

object

href

string

example

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

object

href

string

example

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

object

href

string

example

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

Example Response

{
   "page_size": 10,
   "_embedded": {
      "sessions": [
         {
            "id": "SES-63f61863-4a51-4f6b-86e1-46edebio0391",
            "_embedded": {
               "user": {
                  "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
                  "name": "my_user_name"
               },
               "api_key": "string"
            },
            "properties": {
               "ttl": 0
            }
         }
      ]
   },
   "_links": {
      "self": {
         "first": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/sessions?order=desc&page_size=10"
         },
         "self": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/sessions?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
         },
         "next": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/sessions?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
         },
         "prev": {
            "href": "https://api.nexmo.com/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec/sessions?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/v0.3/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

number

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

exampleLEFT

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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

_links

object

href

string(url)

example

https://api.nexmo.com/v0.3/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/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10

self

object

href

string

example

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

object

href

string

example

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

object

href

string

example

https://api.nexmo.com/v0.3/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": "LEFT",
            "_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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
                     }
                  }
               }
            },
            "_links": {
               "href": "https://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
      },
      "next": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
      },
      "prev": {
         "href": "https://api.nexmo.com/v0.3/conversations/CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
      }
   }
}

Create a member

posthttps://api.nexmo.com/v0.3/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

exampleinvited

Invite or join a member to a conversation

Must be one of:invitedjoined

user

object

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

object

A user who joins a conversation as a member can have one channel per membership type. Channels can be app, phone, sip, websocket, or vbc

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

from

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

leg_ids

array

Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

media

object

Media Object

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

Example Request

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

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

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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

example

[
  "LEFT",
  "INVITED"
]

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

Timestamp

joined

string

example2020-01-01T14:00:00.00Z

Timestamp

left

string

example2020-01-01T14:00:00.00Z

Timestamp

initiator

object

joined

object

isSystem

boolean

true if the user was invited by an admin JWT. user_id and member_id will not exist if true

user_id

string

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

User ID

member_id

string

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

Member ID

channel

object

A user who joins a conversation as a member can have one channel per membership type. Channels can be app, phone, sip, websocket, or vbc

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

from

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

leg_ids

array

Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

media

object

example

{
  "audio_settings": {
    "enabled": false,
    "earmuffed": false,
    "muted": false
  }
}

Media Object

_links

object

href

string(url)

example

https://api.nexmo.com/v0.3/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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
            }
         }
      }
   },
   "state": "INVITED",
   "timestamp": {
      "invited": "2020-01-01T14:00:00.00Z",
      "joined": "2020-01-01T14:00:00.00Z",
      "left": "2020-01-01T14:00:00.00Z"
   },
   "initiator": {
      "joined": {
         "isSystem": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "phone",
      "leg_id": "a595959595959595995",
      "from": {
         "type": "app",
         "user": "jamie"
      },
      "to": {
         "type": "app",
         "user": "jamie"
      },
      "leg_ids": [
         {
            "leg_id": "a595959595959595995"
         }
      ]
   },
   "media": {
      "audio_settings": {
         "enabled": false,
         "earmuffed": false,
         "muted": false
      }
   },
   "_links": {
      "href": "https://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
   }
}

Retrieve yourself in a given conversation

gethttps://api.nexmo.com/v0.3/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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

example

[
  "LEFT",
  "JOINED"
]

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

Timestamp

joined

string

example2020-01-01T14:00:00.00Z

Timestamp

left

string

example2020-01-01T14:00:00.00Z

Timestamp

initiator

object

joined

object

isSystem

boolean

true if the user was invited by an admin JWT. user_id and member_id will not exist if true

user_id

string

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

User ID

member_id

string

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

Member ID

channel

object

A user who joins a conversation as a member can have one channel per membership type. Channels can be app, phone, sip, websocket, or vbc

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

from

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

leg_ids

array

Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

media

object

example

{
  "audio_settings": {
    "enabled": false,
    "earmuffed": false,
    "muted": false
  }
}

Media Object

_links

object

href

string(url)

example

https://api.nexmo.com/v0.3/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/v0.3/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": {
         "isSystem": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "phone",
      "leg_id": "a595959595959595995",
      "from": {
         "type": "app",
         "user": "jamie"
      },
      "to": {
         "type": "app",
         "user": "jamie"
      },
      "leg_ids": [
         {
            "leg_id": "a595959595959595995"
         }
      ]
   },
   "media": {
      "audio_settings": {
         "enabled": false,
         "earmuffed": false,
         "muted": false
      }
   },
   "_links": {
      "href": "https://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
   }
}

Retrieve a member

gethttps://api.nexmo.com/v0.3/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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

example

[
  "LEFT",
  "JOINED"
]

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

Timestamp

joined

string

example2020-01-01T14:00:00.00Z

Timestamp

left

string

example2020-01-01T14:00:00.00Z

Timestamp

initiator

object

joined

object

isSystem

boolean

true if the user was invited by an admin JWT. user_id and member_id will not exist if true

user_id

string

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

User ID

member_id

string

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

Member ID

channel

object

A user who joins a conversation as a member can have one channel per membership type. Channels can be app, phone, sip, websocket, or vbc

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

from

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

leg_ids

array

Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

media

object

example

{
  "audio_settings": {
    "enabled": false,
    "earmuffed": false,
    "muted": false
  }
}

Media Object

_links

object

href

string(url)

example

https://api.nexmo.com/v0.3/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/v0.3/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": {
         "isSystem": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "phone",
      "leg_id": "a595959595959595995",
      "from": {
         "type": "app",
         "user": "jamie"
      },
      "to": {
         "type": "app",
         "user": "jamie"
      },
      "leg_ids": [
         {
            "leg_id": "a595959595959595995"
         }
      ]
   },
   "media": {
      "audio_settings": {
         "enabled": false,
         "earmuffed": false,
         "muted": false
      }
   },
   "_links": {
      "href": "https://api.nexmo.com/v0.3/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/v0.3/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

state

string

examplejoined

Must be one of:joinedleft

channel

object

A user who joins a conversation as a member can have one channel per membership type. Channels can be app, phone, sip, websocket, or vbc

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

from

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

leg_ids

array

Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

Example Request

{
   "state": "joined",
   "channel": {
      "type": "phone",
      "leg_id": "a595959595959595995",
      "from": {
         "type": "app",
         "user": "jamie"
      },
      "to": {
         "type": "app",
         "user": "jamie"
      },
      "leg_ids": [
         {
            "leg_id": "a595959595959595995"
         }
      ]
   }
}

{
   "state": "joined",
   "channel": {
      "type": "phone",
      "leg_id": "a595959595959595995",
      "from": {
         "type": "app",
         "user": "jamie"
      },
      "to": {
         "type": "app",
         "user": "jamie"
      },
      "leg_ids": [
         {
            "leg_id": "a595959595959595995"
         }
      ]
   }
}

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/v0.3/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

state

string

example

[
  "LEFT",
  "JOINED"
]

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

Timestamp

joined

string

example2020-01-01T14:00:00.00Z

Timestamp

left

string

example2020-01-01T14:00:00.00Z

Timestamp

initiator

object

joined

object

isSystem

boolean

true if the user was invited by an admin JWT. user_id and member_id will not exist if true

user_id

string

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

User ID

member_id

string

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

Member ID

channel

object

A user who joins a conversation as a member can have one channel per membership type. Channels can be app, phone, sip, websocket, or vbc

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

from

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

One Of

type

string

Required

exampleapp

The type of connection. Must be app

user

string

Required

examplejamie

The username to connect to

leg_ids

array

Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.

leg_id

string

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

media

object

example

{
  "audio_settings": {
    "enabled": false,
    "earmuffed": false,
    "muted": false
  }
}

Media Object

_links

object

href

string(url)

example

https://api.nexmo.com/v0.3/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/v0.3/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": {
         "isSystem": true,
         "user_id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
         "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
      }
   },
   "channel": {
      "type": "phone",
      "leg_id": "a595959595959595995",
      "from": {
         "type": "app",
         "user": "jamie"
      },
      "to": {
         "type": "app",
         "user": "jamie"
      },
      "leg_ids": [
         {
            "leg_id": "a595959595959595995"
         }
      ]
   },
   "media": {
      "audio_settings": {
         "enabled": false,
         "earmuffed": false,
         "muted": false
      }
   },
   "_links": {
      "href": "https://api.nexmo.com/v0.3/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

List events

gethttps://api.nexmo.com/v0.3/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

Query Parameters

page_size

number

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.

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

Responses
Content Type
application/json

Retrieve Events Response Payload Object

page_size

integer

Required

example10

The number of results returned on this page.

_embedded

object

Required

events

array

List of events matching the provided filter

string

Required

example5

Event id. This is a progressive integer

type

string

Required

exampletext

Event type

from

string

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

Member ID

string

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

Member ID

body

object

Required

example

{
  "text": "My Text"
}

Event Body

state

string

exampleLEFT

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

Must be one of:INVITEDJOINEDLEFTUNKNOWN

timestamp

string

Required

example2020-01-01T14:00:00.00Z

Time of creation

href

string(url)

Required

examplehttps://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1

A link towards a conversation event included in Conversation API

_links

object

Required

first

object

href

string

examplehttps://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10

self

object

Required

href

string

example

https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=a30e3b7a3dcda1434f64bbb1a5fa489b

object

href

string

example

https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=4db03d9254d1cdaecc7b1fc15b6bf1a81f3d3151191d784f1327893f8dc96416

object

href

string

example

https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=84963f79fd25785be9706bd38bfd30c264f71964fa4edc8d8b4dd5f30bbd9f7c

Example Response

{
   "page_size": 10,
   "_embedded": {
      "events": [
         {
            "id": "5",
            "type": "text",
            "from": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
            "to": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
            "body": {
               "text": "My Text"
            },
            "state": "LEFT",
            "timestamp": "2020-01-01T14:00:00.00Z",
            "href": "https://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1"
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=a30e3b7a3dcda1434f64bbb1a5fa489b"
      },
      "next": {
         "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=4db03d9254d1cdaecc7b1fc15b6bf1a81f3d3151191d784f1327893f8dc96416"
      },
      "prev": {
         "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=84963f79fd25785be9706bd38bfd30c264f71964fa4edc8d8b4dd5f30bbd9f7c"
      }
   }
}

Create an event

posthttps://api.nexmo.com/v0.3/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

type

string

Required

exampletext

Event type

string

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

Member ID

from

string

Required

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

Member ID

body

object

example

{
  "text": "My Text"
}

Event Body

Example Request

{
   "type": "text",
   "to": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "from": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "body": {
      "text": "My Text"
   }
}

{
   "type": "text",
   "to": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "from": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "body": {
      "text": "My Text"
   }
}

Responses
Content Type
application/json

Create New Event Response Payload Object

string

example5

Event id. This is a progressive integer

timestamp

string

example2020-01-01T14:00:00.00Z

Time of event creation

href

string(url)

examplehttps://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1

A link towards a conversation event included in Conversation API

Example Response

{
   "id": "5",
   "timestamp": "2020-01-01T14:00:00.00Z",
   "href": "https://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1"
}

Retrieve an event

gethttps://api.nexmo.com/v0.3/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

Retrieve an event Content Payload

string

Required

example5

Event id. This is a progressive integer

type

string

Required

exampletext

Event type

from

string

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

Member ID

string

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

Member ID

body

object

Required

example

{
  "text": "My Text"
}

Event Body

state

string

exampleLEFT

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

Must be one of:INVITEDJOINEDLEFTUNKNOWN

timestamp

string

Required

example2020-01-01T14:00:00.00Z

Time of creation

href

string(url)

Required

examplehttps://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1

A link towards a conversation event included in Conversation API

Example Response

{
   "id": "5",
   "type": "text",
   "from": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "to": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
   "body": {
      "text": "My Text"
   },
   "state": "LEFT",
   "timestamp": "2020-01-01T14:00:00.00Z",
   "href": "https://api.nexmo.com/v0.3/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1"
}

Delete an event

deletehttps://api.nexmo.com/v0.3/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

Success response with empty JSON

Example Response

{}

leg

A leg can be a video call, IP call, or PSTN call that users participate in using multiple platforms. With this endpoint you can retrieve the details about all of the legs that took place in your application.

Available Operations

List legs

gethttps://api.nexmo.com/v0.3/legs

Authentication

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

Responses
Content Type
application/json

List Legs Successfully

count

number

Required

example100

The total number of records returned by your request.

page_size

number

Required

Min1

Max100

Default10

example10

The amount of records returned in this response

record_index

number

Required

Return page_size amount of conversations from this index in the response. That is, if your request returns 300 conversations, set record_index to 5 in order to return conversations 50 to 59. The default value is 0. That is, the first page_size calls.

_links

object

Required

self

object

Required

href

string

_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

legs

array

Required

uuid

string

Required

examplea595959595959595995

The id of the leg. rtc_id and call_id are leg id

type

string

examplephone

Channel type

Must be one of:appphonesipwebsocketvbc

conversation_uuid

string

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

The unique identifier for this conversation

state

string

exampleterminated

Leg Status

Must be one of:terminated

from

object

start_time

string

example2020-01-01T14:00:00.00Z

Time of leg start

start_end

string

example2020-01-01T14:00:00.00Z

Time of leg end

_links

object

_embedded

object

Example Response

{
   "count": "100",
   "page_size": 10,
   "record_index": 0,
   "_links": {
      "self": {
         "href": "string"
      }
   },
   "_embedded": {
      "legs": [
         {
            "uuid": "a595959595959595995",
            "type": "phone",
            "conversation_uuid": "CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a",
            "state": "terminated",
            "from": {},
            "to": {},
            "start_time": "2020-01-01T14:00:00.00Z",
            "start_end": "2020-01-01T14:00:00.00Z",
            "_links": {},
            "_embedded": {}
         }
      ]
   }
}

Delete a leg

deletehttps://api.nexmo.com/v0.3/legs/:leg_id

Authentication

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

Path Parameters

leg_id

string

Required

Leg ID

Responses
Content Type
application/json

Success response with empty JSON

Example Response

{}

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

List user sessions

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 yourself in a given conversation

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

List events

Authentication

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

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

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json