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

List Conversations

Please note that not all data is available in the list endpoint. Once you've identified the conversation you need to work with, use the GET /conversations/:id endpoint to fetch all of the conversation details

GET https://api.nexmo.com/beta2/conversations

Query Parameter

Key Description Example Default
page_size
integer

The number of results returned per page

None 10
order
string

Show the most (desc) / least (asc) recently created entries first


Must be one of: asc or desc
None asc
cursor
string

The cursor to start returning results from.

You are not expected to provide this manually, but to follow the url provided in _links.next.href in the response which contains a cursor value

None None
date_start
string

Search for conversations created after this ISO8601 date

None None
date_end
string

Search for conversations created before this ISO8601 date

None None

View response field descriptions

Response Fields

Field Description
page_size
integer

The number of results returned on this page

_embedded
object
Field Description
data
object
Field Description
conversations
array of objects

List of conversations matching the provided filter

Field Description
id
string

The ID of the conversation

name
string

Your internal conversation name. Must be unique

display_name
string

The public facing name of the conversation

image_url
string

An image URL that you associate with the conversation

timestamp
object
Field Description
created
string

The time that the conversation was created

{
  "page_size": 10,
  "_embedded": {
    "data": {
      "conversations": [
        {
          "id": "CON-afe887d8-d587-4280-9aae-dfa4c9227d5e",
          "name": "my-conversation",
          "display_name": "Conversation with Ashley",
          "image_url": "https://example.com/my-image.png",
          "timestamp": {
            "created": "2019-09-03T18:40:24.324Z"
          },
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/conversations/CON-c4724477-72ac-438e-9fc0-1d3e2ff8728c"
            }
          }
        }
      ]
    }
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/beta2/conversations?order=desc&page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/beta2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
    },
    "next": {
      "href": "https://api.nexmo.com/beta2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
    },
    "prev": {
      "href": "https://api.nexmo.com/beta2/conversations?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
    }
  }
}

List Users

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

Query Parameter

Key Description Example Default
page_size
integer

The number of results returned per page

None 10
order
string

Show the most (desc) / least (asc) recently created entries first


Must be one of: asc or desc
None asc
cursor
string

The cursor to start returning results from.

You are not expected to provide this manually, but to follow the url provided in _links.next.href in the response which contains a cursor value

None None

View response field descriptions

Response Fields

Field Description
page_size
integer

The number of results returned on this page

_embedded
object
Field Description
data
object
Field Description
users
array of objects

List of users matching the provided filter

Field Description
id
string

The ID of the user

name
string

The name of the user

{
  "page_size": 10,
  "_embedded": {
    "data": {
      "users": [
        {
          "id": "USR-e46d9542-752a-4786-8f12-25a2e623a793",
          "name": "ashley",
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/users/USR-e46d9542-752a-4786-8f12-25a2e623a793"
            }
          }
        }
      ]
    }
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/beta2/users?order=desc&page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/beta2/users?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
    },
    "next": {
      "href": "https://api.nexmo.com/beta2/users?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
    },
    "prev": {
      "href": "https://api.nexmo.com/beta2/users?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
    }
  }
}

List Members

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

The ID of the conversation

CON-afe887d8-d587-4280-9aae-dfa4c9227d5e None

Query Parameter

Key Description Example Default
page_size
integer

The number of results returned per page

None 10
order
string

Show the most (desc) / least (asc) recently created entries first


Must be one of: asc or desc
None asc
cursor
string

The cursor to start returning results from.

You are not expected to provide this manually, but to follow the url provided in _links.next.href in the response which contains a cursor value

None None

View response field descriptions

Response Fields

Field Description
page_size
integer

The number of results returned on this page

_embedded
object
Field Description
data
object
Field Description
members
array of objects

List of members matching the provided filter

Field Description
id
string

Member ID

name
string

The name of the User

display_name
string

The display name of the User

user_id
string

The ID of the User

state
string

The state that the member is in for this conversation

One of: INVITED or JOINED
{
  "page_size": 10,
  "_embedded": {
    "data": {
      "members": [
        {
          "id": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
          "name": "ashley",
          "display_name": "Ashley Arthur",
          "user_id": "USR-2c52f0ec-7a48-4b52-9d47-df47482b2b7e",
          "state": "JOINED",
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/members/MEM-e784d5d1-dff2-424a-9de7-bc34f1901177"
            }
          }
        }
      ]
    }
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/beta2/members?order=desc&page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/beta2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
    },
    "next": {
      "href": "https://api.nexmo.com/beta2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
    },
    "prev": {
      "href": "https://api.nexmo.com/beta2/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
    }
  }
}

List Events

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

Path Parameters

Key Description Example Default
conversation_id
Required | string

The ID of the conversation

