Skip to navigation
conversation user member event leg
 
 

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

Jump to:

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.

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.

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.

event »

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

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.

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.

Available Operations:

List conversations

This endpoint is DEPRECATED. Please use /v0.2/conversations.

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

conversations
array of objects
uuid
string

The unique identifier for this conversation

name
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

ttl
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

ttl
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
video
boolean
display_name
string

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

timestamp
object
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

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

Timestamp

joined
string

Timestamp

left
string

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

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

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

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

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

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:

List users

This endpoint is DEPRECATED. Please use /v0.2/users.

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

type
string

Channel type

Must be 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

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

to

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

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.

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
created
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:

List members

This endpoint is DEPRECATED. Please use /v0.2/members.

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

type
string

Channel type

Must be 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

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

to

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

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.

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

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

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

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

User ID

member_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

type
string

Channel type

Must be 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

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

to

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

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.

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:

List events

This endpoint is DEPRECATED. Please use /v0.2/events.

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:

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

legs
array of objects
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

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 
{}