Trovacast

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.

A conversation (json)
{
  "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.

WhatsApp threads you can still reply to freely
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.

Read a thread
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 is 422 ASSIGNEE_NOT_A_MEMBER), or { "userId": null } to unassign.
  • POST /v1/conversations/{conversationId}/resolve — marks it handled; conversation.resolved fires.
  • POST /v1/conversations/{conversationId}/reopen — puts it back in the queue; conversation.opened fires with reason: "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.

Resolve the thread you just answered
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

Events

EventWhen it is sentKey scopes
conversation.openedA 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, reasonconversations:read
conversation.resolvedA conversation was marked handled. An agent or an API key resolved the thread.data: conversation, livemodeconversations:read

Errors

CodeStatusMeaning and what to do
API_KEY_SCOPE_MISSING403The 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_MEMBER422The 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_CHANGED409The 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_FOUND404The 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_FOUND404No 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_UNSUPPORTED422A 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_FAILED400The 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.