The Conversation API is a low-level API that allows you to create various objects such as Users, Members, and Conversations.
Conversations are the fundamental concept the API revolves around. Conversations are containers of communications exchanged between two or more Users which could be a single interaction or the history of all interactions between them.
The API also allows you to create Events and Legs to enable text, voice and video communications between two Users and store them in Conversations.
Text, voice and video communications can currently flow through various Channels like App, Phone, SIP, and Websocket. To enable the App channel (for in-app messaging, voice and video), you would need to also utilize our Nexmo Client SDK.
Phone, SIP and Websocket Channels are enabled through the Voice API and they all flow into Conversations.
This API is currently in Developer Preview.
Nexmo always welcomes your feedback. Your suggestions help us improve the product. If you do need help, please email email@example.com and include Conversation API in the subject line. Please note that during the Developer Preview period support times are limited to Monday to Friday.
The Conversation API currently supports a range of communication channels described in this documentation.
As the Conversation API expands to support more and more Nexmo services, the supported Channels will also expand. Conversations would, as a result, become the container for the history of all your communication exchanged via Nexmo Services. This history would then be accessible through the Conversation API.
IMPORTANT: If you are in APAC region there are some limitations. Please contact firstname.lastname@example.org for information on how to obtain APAC LVN support via our Singapore servers.
You should be familiar with the following before you use the Conversation API:
- Create a Nexmo account
- Rent a Nexmo Number
- Install the Beta version of the Nexmo Command Line tools
- Create a Nexmo Application using the command line tools or Dashboard
- Set up Ngrok
NOTE: Ngrok is typically used to test a webhook server (web application) locally. Alternatively you can host your application on the web using your preferred hosting provider.
The Conversation API is authenticated using JWTs. You can generate a JWT with the following command:
JWT="$(nexmo jwt:generate private.key exp=$(($(date +%s)+86400)) application_id=NEXMO_APPLICATION_ID)"
You can then view the JWT with:
You need to replace
NEXMO_APPLICATION_ID with the ID for your application. Also,
private.key is the key associated with this same application.
You can verify your JWT at jwt.io.
To make an example Conversation API call:
Add the following to
# Gets a list of conversations from an application ID (app ID is in the JWT). curl "https://api.nexmo.com/beta/conversations" \ -H 'Authorization: Bearer '$JWT\ -H 'Content-Type: application/json'
Save this file to your machine and run it:
- Application: A Nexmo Application provides a container for Users and Conversations.
- User: A User represents an entity such as a person that wishes to communicate.
- Conversation: A Conversation connects Users and allows them to communicate.
- Member: A Member is created when a User joins a Conversation.
- Call: A Call consists of one or more Legs.
- Channel: A Channel refers to one of App, Phone, SIP or Websocket.
- Leg: A Leg connects a User with a Conversation.
- Media: Media refers to type of communication. It is currently one of text, voice, or video.
- Event: Conversations are event-driven. Event objects are generated when key activities occur.
- Session: A Session is a live communication stream created with a Client SDK.
- How to generate JWTs: This topic explains how to generate JWTs for use in your app. JSON Web Tokens (JWTs) and Access Control Lists (ACLs) are a key concept to understand in order to authenticate your apps and users.
Code snippets provide ready to use samples of code so you can build out your application quickly.
You could start by Creating a Conversation.