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.

Download OpenAPI 3 Definition

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

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
None
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
None
Key Description Example Default
speaking_detection_level
number

None

0 None
ttl
number

Time to leave

60 None

View response field descriptions

Response Fields

Field Description
id

The unique identifier for this conversation

href

A link towards a conversation included in Conversation Service API

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

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

The total number of records returned by your request.

page_size

The amount of records returned in this response

record_index

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

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

The unique identifier for this conversation

name

Unique name for a conversation

href

A link towards a conversation included in Conversation Service 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

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
None
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
None
Key Description Example Default
speaking_detection_level
number

None

0 None
ttl
number

Time to leave

60 None

View response field descriptions

Response Fields

Field Description
id

The unique identifier for this conversation

href

A link towards a conversation included in Conversation Service 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

The unique identifier for this conversation

name

Unique name for a conversation

numbers
Field Description
properties
Field Description
video
display_name

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

timestamp
Field Description
created

Time of creation

updated

Time of last update

destroyed

Time of last update

sequence_number

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

Member ID

user_id

User ID

name

Unique name for a user

state

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

One of: invited, joined, left or unknown
timestamp
Field Description
invited

Timestamp

joined

Timestamp

left

Timestamp

initiator
Field Description
joined
Field Description
isSystem

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

user_id

User ID

member_id

Member ID

channel

When a user joins a conversation as a member, they can have one channel per membership. Channels can be app, phone, sip, or websocket

Field Description
type

Channel type

One of: app, phone, sip or websocket
leg_id

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

from
Field Description
type

Channel type

One of: app, phone, sip or websocket
number

this can be a phone number or a random string

to
Field Description
type

Channel type

One of: app, phone, sip or websocket
number

this can be a phone number or a random string

leg_ids
array of s
Field Description
leg_id

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

api_key

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": {
          "type": "phone",
          "number": "a447700900585"
        },
        "to": {
          "type": "phone",
          "number": "a447700900585"
        },
        "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
{}

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

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": "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
channels
object
None
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
to
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
leg_ids
array
None

View response field descriptions

Response Fields

Field Description
name

Unique name for a user

display_name

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

href

A link towards a user included in Conversation Service 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

User ID

name

Unique name for a user

channels
href
{
  "id": "USR-63f61863-4a51-4f6b-86e1-46edebio0391",
  "name": "my_user_name",
  "channels": {},
  "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
None
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
to
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
leg_ids
array
None

View response field descriptions

Response Fields

Field Description
id

User ID

href

A link towards a user included in Conversation Service 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": "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

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": "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
None
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
to
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
leg_ids
array
None
media
object
None
Key Description Example Default
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

Member ID

user_id

User ID

state

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

One of: invited, joined, left or unknown
timestamp
Field Description
invited

Timestamp

joined

Timestamp

left

Timestamp

channel

When a user joins a conversation as a member, they can have one channel per membership. Channels can be app, phone, sip, or websocket

Field Description
type

Channel type

One of: app, phone, sip or websocket
leg_id

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

from
Field Description
type

Channel type

One of: app, phone, sip or websocket
number

this can be a phone number or a random string

to
Field Description
type

Channel type

One of: app, phone, sip or websocket
number

this can be a phone number or a random string

leg_ids
array of s
Field Description
leg_id

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

href

A link towards a member included in Conversation Service API

initiator
Field Description
joined
Field Description
isSystem

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

user_id

User ID

member_id

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": {
      "type": "phone",
      "number": "a447700900585"
    },
    "to": {
      "type": "phone",
      "number": "a447700900585"
    },
    "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

Member ID

href

A link towards a member included in Conversation Service 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
None
Key Description Example Default
type
string

Channel type


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

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

a595959595959595995 None
from
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
to
object
None
Key Description Example Default
type
string

Channel type


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

this can be a phone number or a random string

a447700900585 None
leg_ids
array
None

View response field descriptions

Response Fields

Field Description
id

Member ID

href

A link towards a member included in Conversation Service 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
None
Key Description Example Default

View response field descriptions

Response Fields

Field Description
id

Event id. This is a progressive integer

timestamp

Time of event creation

href

A link towards a conversation event included in Conversation Service 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

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

Event id. This is a progressive integer

type

Event type

from

Member ID

to

Member ID

body

Event Body

state

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

One of: invited, joined, left or unknown
timestamp

Time of creation

href

A link towards a conversation event included in Conversation Service 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

The total number of records returned by your request.

page_size

The amount of records returned in this response

record_index

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

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

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

type

Channel type

One of: app, phone, sip or websocket
conversation_uuid

The unique identifier for this conversation

state

Leg Status

One of: terminated
from
to
start_time

Time of leg start

start_end

Time of leg end

_embedded
{
  "count": "100",
  "page_size": 1,
  "record_index": 1,
  "_links": {
    "self": {
      "href": "abc123"
    }
  },
  "_embedded": {
    "conversations": [
      {
        "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
{}