Messaging
Conversations
Read the threads behind your messages — one per contact per sending number — with the WhatsApp service window and every message exchanged, and assign, resolve or reopen them.
A conversation is one thread per contact per sending number, on every channel: channel is whatsapp, email or sms, and senderRef is what the thread is sent from — the WhatsApp number’s id, the email from address, or the SMS header. Inbound messages carry their conversationId, which is also how you reply on the right number.
{
"object": "conversation",
"id": "0c9b8a7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
"contactId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"channel": "whatsapp",
"senderRef": "1098765432",
"senderId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
"status": "open",
"serviceWindowExpiresAt": "2026-11-06T09:30:00.000Z",
"serviceWindowOpen": true,
"lastInboundAt": "2026-11-05T09:30:00.000Z",
"lastOutboundAt": "2026-11-05T09:31:00.000Z",
"lastMessageAt": "2026-11-05T09:31:00.000Z",
"assignedUserId": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
"assignedAt": "2026-11-05T09:30:30.000Z",
"resolvedAt": null,
"version": 7,
"createdAt": "2026-10-30T12:00:00.000Z"
}The service window
On WhatsApp, serviceWindowExpiresAt is the end of the 24-hour customer service window — free-form messages until then, a template after — and serviceWindowOpen says whether it is open now. Email and SMS have no window: they send any time, subject to consent, so on those threads serviceWindowExpiresAt is always null and serviceWindowOpen always false. senderId is the id POST /v1/messages takes for the sender (null once it is no longer connected).
List conversations
GET /v1/conversations (conversations:read) filters by channel, contactId, status (open or resolved) and windowOpen, newest first. windowOpen is a WhatsApp filter: it matches WhatsApp threads only (false means closed or never opened), and with channel=email or channel=sms it is a 400. Each key lists and reads the conversations of its own mode only: every conversation says livemode (false for a test contact’s thread or the sandbox’s), and another mode’s thread is a 404.
curl 'https://api.trovacast.com/v1/conversations?channel=whatsapp&windowOpen=true' \
-H "Authorization: Bearer $TROVACAST_API_KEY"GET /v1/conversations/{conversationId}/messages lists a thread’s messages, newest first. It needs messages:read: conversations:read alone shows threads and windows, not what was said.
curl 'https://api.trovacast.com/v1/conversations/CONVERSATION_ID/messages?limit=50' \
-H "Authorization: Bearer $TROVACAST_API_KEY"conversation.opened fires when a conversation starts waiting for an answer — the customer wrote for the first time, or again after it was resolved, or an agent (or a key) reopened it — and conversation.resolved when an agent (or a key) marks it handled.
Triage
With conversations:write a key does what an assignment manager does in the inbox. Every conversation carries assignedUserId (the member it is assigned to, or null), assignedAt, resolvedAt and version, which moves on every change — an assignment, a resolve, a customer’s message.
POST /v1/conversations/{conversationId}/assign—{ "userId": "…" }or{ "email": "…" }, an active member of the project (anyone else is422 ASSIGNEE_NOT_A_MEMBER), or{ "userId": null }to unassign.POST /v1/conversations/{conversationId}/resolve— marks it handled;conversation.resolvedfires.POST /v1/conversations/{conversationId}/reopen— puts it back in the queue;conversation.openedfires withreason: "api".
Each takes an optional version: sent, the change applies only to the thread as you read it — a resolve with a version from before the customer’s latest message is 409 CONVERSATION_CHANGED rather than closing a thread over a message nobody read. Asking for the state it is already in answers it as it is. Every change is audited against the key and shows in open inboxes at once. A test key is refused (422 TEST_MODE_UNSUPPORTED): a thread is a real customer’s.
curl -X POST 'https://api.trovacast.com/v1/conversations/CONVERSATION_ID/resolve' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 7
}'Endpoints
- GET
/v1/conversationsLists conversations, newest first - GET
/v1/conversations/{conversationId}Retrieves a conversation and its service window - GET
/v1/conversations/{conversationId}/messagesLists a conversation’s messages, newest first - POST
/v1/conversations/{conversationId}/assignAssigns a conversation to a member (or to nobody) - POST
/v1/conversations/{conversationId}/resolveMarks a conversation handled (`conversation.resolved`) - POST
/v1/conversations/{conversationId}/reopenPuts a resolved conversation back in the queue (`conversation.opened`, reason `api`)
Events
| Event | When it is sent | Key scopes |
|---|---|---|
conversation.opened | A conversation now waits for an answer. The customer’s first message on the thread, a customer message on a resolved thread, or an agent or API key reopening it. A reaction never opens one, nor does an outbound send.data: conversation, livemode, reason | conversations:read |
conversation.resolved | A conversation was marked handled. An agent or an API key resolved the thread.data: conversation, livemode | conversations:read |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
API_KEY_SCOPE_MISSING | 403 | The key lacks the scope the endpoint (or a webhook event) requires; requiredScope names it. See Scopes.What to do: Use a key that holds requiredScope: a project administrator creates one in Settings → Developers (an existing key's scopes can be narrowed, never widened). Retrying with this key cannot succeed. |
ASSIGNEE_NOT_A_MEMBER | 422 | The userId or email given to assign a conversation is not an active member of the project — the same answer for an unknown user, a removed member or another project’s user.What to do: Check the userId or email, or add the person to the project in Settings → Members first. |
CONVERSATION_CHANGED | 409 | The conversation moved on since you read it (a new message, another assignment or status change), or the version you sent is not its current one. See Conversations.What to do: Read the conversation again (GET /v1/conversations/{conversationId}) and, if the action still makes sense, retry with its current version. |
CONVERSATION_NOT_FOUND | 404 | The conversationId of a send, or of a conversation read, names no conversation this key can see — another project’s, or one of the other mode: a test thread (the sandbox’s, or a test contact’s) to a live key, a live customer’s to a test key.What to do: Check the id against GET /v1/conversations (or the conversationId of the customer’s message.received) with a key of the same mode, or send by contactId instead. |
NOT_FOUND | 404 | No such resource for this key: another project's id is indistinguishable from one that does not exist. Some endpoints name what is missing with a more specific 404 code; treat any 404 as not found.What to do: Check the id, and that the key belongs to the project and mode that hold it — a test key reads only test records, a live key only live ones. Do not retry unchanged. |
TEST_MODE_UNSUPPORTED | 422 | A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead. |
VALIDATION_FAILED | 400 | The request is malformed; message lists each problem. Also a bulk webhook resend whose until is not after since.What to do: Correct every problem message lists, then send the request again; the same body fails the same way. The API reference has each endpoint's fields. |