Nexmo Conversation API
Browse all Nexmo APIs★ Only Publicly Available OpenAPI DocumentCommunicationsChat Messagingbearer23 EndpointsREST
For Agents
Build multi-party chat, voice, SMS, and WebRTC conversations with shared persisted history across 23 endpoints.
Use for: Create a new Vonage conversation, Add a member to a Vonage conversation, Post a message event to a Vonage conversation, List members in a Vonage conversation
Not supported: Does not send standalone SMS, place outbound calls, or provision numbers — use for multi-party persisted conversation orchestration only.
The Vonage Conversation API (conversation-api) lets you build multi-party communication features that span IP messaging, PSTN voice, SMS, and WebRTC audio and video on a single shared conversation object. Conversation content is persisted, allowing playback or pickup later. The 23 endpoints cover conversations, members, events, users, legs, and call recording — enough surface to power in-app chat, recorded sales calls, agent-routed support threads, and omnichannel customer experiences.
Install Jentic One Beta
Connect the Conversation API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Conversation API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Conversation API.
Create a Vonage conversation that scopes a multi-party message and event stream
Add and remove members on a conversation to control who can post and receive events
Post events into a conversation to drive in-app chat, custom signalling, or media uploads
List events on a conversation to render the message history in a client
Manage user accounts that participate in conversations across IP messaging, PSTN, SMS, and WebRTC
Trigger and stop call recording on an active conversation for later playback or transcription
Use Cases
Patterns agents use Conversation API for, with concrete tasks.
★ In-app customer support chat
A support web app needs persistent chat threads where customers and agents exchange text and image events. POST /conversations creates the thread, POST /conversations/{conversation_id}/members adds participants, and POST /conversations/{conversation_id}/events streams in messages. Clients render history via GET /conversations/{conversation_id}/events. End-to-end build is roughly a week including auth and UI.
POST /conversations with name 'support-thread-1234', then POST /conversations/{conversation_id}/members for both customer and agent user_ids.
Recorded sales call with transcription
Sales teams record calls for compliance and downstream transcription. Once a Conversation is bound to a call, PUT /conversations/{conversation_id}/record starts and stops recording. Playback URLs flow into the existing analytics pipeline. Implementation is one afternoon plus webhook plumbing.
PUT /conversations/{conversation_id}/record with action 'start' and split: 'conversation' to capture all participants on one stream.
User-scoped conversation listing
When a user logs into a chat client, their inbox is the list of conversations they participate in. GET /users/{user_id}/conversations returns that list with last activity metadata so the client can render the inbox in one round trip. Pagination keeps payloads manageable for power users.
GET /users/{user_id}/conversations with page_size 50 and render the result as the inbox.
Member moderation on policy violation
When a chat moderation system flags a message, it must remove the offending member from the thread. DELETE /conversations/{conversation_id}/members/{member_id} ejects the member; subsequent posts from them will be rejected. The full lifecycle including audit logging takes a few hours.
DELETE /conversations/{conversation_id}/members/{member_id} for the offending member and post a system event noting the moderation.
Agent-driven conversation orchestration
An AI agent running a virtual team standup creates a conversation, adds each team member as a user, and posts a daily prompt event. Through Jentic, the agent searches for 'create vonage conversation', loads POST /conversations, and chains member and event creation calls — credentials stay in the Jentic vault.
Search Jentic for 'create vonage conversation', load schema, POST /conversations, then loop POST /conversations/{conversation_id}/members and POST /conversations/{conversation_id}/events for the standup prompt.
Key Endpoints
23 endpoints — the vonage conversation api (conversation-api) lets you build multi-party communication features that span ip messaging, pstn voice, sms, and webrtc audio and video on a single shared conversation object.
METHOD
PATH
DESCRIPTION
POST
/conversations
Create a conversation
GET
/conversations
List conversations
POST
/conversations/{conversation_id}/members
Add a member to a conversation
POST
/conversations/{conversation_id}/events
Post an event to a conversation
GET
/conversations/{conversation_id}/events
List events in a conversation
PUT
/conversations/{conversation_id}/record
Start or stop conversation recording
GET
/users/{user_id}/conversations
List conversations a user belongs to
POST
/users
Create a user
POST
/conversations
Create a conversation
GET
/conversations
List conversations
POST
/conversations/{conversation_id}/members
Add a member to a conversation
POST
/conversations/{conversation_id}/events
Post an event to a conversation
GET
/conversations/{conversation_id}/events
List events in a conversation
PUT
/conversations/{conversation_id}/record
Start or stop conversation recording
GET
/users/{user_id}/conversations
List conversations a user belongs to
POST
/users
Create a user
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
The Conversation API uses JWT bearer tokens signed with a Vonage Application private key. Jentic stores the private key in the encrypted MAXsystem vault and mints short-lived JWTs per request — the agent never holds the key material directly.
Intent-based discovery
Agents search by intent (e.g. 'list members in a Vonage conversation') and Jentic returns the matching Conversation API operation with its input schema, so the agent invokes it without parsing the OpenAPI spec by hand.
Time to first call
Direct integration: 3-5 days for JWT minting, key rotation, and webhook handling. Through Jentic: under 1 hour — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Conversation API through Jentic.
What authentication does the Vonage Conversation API use?
It uses JWT bearer tokens signed with a Vonage Application private key. Jentic stores the private key in the encrypted MAXsystem vault and mints short-lived JWTs per request, so the agent never holds the raw key.
How are members different from users in the Vonage Conversation API?
A user is a long-lived account on POST /users that can participate in any conversation. A member is the per-conversation join created by POST /conversations/{conversation_id}/members and bound to a user_id. Removing a member does not delete the user.
What are the rate limits for the Vonage Conversation API?
Vonage does not publish a hard per-second cap in the OpenAPI spec for the Conversation API. Treat event posts as the highest-frequency endpoint and batch where possible — clients posting more than several events per second per conversation should rely on Vonage's client SDK to multiplex over a single websocket.
How do I post a message into a conversation through Jentic with the Vonage Conversation API?
Run pip install jentic, search Jentic for 'post vonage conversation event', load POST /conversations/{conversation_id}/events, and execute with type 'text' and a body containing the message text. JWTs are minted from the vault at call time.
Can I record a conversation with the Vonage Conversation API?
Yes. PUT /conversations/{conversation_id}/record accepts an action of 'start' or 'stop' and a split mode controlling whether each participant is captured on a separate stream or mixed.
How many channels does the Vonage Conversation API support?
The Conversation API spans IP messaging, PSTN voice, SMS, and WebRTC audio and video on the same conversation object. A single conversation can therefore carry events from any combination of those channels.
GET STARTED