Conversation API

Beta

The 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 OAS 3 Definition

Improve this specification

There are multiple versions of this API available

Version 1 | Version 2

conversation

A conversation is a shared core component that Vonage APIs rely on. Conversations happen over multiple mediums and and can have associated Users through Memberships.

List conversations

This API endpoint is deprecated. Please use /v0.2/conversations.
This endpoint will return a maximum of 100 items.

List all conversations associated with your application. This endpoint required an admin JWT. To find all conversations for the currently logged in user, see GET /users/:id/conversations

GET


        https://api.nexmo.com/v0.1/conversations

Host


        https://api.nexmo.com

GET


        /v0.1/conversations

Authentication

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

Query Parameter

date_start

string (dateTime)

Return the records that occurred after this point in time.

date_end

string (dateTime)

Return the records that occurred before this point in time.

page_size

number | Default: 10

Return this amount of records in the response

record_index

number | Default: 0

Return calls from this index in the response

order

string | Default: asc

Return the records in ascending or descending order.

Must be one of: asc, desc, ASC or DESC

Responses

200 List Conversations Response Payload Object.

count

number

The total number of records returned by your request.

page_size

number

The amount of records returned in this response

record_index

number

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.

_embedded

object

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

array of objects

string

The unique identifier for this conversation

string

Unique name for a conversation

Example Responses

200

{
  "count": "100",
  "page_size": 50,
  "record_index": 0,
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v0.1/conversations?page_size=2&record_index=10&"
    }
  },
  "_embedded": {
    "conversations": [
      {
        "uuid": "CON-63f61863-4a51-4f6b-86e1-46edebio0391",
        "name": "customer_chat",
        "_links": {
          "self": {
            "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391"
          }
        }
      }
    ]
  }
}

Create a conversation

POST


        https://api.nexmo.com/v0.1/conversations

Host


        https://api.nexmo.com

POST


        /v0.1/conversations

Authentication

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

Request body application/json

Conversation Request Payload Object

name

string

Unique name for a conversation

display_name

string

The display name for the conversation. It does not have to be unique

image_url

string (url)

A link to an image for conversations' and users' avatars

properties

object

Conversation properties

number

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

Responses

200 Create / Update Conversation Response Payload Object

id

string

The unique identifier for this conversation

href

string

A link towards a conversation included in Conversation API

Example Request

{
  "name": "customer_chat",
  "display_name": "Customer Chat",
  "image_url": "https://example.com/image.png",
  "properties": {
    "ttl": 60
  }
}

Example Responses

200

{
  "id": "CON-63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Update a conversation

PUT


        https://api.nexmo.com/v0.1/conversations/:conversation_id

Host


        https://api.nexmo.com

PUT


        /v0.1/conversations/:conversation_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Request body application/json

Conversation Request Payload Object

name

string

Unique name for a conversation

display_name

string

The display name for the conversation. It does not have to be unique

image_url

string (url)

A link to an image for conversations' and users' avatars

properties

object

Conversation properties

number

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

Responses

200 Create / Update Conversation Response Payload Object

id

string

The unique identifier for this conversation

href

string

A link towards a conversation included in Conversation API

Example Request

{
  "name": "customer_chat",
  "display_name": "Customer Chat",
  "image_url": "https://example.com/image.png",
  "properties": {
    "ttl": 60
  }
}

Example Responses

200

{
  "id": "CON-63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Retrieve a conversation

GET


        https://api.nexmo.com/v0.1/conversations/:conversation_id

Host


        https://api.nexmo.com

GET


        /v0.1/conversations/:conversation_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Responses

200 Retrieve a conversation

uuid

string

The unique identifier for this conversation

name

string

Unique name for a conversation

numbers

object

properties

object

boolean

display_name

string

The display name for the conversation. It does not have to be unique

timestamp

object

string

Time of creation

string

Time of last update

string

Time of last update

sequence_number

string

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

members

array of objects

Users associated to this conversation as members

string

Member ID

string

User ID

string

Unique name for a user

string

The state that the member is in. Possible values are invited, joined, left, or unknown

One of: invited, joined, left or unknown

object

string

Timestamp

string

Timestamp

string

Timestamp

object

boolean

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

string

User ID

string

Member ID

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

string

Channel type

One of: app, phone, sip, websocket or vbc

string

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

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.

string

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

api_key

string

The API key for your account

Example Responses

200

{
  "uuid": "CON-63f61863-4a51-4f6b-86e1-46edebio0391",
  "name": "customer_chat",
  "numbers": {},
  "properties": {
    "video": false
  },
  "display_name": "Customer Chat",
  "timestamp": {
    "created": "2020-01-01T14:00:00.00Z",
    "updated": "2020-01-01T14:05:00.00Z",
    "destroyed": "2020-01-01T14:20:00.00Z"
  },
  "sequence_number": "1",
  "members": [
    {
      "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
      "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
      "name": "my_user_name",
      "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": false,
          "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
          "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
        }
      },
      "channel": {
        "type": "phone",
        "leg_id": "a595959595959595995",
        "from": {},
        "to": {},
        "leg_ids": [
          {
            "leg_id": "a595959595959595995"
          }
        ]
      }
    }
  ],
  "api_key": "abc123",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391"
    }
  }
}

