conversation member event
 
 

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.

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.

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

There are multiple versions of this API available

Version 1 | Version 2

List Users

GET https://api.nexmo.com/v0.2/users
Host https://api.nexmo.com
GET /v0.2/users

Query Parameter

page_size
integer | Default: 10

The number of results returned per page. The default value is 10. The maximum value is 100.

order
string | Default: asc

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

Must be one of: asc or desc
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

Responses

200 OK
page_size
integer

The number of results returned on this page

cursor
string

Current cursor

_embedded
object
data
object
users
array of objects

List of users matching the provided filter

id
string

The ID of the user

name
string

The name of the user

Example Responses

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

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

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/v0.2/conversations
Host https://api.nexmo.com
GET /v0.2/conversations

Query Parameter

page_size
integer | Default: 10

The number of results returned per page. The default value is 10. The maximum value is 100.

order
string | Default: asc

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

Must be one of: asc or desc
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

date_start
string

Search for conversations created after this ISO8601 date

date_end
string

Search for conversations created before this ISO8601 date

Responses

200 OK
page_size
integer

The number of results returned on this page.

cursor
string

Current cursor

_embedded
object
data
object
conversations
array of objects

List of conversations matching the provided filter

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

The time that the conversation was created

Example Responses

200
{
  "page_size": 10,
  "cursor": "88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0",
  "_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/v0.2/conversations/CON-c4724477-72ac-438e-9fc0-1d3e2ff8728c"
            }
          }
        }
      ]
    }
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
    },
    "next": {
      "href": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
    },
    "prev": {
      "href": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
    }
  }
}

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

GET https://api.nexmo.com/v0.2/conversations/:conversation_id/members
Host https://api.nexmo.com
GET /v0.2/conversations/:conversation_id/members

Path Parameters

conversation_id
string | Required

The ID of the conversation

Query Parameter

page_size
integer | Default: 10

The number of results returned per page. The default value is 10. The maximum value is 100.

order
string | Default: asc

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

Must be one of: asc or desc
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

Responses

200 OK
page_size
integer

The number of results returned on this page

_embedded
object
data
object
members
array of objects

List of members matching the provided filter

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

Example Responses

200
{
  "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/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/members/MEM-e784d5d1-dff2-424a-9de7-bc34f1901177"
            }
          }
        }
      ]
    }
  },
  "_links": {
    "first": {
      "href": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0"
    },
    "next": {
      "href": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55"
    },
    "prev": {
      "href": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb"
    }
  }
}

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

GET https://api.nexmo.com/v0.2/conversations/:conversation_id/events
Host https://api.nexmo.com
GET /v0.2/conversations/:conversation_id/events

Path Parameters

conversation_id
string | Required

The ID of the conversation

Query Parameter

page_size
integer | Default: 10

The number of results returned per page. The default value is 10. The maximum value is 100.

order
string | Default: asc

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

Must be one of: asc or desc
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

start_id
string

The ID to start returning events at

end_id
string

The ID to end returning events at

event_type
string

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

Responses

200 OK
page_size
integer

The number of results returned on this page.

_embedded
object
data
object
events
array

List of events matching the provided filter

Example Responses

200
{
  "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/v0.2/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/v0.2/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/v0.2/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/v0.2/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/v0.2/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/v0.2/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/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10"
    },
    "self": {
      "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=a30e3b7a3dcda1434f64bbb1a5fa489b"
    },
    "next": {
      "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=4db03d9254d1cdaecc7b1fc15b6bf1a81f3d3151191d784f1327893f8dc96416"
    },
    "prev": {
      "href": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=84963f79fd25785be9706bd38bfd30c264f71964fa4edc8d8b4dd5f30bbd9f7c"
    }
  }
}