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.
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.
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.
Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users
GET
https://api.nexmo.com/v0.2/users
Host
https://api.nexmo.com
GET
/v0.2/users
The number of results returned per page. The default value is 10. The maximum value is 100.
Show the most (desc) / least (asc) recently created entries first
asc or desc
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
The number of results returned on this page
Current cursor
List of users matching the provided filter
The ID of the user
The name of the user
{
"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"
}
}
}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.
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
The number of results returned per page. The default value is 10. The maximum value is 100.
Show the most (desc) / least (asc) recently created entries first
asc or desc
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
Search for conversations created after this ISO8601 date
Search for conversations created before this ISO8601 date
The number of results returned on this page.
Current cursor
List of conversations matching the provided filter
The ID of the conversation
Your internal conversation name. Must be unique
The public facing name of the conversation
An image URL that you associate with the conversation
The time that the conversation was created
{
"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"
}
}
}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.
GET
https://api.nexmo.com/v0.2/conversations/:conversation_id/members
Host
https://api.nexmo.com
GET
/v0.2/conversations/:conversation_id/members
The ID of the conversation
The number of results returned per page. The default value is 10. The maximum value is 100.
Show the most (desc) / least (asc) recently created entries first
asc or desc
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
The number of results returned on this page
List of members matching the provided filter
Member ID
The name of the User
The display name of the User
The ID of the User
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/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"
}
}
}Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users
GET
https://api.nexmo.com/v0.2/conversations/:conversation_id/events
Host
https://api.nexmo.com
GET
/v0.2/conversations/:conversation_id/events
The ID of the conversation
The number of results returned per page. The default value is 10. The maximum value is 100.
Show the most (desc) / least (asc) recently created entries first
asc or desc
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
The ID to start returning events at
The ID to end returning events at
The type of event to search for. Does not currently support custom events
The number of results returned on this page.
List of events matching the provided filter
{
"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.823+00:00",
"_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.823+00:00",
"_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.823+00:00",
"_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.823+00:00",
"_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"
}
}
}