Conversations
List and open conversations, change their status, assignee, team, topic and tags, mark them read, and add internal notes.
A conversation is one contact on one connection: the thread an agent works in the inbox. It has a status, an assignee, tags, and its messages.
| Endpoint | Scope | |
|---|---|---|
GET /v2/conversations | conversations:read | A page of conversations, most recent activity first |
GET /v2/conversations/{id} | conversations:read | One conversation |
PATCH /v2/conversations/{id} | conversations:write | Change status, assignee, team, topic, tags or priority |
POST /v2/conversations/{id}/read | conversations:write | Mark it read for the key's member (200) |
GET /v2/conversations/{id}/messages | messages:read | Its messages, newest first |
POST /v2/conversations/{id}/notes | conversations:write | Add an internal note the customer never sees (201) |
Every one needs a live key that is not pinned to an App. Lists use the standard
pagination. A key sees only conversations its member can see in the
console (their own, their team's, the unassigned queue, or all): anything else is a 404, on the
list and on a direct read alike.
The conversation object
{
"id": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
"status": "open",
"snoozedUntil": null,
"channel": "whatsapp_cloud",
"connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
"contact": { "id": "2b9d4f61-7a3c-4e8b-9d0f-1a2b3c4d5e60", "displayName": "Layla Haddad" },
"assigneeId": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
"teamId": null,
"topicId": null,
"appId": null,
"integrationId": null,
"tags": ["refund"],
"priority": 0,
"unread": false,
"needsReply": true,
"lastMessageAt": "2026-10-21T09:28:40.112Z",
"lastInboundAt": "2026-10-21T09:28:40.112Z",
"createdAt": "2026-10-20T16:02:11.903Z",
"updatedAt": "2026-10-21T09:28:40.112Z"
}status is open, snoozed or resolved. unread is relative to the key's member.
Filters
GET /v2/conversations takes, all optional: status and channel (comma-separated lists, e.g.
status=open,snoozed), connectionId, assignee (me, none or a member id), teamId,
topicId, appId, integrationId, contactId, tag, unread (true/false),
updatedSince (ISO time), priorityMin, priorityMax, and sort (-lastMessageAt, the default,
lastMessageAt, createdAt or -createdAt).
GET /v2/conversations/{id}/messages takes direction (inbound/outbound), and
includeNotes / includeSystem (false by default).
Change a conversation
PATCH /v2/conversations/{id}, with any of:
| Field | |
|---|---|
status | open, snoozed or resolved |
snoozedUntil | With status: snoozed: when to wake it (a future ISO time). Omit to snooze until the customer replies. |
assigneeId | A member id, or null to unassign |
teamId | Move it to a team |
topicId | A topic id, or null to clear |
tags | The whole tag set (replaces). Or use addTags / removeTags to change a few; not both. |
priority | 0 to 1000 |
visitorDetails | App conversations: visitor detail values by field key |
curl -X PATCH https://app.gauge.chat/backend/v2/conversations/c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c \
-H "Authorization: Bearer $GAUGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "resolved", "addTags": ["refunded"] }'The answer is the conversation after the change. Fields are applied in the order of the table; if one is refused (for example an assignee the member may not assign to), the rest are not applied and the error says which.
Leave a note for the team
POST /v2/conversations/{id}/notes · requires Idempotency-Key
curl https://app.gauge.chat/backend/v2/conversations/c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c/notes \
-H "Authorization: Bearer $GAUGE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: note-order-1042-refunded" \
-d '{ "body": "Refund of £42.00 issued in Stripe (re_3Q…)." }'body is plain text up to 8,192 characters; @[Name](memberId) mentions notify that member.
messageId pins the note to one message of the conversation.
Events
A status change (open, snooze, resolve) and an assignment, team or topic change made through the
API raise the same conversation.updated webhook as one
made in the console. Tag and priority changes do not raise a webhook.