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

# Nexmo Conversation API

The Vonage Conversation API V2 (conversation.v2) is a read-only surface over the conversation object model. It exposes GET endpoints for conversations, members, events, and users, designed for analytics, compliance review, and admin tooling. The 4 endpoints complement the v0.1 surface, which carries the full create, update, and delete operations.

## For AI agents

Read-only listing over Vonage conversations, members, events, and users for analytics and compliance views.

## Scope

Does not create, update, or delete conversations, members, or events - use for read-only conversation listing only.

## Capabilities

- List Vonage conversations on an account for inventory or audit
- List events recorded on a specific conversation to render a read-only history view
- List members on a conversation to display who participated
- List user objects that exist on the Vonage account to drive a directory view
- Stream conversation history into analytics for retention beyond Vonage's window

## Use cases

### Read-only history export

An analytics pipeline needs to back up conversation history to a data lake. GET /conversations enumerates conversations, then GET `/conversations/{conversation_id}/events` pulls the event stream for each. Pagination keeps memory bounded. Effort is roughly half a day plus storage plumbing.

Example prompt: Iterate GET /conversations and for each id call GET `/conversations/{conversation_id}/events` with cursor pagination, writing every event to the data lake.

### Compliance review of past chats

Compliance reviews require listing every conversation that occurred in a window and the members who participated. GET /conversations with date filters and GET `/conversations/{conversation_id}/members` together produce the review packet. Roughly a day including formatting.

Example prompt: GET /conversations for the review window, then GET `/conversations/{conversation_id}/members` for each id and join into a compliance CSV.

### User directory enumeration

GET /users returns every user object that has ever joined a conversation on the account. An admin dashboard renders this as a searchable directory and links each user to their conversation history. A few hours of integration work.

Example prompt: GET /users with pagination and write the resulting list into the admin dashboard's directory store.

### Agent-driven conversation lookup

A support agent looking at a customer's history asks an AI helper for 'every conversation user_xyz has been in'. The helper searches Jentic for 'list vonage conversations', loads GET /conversations, and filters by the user_id. Credentials stay in your Jentic One instance.

Example prompt: Search Jentic for 'list vonage conversations', load GET /conversations, and execute filtered to the target user_id.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/conversations` | List conversations |
| GET | `/conversations/{conversation_id}/events` | List events on a conversation |
| GET | `/conversations/{conversation_id}/members` | List members on a conversation |
| GET | `/users` | List users |

## Key resources

- **Conversations** — List conversations on the account.
- **Members** — List the members of a given conversation.
- **Events** — List the events of a given conversation.
- **Users** — List user objects on the account.

## Why Jentic

- **Setup:** Wiring this Vonage Conversation API version by hand means minting JWT bearer tokens from your application private key, pointing at the v0.2 host, and paging conversation, member, and event listings yourself. 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:** This API version puts the conversation id in the URL path (`/conversations/{conversation_id}/events`), so a rule can pin your agent to reading one conversation's events and members. This surface is read-only, so the agent has only listing operations to call and no way to create, update, or delete.
- **Credential handling:** Your Vonage application private key is stored once, encrypted, by your own Jentic One instance, which mints short-lived JWTs and injects the bearer token at execution time. The key material never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Vonage conversations' or 'read a conversation's members', 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.
- **Twilio Monitor API** — Twilio's audit and event monitoring API.
- **Vonage Messages API** — Vonage's omnichannel messaging API for SMS, MMS, WhatsApp, Viber, and Facebook Messenger.
- **Plivo API** — Plivo's SMS, voice, and account management platform.

## FAQ

### What authentication does the Vonage Conversation API V2 use?

The Conversation API v0.2 spec does not declare an auth scheme. In production, Vonage requires a JWT bearer token signed with a Vonage Application private key. Jentic stores that key in your Jentic One instance and mints JWTs per call.

### Why is the Vonage Conversation API V2 read-only?

This v0.2 surface only exposes GET endpoints across conversations, members, events, and users. To create or modify resources, use the Conversation API v0.1 surface which provides the full POST, PUT, and DELETE set.

### What are the rate limits for the Vonage Conversation API V2?

Vonage does not publish a per-second cap in the spec. Treat list operations as eventually consistent and prefer cursor pagination over deep page indices for large accounts.

### How do I list members on a conversation through Jentic with the Vonage Conversation API V2?

Run pip install jentic, search Jentic for 'list vonage conversation members', load GET `/conversations/{conversation_id}/members`, and execute. The JWT is minted from the vault at call time.

### Can I post a message with the Vonage Conversation API V2?

No - this v0.2 surface is read-only. Use the v0.1 Conversation API and POST `/conversations/{conversation_id}/events` to post a message into an existing conversation.

### How do I export conversation history with the Vonage Conversation API V2?

Iterate GET /conversations to enumerate ids, then call GET `/conversations/{conversation_id}/events` for each id with cursor-based pagination. Write the events to long-term storage outside Vonage's retention window.

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

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this surface is read-only, so the agent can only call the listing operations (GET /conversations, GET `/conversations/{conversation_id}/events`, GET `/conversations/{conversation_id}/members`, and GET /users) with no way to create, update, or delete anything. Since the conversation id sits in the URL path, a rule can pin the agent to reading one conversation's events and members rather than the whole account. Your Vonage application private key is held only by your own instance and injected at call time, so you control which agents can list conversations at all.