CON-afe887d8-d587-4280-9aae-dfa4c9227d5e None

Query Parameter

Key Description Example Default
page_size
integer

The number of results returned per page

None 10
order
string

Show the most (desc) / least (asc) recently created entries first


Must be one of: asc or desc
None asc
cursor
string

The cursor to start returning results from.

You are not expected to provide this manually, but to follow the url provided in _links.next.href in the response which contains a cursor value

None None
start_id
string

The ID to start returning events at

13 None
end_id
string

The ID to end returning events at

19 None
event_type
string

The type of event to search for. Does not currently support custom events

text None

View response field descriptions

Response Fields

Field Description
page_size
integer

The number of results returned on this page

_embedded
object
Field Description
data
object
Field Description
events
array of s

List of events matching the provided filter

This array contains any of the following objects:
Field Description
body
object

The body of the text event

Field Description
text
string

The text sent in this event

type
string

The event type (text)

conversation_id
string

The ID of the Conversation that the member belongs to

id
integer

The ID of the event

from
string

The member ID of the sender

timestamp
string

The time that the event happened

Field Description
body
object

The body of your custom event

type
string

The event type (custom:<YOUR_IDENTIFIER>)

id
integer

The ID of the event

from
string

The member ID of the sender

timestamp
string

The time that the event happened

Field Description
type
string

The event type (member:invited)

id
integer

The ID of the event

from
string

The member ID of the sender

timestamp
string

The time that the event happened

body
Field Description
type
string

The event type (member:left)

id
integer

The ID of the event

from
string

The member ID of the sender

timestamp
string

The time that the event happened

body
{
  "page_size": 10,
  "_embedded": {
    "data": {
      "events": [
        {
          "body": {
            "text": "Hello World"
          },
          "type": "text",
          "conversation_id": "CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625",
          "id": 9,
          "from": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
          "timestamp": "2019-09-12T19:49:21.823Z",
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events/9"
            }
          }
        },
        {
          "body": {
            "my": "Custom Data"
          },
          "type": "custom:my_event",
          "id": 9,
          "from": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
          "timestamp": "2019-09-12T19:49:21.823Z",
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events/9"
            }
          }
        },
        {
          "type": "member:invited",
          "id": 9,
          "from": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
          "timestamp": "2019-09-12T19:49:21.823Z",
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events/9"
            }
          },
          "body": {
            "id": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
            "name": "ashley",
            "display_name": "Ashley Arthur",
            "user_id": "USR-2c52f0ec-7a48-4b52-9d47-df47482b2b7e",
            "state": "JOINED",
            "_links": {
              "self": {
                "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/members/MEM-e784d5d1-dff2-424a-9de7-bc34f1901177"
              }
            },
            "timestamp": {
              "invited": "2019-09-03T18:40:24.324Z",
              "joined": "2019-09-12T16:27:07.450Z",
              "left": "2019-09-13T02:16:55.390Z"
            },
            "channel": {
              "type": "app"
            },
            "initiator": {
              "invited": {
                "is_system": true
              },
              "joined": {
                "is_system": true
              }
            },
            "media": {
              "audio_settings": {
                "enabled": false,
                "earmuffed": false,
                "muted": false
              }
            }
          }
        },
        {
          "type": "member:left",
          "id": 9,
          "from": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
          "timestamp": "2019-09-12T19:49:21.823Z",
          "_links": {
            "self": {
              "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events/9"
            }
          },
          "body": {
            "id": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
            "name": "ashley",
            "display_name": "Ashley Arthur",
            "user_id": "USR-2c52f0ec-7a48-4b52-9d47-df47482b2b7e",
            "state": "JOINED",
            "_links": {
              "self": {
                "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/members/MEM-e784d5d1-dff2-424a-9de7-bc34f1901177"
              }
            },
            "timestamp": {
              "invited": "2019-09-03T18:40:24.324Z",
              "joined": "2019-09-12T16:27:07.450Z",
              "left": "2019-09-13T02:16:55.390Z"
            },
            "channel": {
              "type": "app"
            },
            "initiator": {
              "invited": {
                "is_system": true
              },
              "joined": {
                "is_system": true
              }
            },
            "media": {
              "audio_settings": {
                "enabled": false,
                "earmuffed": false,
                "muted": false
              }
            }
          }
        }
      ]
    }
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=a30e3b7a3dcda1434f64bbb1a5fa489b"
    },
    "next": {
      "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=4db03d9254d1cdaecc7b1fc15b6bf1a81f3d3151191d784f1327893f8dc96416"
    },
    "prev": {
      "href": "https://api.nexmo.com/beta2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=84963f79fd25785be9706bd38bfd30c264f71964fa4edc8d8b4dd5f30bbd9f7c"
    }
  }
}