canonical: https://jentic.com/apis/nexmo.com/vonage-conversation

# Nexmo Conversation API

The Vonage Conversation API (conversation) 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.

## For AI agents

Build multi-party chat, voice, SMS, and WebRTC conversations with shared persisted history across 23 endpoints.

## Scope

Does not send standalone SMS, place outbound calls, or provision numbers - use for multi-party persisted conversation orchestration only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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 your Jentic One instance.

Example prompt: 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

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

## Key resources

- **Conversations** — Create, list, retrieve, update, and delete conversation containers and trigger recording.
- **Members** — Add, list, retrieve, update, and remove members within a conversation.
- **Events** — Post, list, retrieve, and delete events such as messages within a conversation.
- **Users** — Create, list, retrieve, update, and delete user objects that participate in conversations.
- **Legs** — List and delete the call legs associated with conversations.

## Why Jentic

- **Setup:** Wiring the Conversation API by hand means minting JWT bearer tokens signed with your Vonage Application private key, refreshing them per request, and pointing every call at the api.nexmo.com/v0.1 host. Through Jentic you install once, import the Conversation API from the API Directory, store the Application private key once, and your agent calls it.
- **Permission scoping:** The Conversation API puts the conversation id in the URL path (`/conversations/{conversation_id}/...`), so a rule can pin your agent to one conversation: it can add members and post events to that conversation and nothing else. You choose the operations it may call, so you can grant reading and posting events while leaving out recording control unless you add it.
- **Credential handling:** Your Vonage Application private key is stored once, encrypted, by your own Jentic One instance and used to mint short-lived JWTs at execution time. The key never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list members in a Vonage conversation' or 'post an event to a conversation', and Jentic returns the matching Conversation API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio Conversations API** — Twilio's omnichannel messaging conversation API.
- **Twilio Chat API** — Twilio's in-app chat platform with channels and members.
- **Vonage Messages API** — Vonage's omnichannel messaging API for SMS, MMS, WhatsApp, Viber, and Facebook Messenger.
- **Vonage Voice API** — Vonage's voice calling API tied to Vonage applications.
- **Plivo API** — Plivo's SMS, voice, and account management platform.

## FAQ

### 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 Jentic One instance 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.

### Can I limit what my agent is allowed to do with the Vonage Conversation API?

Yes. Because Jentic One is self-hosted, your own rules decide which operations and credentials the agent may use. Since the Conversation API carries the conversation id in the URL path, you can pin the agent to a single conversation so it can add members with POST `/conversations/{conversation_id}/members` and post events with POST `/conversations/{conversation_id}/events`, and nothing outside that conversation. You choose the operations it may call, so you can grant reading and posting events while withholding recording control on PUT `/conversations/{conversation_id}/record` unless you explicitly allow it.