Nexmo Conversation API Developer Preview

The Nexmo Conversation API enables you to build conversation features where communication can take place across multiple mediums including IP Messaging, PSTN Voice, SMS and WebRTC Audio and Video. The context of the conversations is maintained though each communication event taking place within a conversation, no matter the medium.

There are multiple versions of this API available

Version 1 | Version 2

Conversation

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

Create a conversation

POST https://api.nexmo.com/beta/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

Key Description Example Default
name
string

Unique name for a conversation

customer_chat None
display_name
string

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

Customer Chat None
image_url
string | (url)

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

https://example.com/image.png None
numbers
object
Key Description Example Default
sms
string

phone number used for sms channel

442079460000 None
pstn
string

phone number used for pstn channel

14155550100 None
properties
object
Key Description Example Default
ttl
number

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

60 None

View response field descriptions

Response Fields

Field Description
id
string

The unique identifier for this conversation

href
string

A link towards a conversation included in Conversation API

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

List conversations

This API endpoint is deprecated. Please use /beta2/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/beta/conversations

Authentication

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

Query Parameter

Key Description Example Default
date_start
string | (dateTime)

Return the records that occurred after this point in time.

2018-01-01 10:00:00 None
date_end
string | (dateTime)

Return the records that occurred before this point in time.

2018-01-01 12:00:00 None
page_size
number

Return this amount of records in the response

None 10
record_index
number

Return calls from this index in the response

None 0
order
string

Return the records in ascending or descending order.


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

View response field descriptions

Response Fields

Field Description
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

Field Description
conversations
array of objects
Field Description
uuid
string

The unique identifier for this conversation

name
string

Unique name for a conversation

href
string

A link towards a conversation included in Conversation API

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

Update a conversation

PUT https://api.nexmo.com/beta/conversations/:conversation_id

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

Request body application/json

Conversation Request Payload Object

Key Description Example Default
name
string

Unique name for a conversation

customer_chat None
display_name
string

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

Customer Chat None
image_url
string | (url)

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

https://example.com/image.png None
numbers
object
Key Description Example Default
sms
string

phone number used for sms channel

442079460000 None
pstn
string

phone number used for pstn channel

14155550100 None
properties
object
Key Description Example Default
ttl
number

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

60 None

View response field descriptions

Response Fields

Field Description
id
string

The unique identifier for this conversation

href
string

A link towards a conversation included in Conversation API

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

Retrieve a conversation

GET https://api.nexmo.com/beta/conversations/:conversation_id

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

View response field descriptions

Response Fields

Field Description
uuid
string

The unique identifier for this conversation

name
string

Unique name for a conversation

numbers
object
Field Description
properties
object
Field Description
video
boolean
display_name
string

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

timestamp
object
Field Description
created
string

Time of creation

updated
string

Time of last update

destroyed
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

Field Description
member_id
string

Member ID

user_id
string

User ID

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
timestamp
object
Field Description
invited
string

Timestamp

joined
string

Timestamp

left
string

Timestamp

initiator
object
Field Description
joined
object
Field Description
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

User ID

member_id
string

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

Field Description
type
string

Channel type

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

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

from
to
leg_ids
array of s

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.

Field Description
leg_id
string

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

api_key
string

The API key for your account

{
  "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/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391"
    }
  }
}

Delete a conversation

DELETE https://api.nexmo.com/beta/conversations/:conversation_id

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

View response field descriptions

Response Fields

Field Description
{}

Record a conversation

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

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

Request body application/json

Record Conversation Request Payload Object

Key Description Example Default
action
Required | string

Recording Action


Must be one of: start or stop
start None
event_url
array
of strings

The webhook endpoint where recording progress events are sent to.

["https://example.com/event"]
None
event_method
string

The HTTP method used to send event information to event_url.

POST POST
split
string

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

conversation conversation
format
string

Record the Conversation in a specific format.


Must be one of: mp3 or wav
mp3 mp3
No Content
Not Found
Bad Request

User