Delete a conversation

DELETE


        https://api.nexmo.com/v0.1/conversations/:conversation_id

Host


        https://api.nexmo.com

DELETE


        /v0.1/conversations/:conversation_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Responses

200 Success response with empty JSON

Example Responses

200

{}

Record a conversation

PUT


        https://api.nexmo.com/v1/conversations/:conversation_id/record

Host


        https://api.nexmo.com

PUT


        /v1/conversations/:conversation_id/record

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Request body application/json

Record Conversation Request Payload Object

action

string | Required

Recording Action

Must be one of: start or stop

event_url

array of strings

The webhook endpoint where recording progress events are sent to.

event_method

string | Default: POST

The HTTP method used to send event information to event_url.

split

string | Default: conversation

Record the sent and received audio in separate channels of a stereo recording

format

string | Default: mp3

Record the Conversation in a specific format.

Must be one of: mp3 or wav

Example Request

{
  "action": "start"
}

{
  "action": "start",
  "event_url": [
    "https://example.com/event"
  ],
  "event_method": "POST",
  "split": "conversation",
  "format": "mp3"
}

Example Responses

204 404 400

No Content

This endpoint does not support application/json

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:

get List users
post Create a user
get Retrieve a user
put Update a user
delete Delete a user
get List user conversations

List users

This API endpoint is deprecated. Please use /v0.2/users
This endpoint will return a maximum of 100 items.

GET


        https://api.nexmo.com/v0.1/users

Host


        https://api.nexmo.com

GET


        /v0.1/users

Authentication

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

Responses

200 List of users

id

string

User ID

name

string

Unique name for a user

href

string

A link towards a user included in Conversation API

Example Responses

200

[
  {
    "id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
    "name": "my_user_name",
    "href": "https://api.nexmo.com/v0.1/users/USR-63f61863-4a51-4f6b-86e1-46edebio0391"
  }
]

Create a user

Note: Users must be created with an admin JWT.

POST


        https://api.nexmo.com/v0.1/users

Host


        https://api.nexmo.com

POST


        /v0.1/users

Authentication

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

Request body application/json

name

string

Unique name for a user

display_name

string

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

image_url

string (url)

A link to an image for conversations' and users' avatars

Responses

200 Create a user response

id

string

User ID

href

string

A link towards a user included in Conversation API

Example Request

{
  "name": "my_user_name",
  "display_name": "My User Name",
  "image_url": "https://example.com/image.png"
}

Example Responses

200

