Conversation API
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
COMMUNITYNO AUTH0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.0",
"servers": [
{
"url": "https://api.nexmo.com/v0.2"
}
],
"info": {
"contact": {
"email": "devrel@vonage.com",
"name": "Vonage DevRel",
"url": "https://developer.nexmo.com/"
},
"description": "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.",
"title": "Conversation API",
"version": "1.0.1",
"x-label": "Beta",
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_www.vonage.com_content_dam_vonage_us-en_api_illustrations_Mobile_APIs_Services.svg"
},
"x-origin": [
{
"format": "openapi",
"url": "https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/conversation.v2.yml",
"version": "3.0"
}
],
"x-providerName": "nexmo.com",
"x-serviceName": "conversation.v2"
},
"tags": [
{
"description": "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.",
"name": "conversation"
},
{
"description": "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.",
"name": "member"
},
{
"description": "Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users",
"name": "event"
}
],
"paths": {
"/conversations": {
"get": {
"description": "Please note that not all data is available in the list endpoint. Once \nyou've identified the conversation you need to work with, use the \n[GET /conversations/:id](#get-conversation) endpoint to fetch all of the conversation details\n",
"operationId": "get-conversations",
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/order"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/date_start"
},
{
"$ref": "#/components/parameters/date_end"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"_embedded": {
"properties": {
"data": {
"properties": {
"conversations": {
"description": "List of conversations matching the provided filter",
"items": {
"$ref": "#/components/schemas/conversation_list"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object",
"x-nexmo-developer-collection-description-shown": true
},
"_links": {
"properties": {
"first": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10",
"type": "string"
}
},
"type": "object"
},
"next": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55",
"type": "string"
}
},
"type": "object"
},
"prev": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb",
"type": "string"
}
},
"type": "object"
},
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"cursor": {
"description": "Current cursor",
"example": "88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0",
"type": "string"
},
"page_size": {
"description": "The number of results returned on this page.",
"example": 10,
"type": "integer"
}
}
}
}
},
"description": "OK"
}
},
"summary": "List Conversations",
"tags": [
"conversation"
]
}
},
"/conversations/{conversation_id}/events": {
"get": {
"operationId": "get-events",
"parameters": [
{
"$ref": "#/components/parameters/conversation_id_parameter"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/order"
},
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/start_id_parameter"
},
{
"$ref": "#/components/parameters/end_id_parameter"
},
{
"$ref": "#/components/parameters/event_type_parameter"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"_embedded": {
"properties": {
"data": {
"properties": {
"events": {
"description": "List of events matching the provided filter",
"items": {
"$ref": "#/components/schemas/all_events"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object",
"x-nexmo-developer-collection-description-shown": true
},
"_links": {
"properties": {
"first": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10",
"type": "string"
}
},
"type": "object"
},
"next": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=4db03d9254d1cdaecc7b1fc15b6bf1a81f3d3151191d784f1327893f8dc96416",
"type": "string"
}
},
"type": "object"
},
"prev": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=84963f79fd25785be9706bd38bfd30c264f71964fa4edc8d8b4dd5f30bbd9f7c",
"type": "string"
}
},
"type": "object"
},
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=a30e3b7a3dcda1434f64bbb1a5fa489b",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"page_size": {
"description": "The number of results returned on this page.",
"example": 10,
"type": "integer"
}
}
}
}
},
"description": "OK"
}
},
"summary": "List Events",
"tags": [
"event"
]
}
},
"/conversations/{conversation_id}/members": {
"get": {
"operationId": "get-members",
"parameters": [
{
"$ref": "#/components/parameters/conversation_id_parameter"
},
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/order"
},
{
"$ref": "#/components/parameters/cursor"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"_embedded": {
"properties": {
"data": {
"properties": {
"members": {
"description": "List of members matching the provided filter",
"items": {
"$ref": "#/components/schemas/member_list"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object",
"x-nexmo-developer-collection-description-shown": true
},
"_links": {
"properties": {
"first": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10",
"type": "string"
}
},
"type": "object"
},
"next": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55",
"type": "string"
}
},
"type": "object"
},
"prev": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb",
"type": "string"
}
},
"type": "object"
},
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"page_size": {
"description": "The number of results returned on this page",
"example": 10,
"type": "integer"
}
}
}
}
},
"description": "OK"
}
},
"summary": "List Members",
"tags": [
"member"
]
}
},
"/users": {
"get": {
"operationId": "get-users",
"parameters": [
{
"$ref": "#/components/parameters/page_size"
},
{
"$ref": "#/components/parameters/order"
},
{
"$ref": "#/components/parameters/cursor"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"_embedded": {
"properties": {
"data": {
"properties": {
"users": {
"description": "List of users matching the provided filter",
"items": {
"$ref": "#/components/schemas/user_list"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object",
"x-nexmo-developer-collection-description-shown": true
},
"_links": {
"properties": {
"first": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/users?order=desc&page_size=10",
"type": "string"
}
},
"type": "object"
},
"next": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/users?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55",
"type": "string"
}
},
"type": "object"
},
"prev": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/users?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb",
"type": "string"
}
},
"type": "object"
},
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/users?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"cursor": {
"description": "Current cursor",
"example": "88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0",
"type": "string"
},
"page_size": {
"description": "The number of results returned on this page",
"example": 10,
"type": "integer"
}
}
}
}
},
"description": "OK"
}
},
"summary": "List Users"
}
}
},
"components": {
"parameters": {
"conversation_id_parameter": {
"description": "The ID of the conversation",
"example": "CON-afe887d8-d587-4280-9aae-dfa4c9227d5e",
"in": "path",
"name": "conversation_id",
"required": true,
"schema": {
"type": "string"
}
},
"cursor": {
"description": "The cursor to start returning results from.\n\nYou 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\n",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "string"
}
},
"date_end": {
"description": "Search for conversations created before this ISO8601 date",
"in": "query",
"name": "date_end",
"required": false,
"schema": {
"type": "string"
}
},
"date_start": {
"description": "Search for conversations created after this ISO8601 date",
"in": "query",
"name": "date_start",
"required": false,
"schema": {
"type": "string"
}
},
"end_id_parameter": {
"description": "The ID to end returning events at",
"example": 19,
"in": "query",
"name": "end_id",
"required": false,
"schema": {
"type": "string"
}
},
"event_id_parameter": {
"description": "The ID of the event",
"example": 9,
"in": "path",
"name": "event_id",
"required": true,
"schema": {
"type": "integer"
}
},
"event_type_parameter": {
"description": "The type of event to search for. Does not currently support custom events",
"example": "text",
"in": "query",
"name": "event_type",
"required": false,
"schema": {
"type": "string"
}
},
"member_id_parameter": {
"description": "The ID of the member",
"example": "MEM-e46d9542-752a-4786-8f12-25a2e623a793",
"in": "path",
"name": "member_id",
"required": true,
"schema": {
"type": "string"
}
},
"order": {
"description": "Show the most (`desc`) / least (`asc`) recently created entries first",
"in": "query",
"name": "order",
"required": false,
"schema": {
"default": "asc",
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
"page_size": {
"description": "The number of results returned per page. The default value is `10`. The maximum value is `100`.",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 10,
"maximum": 100,
"type": "integer"
}
},
"start_id_parameter": {
"description": "The ID to start returning events at",
"example": 13,
"in": "query",
"name": "start_id",
"required": false,
"schema": {
"type": "string"
}
},
"user_id_parameter": {
"description": "The ID of the user",
"example": "USR-e46d9542-752a-4786-8f12-25a2e623a793",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
},
"schemas": {
"all_events": {
"anyOf": [
{
"$ref": "#/components/schemas/text_event"
},
{
"$ref": "#/components/schemas/custom_event"
},
{
"$ref": "#/components/schemas/member_invited_event"
},
{
"$ref": "#/components/schemas/member_left_event"
}
]
},
"conversation_display_name": {
"description": "The public facing name of the conversation",
"example": "Conversation with Ashley",
"type": "string"
},
"conversation_id": {
"description": "Automatically generated conversation ID",
"example": "CON-c4724477-72ac-438e-9fc0-1d3e2ff8728c",
"type": "string"
},
"conversation_image_url": {
"description": "An image URL that you associate with the conversation",
"example": "https://example.com/my-image.png",
"type": "string"
},
"conversation_list": {
"properties": {
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-c4724477-72ac-438e-9fc0-1d3e2ff8728c",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"display_name": {
"$ref": "#/components/schemas/conversation_display_name"
},
"id": {
"description": "The ID of the conversation",
"example": "CON-afe887d8-d587-4280-9aae-dfa4c9227d5e",
"type": "string"
},
"image_url": {
"$ref": "#/components/schemas/conversation_image_url"
},
"name": {
"$ref": "#/components/schemas/conversation_name"
},
"timestamp": {
"properties": {
"created": {
"description": "The time that the conversation was created",
"example": "2019-09-03T18:40:24.324Z",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"conversation_name": {
"description": "Your internal conversation name. Must be unique",
"example": "my-conversation",
"type": "string"
},
"custom_event": {
"allOf": [
{
"description": "Custom",
"properties": {
"body": {
"description": "The body of your `custom` event",
"example": {
"my": "Custom Data"
},
"type": "object"
},
"type": {
"description": "The event type (`custom:<YOUR_IDENTIFIER>`)",
"example": "custom:my_event",
"type": "string"
}
},
"x-tab-id": "custom-event"
},
{
"$ref": "#/components/schemas/event"
}
]
},
"event": {
"properties": {
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events/9",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"from": {
"description": "The member ID of the sender",
"example": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
"type": "string"
},
"id": {
"description": "The ID of the event",
"example": 9,
"type": "integer"
},
"timestamp": {
"description": "The time that the event happened",
"example": "2019-09-12T19:49:21.823Z",
"type": "string"
}
},
"type": "object"
},
"member": {
"allOf": [
{
"$ref": "#/components/schemas/member_list"
},
{
"properties": {
"channel": {
"properties": {
"type": {
"description": "The channel that the member joins with",
"enum": [
"app"
],
"example": "app",
"type": "string"
}
},
"type": "object"
},
"initiator": {
"properties": {
"invited": {
"properties": {
"is_system": {
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"joined": {
"properties": {
"is_system": {
"example": true,
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
},
"media": {
"description": "The current media state for the member",
"properties": {
"audio_settings": {
"description": "The current audio state for the member",
"properties": {
"earmuffed": {
"description": "Can the member hear other participants?",
"example": false,
"type": "boolean"
},
"enabled": {
"description": "Is audio enabled?",
"example": false,
"type": "boolean"
},
"muted": {
"description": "Can the member speak to other participants?",
"example": false,
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
},
"timestamp": {
"properties": {
"invited": {
"description": "The time that an invitation was sent",
"example": "2019-09-03T18:40:24.324Z",
"type": "string"
},
"joined": {
"description": "The time that the conversation was joined",
"example": "2019-09-12T16:27:07.450Z",
"type": "string"
},
"left": {
"description": "The time that the member left the conversation",
"example": "2019-09-13T02:16:55.390Z",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
]
},
"member_invited_event": {
"allOf": [
{
"description": "Member Invited",
"properties": {
"type": {
"description": "The event type (`member:invited`)",
"example": "member:invited",
"type": "string"
}
},
"x-tab-id": "member-invited"
},
{
"$ref": "#/components/schemas/event"
},
{
"properties": {
"body": {
"$ref": "#/components/schemas/member"
}
}
}
]
},
"member_left_event": {
"allOf": [
{
"description": "Member Left",
"properties": {
"type": {
"description": "The event type (`member:left`)",
"example": "member:left",
"type": "string"
}
},
"x-tab-id": "member-left"
},
{
"$ref": "#/components/schemas/event"
},
{
"properties": {
"body": {
"$ref": "#/components/schemas/member"
}
}
}
]
},
"member_list": {
"properties": {
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/members/MEM-e784d5d1-dff2-424a-9de7-bc34f1901177",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"display_name": {
"description": "The display name of the User",
"example": "Ashley Arthur",
"type": "string"
},
"id": {
"description": "Member ID",
"example": "MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e",
"type": "string"
},
"name": {
"description": "The name of the User",
"example": "ashley",
"type": "string"
},
"state": {
"description": "The state that the member is in for this conversation",
"enum": [
"INVITED",
"JOINED"
],
"example": "JOINED",
"type": "string"
},
"user_id": {
"description": "The ID of the User",
"example": "USR-2c52f0ec-7a48-4b52-9d47-df47482b2b7e",
"type": "string"
}
},
"type": "object"
},
"text_event": {
"allOf": [
{
"description": "Text",
"properties": {
"body": {
"description": "The body of the `text` event",
"properties": {
"text": {
"description": "The text sent in this event",
"example": "Hello World",
"type": "string"
}
},
"type": "object"
},
"conversation_id": {
"description": "The ID of the Conversation that the member belongs to",
"example": "CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625",
"type": "string"
},
"type": {
"description": "The event type (`text`)",
"example": "text",
"type": "string"
}
},
"x-tab-id": "text-event"
},
{
"$ref": "#/components/schemas/event"
}
]
},
"user_id": {
"description": "The ID of the user",
"example": "USR-e46d9542-752a-4786-8f12-25a2e623a793",
"type": "string"
},
"user_links": {
"properties": {
"self": {
"properties": {
"href": {
"example": "https://api.nexmo.com/v0.2/users/USR-e46d9542-752a-4786-8f12-25a2e623a793",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"user_list": {
"properties": {
"_links": {
"$ref": "#/components/schemas/user_links"
},
"id": {
"$ref": "#/components/schemas/user_id"
},
"name": {
"$ref": "#/components/schemas/user_name"
}
},
"type": "object"
},
"user_name": {
"description": "The name of the user",
"example": "ashley",
"type": "string"
}
}
}
}