The concept of a user exists in Nexmo APIs, you can associate one with a user in your own application if you choose. A user can have multiple memberships to conversations and can communicate with other users through various different mediums.

List users

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

GET https://api.nexmo.com/beta/users

Authentication

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

View response field descriptions

Response Fields

Field Description
id
string

User ID

name
string

Unique name for a user

href
string

A link towards a user included in Conversation API

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

Create a user

Note: Users must be created with an admin JWT.

POST https://api.nexmo.com/beta/users

Authentication

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

Request body application/json

Key Description Example Default
name
string

Unique name for a user

my_user_name None
display_name
string

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

My User Name None
image_url
string | (url)

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

https://example.com/image.png None

View response field descriptions

Response Fields

Field Description
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

href
string

A link towards a user included in Conversation API

{
  "name": "my_user_name",
  "display_name": "My User Name",
  "href": "https://api.nexmo.com/beta/converations/USR-63f61863-4a51-4f6b-86e1-46edebio0391"
}

Retrieve a user

GET https://api.nexmo.com/beta/users/:user_id

Authentication

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

Path Parameters

Key Description Example Default
user_id
Required | string

User ID

None None

View response field descriptions

Response Fields

Field Description
id
string

User ID

name
string

Unique name for a user

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

Update a user

PUT https://api.nexmo.com/beta/users/:user_id

Authentication

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

Path Parameters

Key Description Example Default
user_id
Required | string

User ID

None None

Request body application/json

Key Description Example Default
name
string

Unique name for a user

my_user_name None
display_name
string

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

My User Name None
image_url
string | (url)

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

https://example.com/image.png None
channels
object
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from

Any one of the following:

Connect to an App User
Key Description Example Default
type
string

The type of connection. Must be app

app None
user
string

The username to connect to

jamie None
Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
to

Any one of the following:

Connect to an App User
Key Description Example Default
type
string

The type of connection. Must be app

app None
user
string

The username to connect to

jamie None
Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
leg_ids
array
None

View response field descriptions

Response Fields

Field Description
id
string

User ID

href
string

A link towards a user included in Conversation API

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

Delete a user

DELETE https://api.nexmo.com/beta/users/:user_id

Authentication

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

Path Parameters

Key Description Example Default
user_id
Required | string

User ID

None None

View response field descriptions

Response Fields

Field Description
{}

List user conversations

GET https://api.nexmo.com/beta/users/:user_id/conversations

Authentication

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

Path Parameters

Key Description Example Default
user_id
Required | string

User ID

None None

View response field descriptions

Response Fields

Field Description
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
Field Description
created
string

Timestamp