{
  "id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "https://api.nexmo.com/v0.1/users/USR-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Retrieve a user

GET


        https://api.nexmo.com/v0.1/users/:user_id

Host


        https://api.nexmo.com

GET


        /v0.1/users/:user_id

Authentication

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

Path Parameters

user_id

string | Required

User ID

Responses

200 Retrieve a user

id

string

User ID

name

string

Unique name for a user

href

string

Example Responses

200

{
  "id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
  "name": "my_user_name",
  "href": "https://api.nexmo.com/v0.1/users/USR-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Update a user

PUT


        https://api.nexmo.com/v0.1/users/:user_id

Host


        https://api.nexmo.com

PUT


        /v0.1/users/:user_id

Authentication

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

Path Parameters

user_id

string | Required

User ID

Request body application/json

name

string

Unique name for a user

display_name

string

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

image_url

string (url)

A link to an image for conversations' and users' avatars

channels

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

string

Channel type

Must be one of: app, phone, sip, websocket or vbc

string

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

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

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.

Responses

200 Retrieve a user

id

string

User ID

href

string

A link towards a user included in Conversation API

Example Request

{
  "name": "my_user_name",
  "display_name": "My User Name",
  "image_url": "https://example.com/image.png",
  "channels": {
    "type": "phone",
    "leg_id": "a595959595959595995",
    "leg_ids": [
      {
        "leg_id": "a595959595959595995"
      }
    ]
  }
}

Example Responses

200

{
  "id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "https://api.nexmo.com/v0.1/users/USR-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Delete a user

DELETE


        https://api.nexmo.com/v0.1/users/:user_id

Host


        https://api.nexmo.com

DELETE


        /v0.1/users/:user_id

Authentication

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

Path Parameters

user_id

string | Required

User ID

Responses

200 Success response with empty JSON

Example Responses

200

{}

List user conversations

GET


        https://api.nexmo.com/v0.1/users/:user_id/conversations

Host


        https://api.nexmo.com

GET


        /v0.1/users/:user_id/conversations

Authentication

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

Path Parameters

user_id

string | Required

User ID

Responses

200 List user conversations

name

string

Unique name for a conversation

image_url

string

A link to an image for conversations' and users' avatars

display_name

string

The display name for the conversation. It does not have to be unique

state

string

The state that the member is in. Possible values are invited, joined, left, or unknown

One of: invited, joined, left or unknown

member_id

string

Member ID

sequence_number

integer

the id of the last event of the conversation (event's id is an incremental number

href

string

A link towards a resources included in Conversation API

id

string

The unique identifier for this conversation

timestamp

object

string

Timestamp

Example Responses

200

[
  {
    "name": "customer_chat",
    "image_url": "https://example.com/image.png",
    "display_name": "Customer Chat",
    "state": "invited",
    "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
    "sequence_number": "123",
    "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391",
    "id": "CON-63f61863-4a51-4f6b-86e1-46edebio0391",
    "timestamp": {
      "created": "2020-01-01T14:00:00.00Z"
    }
  }
]

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:

get List members
post Create a member
get Retrieve a member
put Update a member
delete Delete a member

List members

This API endpoint is deprecated. Please use /v0.2/members
This endpoint will return a maximum of 100 items.

GET


        https://api.nexmo.com/v0.1/conversations/:conversation_id/members

Host


        https://api.nexmo.com

GET


        /v0.1/conversations/:conversation_id/members

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Responses

200 Members List Object

user_id

string

User ID

user_name

string

Unique name for a user

name

string

Unique name for a user

state

string

The state that the member is in. Possible values are invited, joined, left, or unknown

One of: invited, joined, left or unknown

Example Responses

200

[
  {
    "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
    "user_name": "my_user_name",
    "name": "my_user_name",
    "state": "invited"
  }
]

Create a member

POST


        https://api.nexmo.com/v0.1/conversations/:conversation_id/members

Host


        https://api.nexmo.com

POST


        /v0.1/conversations/:conversation_id/members

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Request body application/json

action

string

Invite or join a member to a conversation

Must be one of: invite or join

user_id

string | Required

User ID

member_id

string

Member ID

channel

object | Required

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

string

Channel type

Must be one of: app, phone, sip, websocket or vbc

string

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

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

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.

media

object

Media Object

knocking_id

string

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

member_id_inviting

string

Member ID of the member that sends the invitation

Responses

201 Create or invite Member in invite state

id

string

Member ID

user_id

string

User ID

state

string

The state that the member is in. Possible values are invited, joined, left, or unknown

One of: invited, joined, left or unknown

timestamp

object

string

Timestamp

string

Timestamp

string

Timestamp

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

string

Channel type

One of: app, phone, sip, websocket or vbc

string

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

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.

string

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

href

string

A link towards a member included in Conversation API

initiator

object

boolean

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

string

User ID

string

Member ID

Example Request

{
  "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391"
}

{
  "action": "join",
  "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
  "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
  "channel": {
    "type": "phone",
    "leg_id": "a595959595959595995",
    "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"
}

Example Responses

201

{
  "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
  "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
  "state": "invited",
  "timestamp": {
    "invited": "2020-01-01T14:00:00.00Z",
    "joined": "2020-01-01T14:00:00.00Z",
    "left": "2020-01-01T14:00:00.00Z"
  },
  "channel": {
    "type": "phone",
    "leg_id": "a595959595959595995",
    "from": {},
    "to": {},
    "leg_ids": [
      {
        "leg_id": "a595959595959595995"
      }
    ]
  },
  "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
  "initiator": {
    "joined": {
      "isSystem": false,
      "user_id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
      "member_id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
    }
  }
}

Retrieve a member

GET


        https://api.nexmo.com/v0.1/conversations/:conversation_id/members/:member_id

Host


        https://api.nexmo.com

GET


        /v0.1/conversations/:conversation_id/members/:member_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

member_id

string | Required

Member ID

Responses

200 Retrieve member payload

id

string

Member ID

href

string

A link towards a member included in Conversation API

Example Responses

200

{
  "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Update a member

PUT


        https://api.nexmo.com/v0.1/conversations/:conversation_id/members/:member_id

Host


        https://api.nexmo.com

PUT


        /v0.1/conversations/:conversation_id/members/:member_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

member_id

string | Required

Member ID

Request body application/json

action

string

Invite or join a member to a conversation

Must be one of: invite or join

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

string

Channel type

Must be one of: app, phone, sip, websocket or vbc

string

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

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

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.

Responses

200 Member retrieved

id

string

Member ID

href

string

A link towards a member included in Conversation API

Example Request

{
  "action": "join",
  "channel": {
    "type": "phone",
    "leg_id": "a595959595959595995",
    "leg_ids": [
      {
        "leg_id": "a595959595959595995"
      }
    ]
  }
}

Example Responses

200

{
  "id": "MEM-63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "https://api.nexmo.com/v0.1/conversations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Delete a member

DELETE


        https://api.nexmo.com/v0.1/conversations/:conversation_id/members/:member_id

Host


        https://api.nexmo.com

DELETE


        /v0.1/conversations/:conversation_id/members/:member_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

member_id

string | Required

Member ID

Responses

200 Success response with empty JSON

Example Responses

200

{}

event

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

Available Operations:

get List events
post Create an event
get Retrieve an event
delete Delete an event

List events

This API endpoint is deprecated. Please use /v0.2/events
This endpoint will return a maximum of 100 items.

GET


        https://api.nexmo.com/v0.1/conversations/:conversation_id/events

Host


        https://api.nexmo.com

GET


        /v0.1/conversations/:conversation_id/events

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Responses

200 Retrieve Events Response Payload Object

id

string

Event id. This is a progressive integer

type

string

Event type

from

string

Member ID

to

string

Member ID

body

object

Event Body

state

string

The state that the member is in. Possible values are invited, joined, left, or unknown

One of: invited, joined, left or unknown

timestamp

string

Time of creation

href

string

A link towards a conversation event included in Conversation API

Example Responses

200

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

Create an event

POST


        https://api.nexmo.com/v0.1/conversations/:conversation_id/events

Host


        https://api.nexmo.com

POST


        /v0.1/conversations/:conversation_id/events

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

Request body application/json

type

string | Required

Event type

to

string

Member ID

from

string | Required

Member ID

body

object

Event Body

Responses

201 Create New Event Response Payload Object

id

string

Event id. This is a progressive integer

timestamp

string

Time of event creation

href

string

A link towards a conversation event included in Conversation API

Example Request

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

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

Example Responses

201

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

Retrieve an event

GET


        https://api.nexmo.com/v0.1/conversations/:conversation_id/events/:event_id

Host


        https://api.nexmo.com

GET


        /v0.1/conversations/:conversation_id/events/:event_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

event_id

string | Required

Event ID

Responses

200 Retrieve an event Content Payload

id

string

Event id. This is a progressive integer

type

string

Event type

from

string

Member ID

to

string

Member ID

body

object

Event Body

state

string

The state that the member is in. Possible values are invited, joined, left, or unknown

One of: invited, joined, left or unknown

timestamp

string

Time of creation

href

string

A link towards a conversation event included in Conversation API

Example Responses

200

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

Delete an event

DELETE


        https://api.nexmo.com/v0.1/conversations/:conversation_id/events/:event_id

Host


        https://api.nexmo.com

DELETE


        /v0.1/conversations/:conversation_id/events/:event_id

Authentication

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

Path Parameters

conversation_id

string | Required

Conversation ID

event_id

string | Required

Event ID

Responses

200 Success response with empty JSON

Example Responses

200

{}

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:

get List legs
delete Delete a leg

List legs

GET


        https://api.nexmo.com/v0.1/legs

Host


        https://api.nexmo.com

GET


        /v0.1/legs

Authentication

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

Responses

200 List Legs Successfully

count

number

The total number of records returned by your request.

page_size

number

The amount of records returned in this response

record_index

number

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.

_embedded

object

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

array of objects

string

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

string

Channel type

One of: app, phone, sip, websocket or vbc

string

The unique identifier for this conversation

string

Leg Status

One of: terminated

object

string

Time of leg start

string

Time of leg end

object

Example Responses

200

{
  "count": "100",
  "page_size": 50,
  "record_index": 0,
  "_links": {
    "self": {
      "href": "abc123"
    }
  },
  "_embedded": {
    "legs": [
      {
        "uuid": "a595959595959595995",
        "type": "phone",
        "conversation_uuid": "CON-63f61863-4a51-4f6b-86e1-46edebio0391",
        "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

DELETE


        https://api.nexmo.com/v0.1/legs/:leg_id

Host


        https://api.nexmo.com

DELETE


        /v0.1/legs/:leg_id

Authentication

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

Path Parameters

leg_id

string | Required

Leg ID

Responses

200 Success response with empty JSON

Example Responses

200

{}

Conversation API

Jump to:

There are multiple versions of this API available

conversation

Available Operations:

List conversations

Authentication

Query Parameter

Responses

Example Responses

Create a conversation

Authentication

Request body application/json

Responses

Example Request

Example Responses

Update a conversation

Authentication

Path Parameters

Request body application/json

Responses

Example Request

Example Responses

Retrieve a conversation

Authentication

Path Parameters

Responses

Example Responses

Delete a conversation

Authentication

Path Parameters

Responses

Example Responses

Record a conversation

Authentication

Path Parameters

Request body application/json

Example Request

Example Responses

user

Available Operations:

List users

Authentication

Responses

Example Responses

Create a user

Authentication

Request body application/json

Responses

Example Request

Example Responses

Retrieve a user

Authentication

Path Parameters

Responses

Example Responses

Update a user

Authentication

Path Parameters

Request body application/json

Responses

Example Request

Example Responses

Delete a user

Authentication

Path Parameters

Responses

Example Responses

List user conversations

Authentication

Path Parameters

Responses

Example Responses

member

Available Operations:

List members

Authentication

Path Parameters

Responses

Example Responses