[
  {
    "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/beta/converations/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.

List members

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

GET https://api.nexmo.com/beta/conversations/:conversation_id/members

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

View response field descriptions

Response Fields

Field Description
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
[
  {
    "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/beta/conversations/:conversation_id/members

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

Request body application/json

Key Description Example Default
action
string

Invite or join a member to a conversation


Must be one of: invite or join
join None
user_id
Required | string

User ID

USR-63f61863-4a51-4f6b-86e1-46edebio0391 None
member_id
string

Member ID

MEM-63f61863-4a51-4f6b-86e1-46edebio0391 None
channel
Required | object
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from

Any one of the following:

Connect to an App User
Key Description Example Default
type
string

The type of connection. Must be app

app None
user
string

The username to connect to

jamie None
Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
to

Any one of the following:

Connect to an App User
Key Description Example Default
type
string

The type of connection. Must be app

app None
user
string

The username to connect to

jamie None
Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
leg_ids
array
None
media
object
knocking_id
string

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

a972836a-450f-35fa-156c-52a2ab5b7d25 None
member_id_inviting
string

Member ID of the member that sends the invitation

MEM-63f61863-4a51-4f6b-86e1-46edebio0391 None

View response field descriptions

Response Fields

Field Description
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
Field Description
invited
string

Timestamp

joined
string

Timestamp

left
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

Field Description
type
string

Channel type

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

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

from
to
leg_ids
array of s

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.

Field Description
leg_id
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
Field Description
joined
object
Field Description
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

User ID

member_id
string

Member ID

{
  "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/beta/converations/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/beta/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

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None
member_id
Required | string

Member ID

None None

View response field descriptions

Response Fields

Field Description
id
string

Member ID

href
string

A link towards a member included in Conversation API

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

Update a member

PUT https://api.nexmo.com/beta/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

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None
member_id
Required | string

Member ID

None None

Request body application/json

Key Description Example Default
action
string

Invite or join a member to a conversation


Must be one of: invite or join
join None
channel
object
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from

Any one of the following:

Connect to an App User
Key Description Example Default
type
string

The type of connection. Must be app

app None
user
string

The username to connect to

jamie None
Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
to

Any one of the following:

Connect to an App User
Key Description Example Default
type
string

The type of connection. Must be app

app None
user
string

The username to connect to

jamie None
Connect to a Phone (PSTN) number
Key Description Example Default
type
string

The type of connection. Must be phone

phone None
number
string

The phone number to connect to

14155550100 None
dtmfAnswer
string

Provide DTMF digits to send when the call is answered

p*123# None
Connect to a SIP Endpoint
Key Description Example Default
type
string

The type of connection. Must be sip

sip None
uri
string

The SIP URI to connect to

sip:rebekka@sip.example.com None
Connect to a Websocket
Key Description Example Default
type
string

The type of connection. Must be websocket

websocket None
uri
string

None

wss://example.com/socket None
content-type
string

None


Must be one of: audio/l16;rate=8000 or audio/l16;rate=16000
audio/l16;rate=16000 None
headers
object
Key Description Example Default
customer_id
string

This is an example header. You can provide any headers you may need

ABC123 None
Connect to a VBC extension
Key Description Example Default
type
string

The type of connection. Must be vbc

vbc None
extension
string

None

1234 None
leg_ids
array
None

View response field descriptions

Response Fields

Field Description
id
string

Member ID

href
string

A link towards a member included in Conversation API

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

Delete a member

DELETE https://api.nexmo.com/beta/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

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None
member_id
Required | string

Member ID

None None

View response field descriptions

Response Fields

Field Description
{}

Event

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

Create an event

POST https://api.nexmo.com/beta/conversations/:conversation_id/events

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

Request body application/json

Key Description Example Default
type
Required | string

Event type

text None
to
string

Member ID

MEM-63f61863-4a51-4f6b-86e1-46edebio0391 None
from
Required | string

Member ID

MEM-63f61863-4a51-4f6b-86e1-46edebio0391 None
body
object

View response field descriptions

Response Fields

Field Description
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

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

List events

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

GET https://api.nexmo.com/beta/conversations/:conversation_id/events

Authentication

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None

View response field descriptions

Response Fields

Field Description
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

[
  {
    "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/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1"
  }
]

Retrieve an event

GET https://api.nexmo.com/beta/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

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None
event_id
Required | string

Event ID

None None

View response field descriptions

Response Fields

Field Description
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

{
  "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/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1"
}

Delete an event

DELETE https://api.nexmo.com/beta/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

Key Description Example Default
conversation_id
Required | string

Conversation ID

CON-f972836a-550f-45fa-956c-12a2ab5b7d22 None
event_id
Required | string

Event ID

None None

View response field descriptions

Response Fields

Field Description
{}

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.

List legs

GET https://api.nexmo.com/beta/legs

Authentication

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

View response field descriptions

Response Fields

Field Description
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

Field Description
legs
array of objects
Field Description
uuid
string

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

type
string

Channel type

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

The unique identifier for this conversation

state
string

Leg Status

One of: terminated
from
object
to
object
start_time
string

Time of leg start

start_end
string

Time of leg end

_embedded
object
{
  "count": "100",
  "page_size": 1,
  "record_index": 1,
  "_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/beta/legs/:leg_id

Authentication

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

Path Parameters

Key Description Example Default
leg_id
Required | string

Leg ID

None None

View response field descriptions

Response Fields

Field Description
{}