Event catalogue
Every event Gauge delivers to webhooks, their payloads, and who receives them.
An endpoint subscribes to events by exact name (support.ticket.created), by family
(support.ticket.*, matched on whole dot-separated segments), or with * for every public
event. A pattern that can never match is refused when you save the endpoint, so a subscription can
never silently receive nothing.
* covers the public catalogue on this page and nothing else. Gauge's internal events never leave
the platform.
Messaging events
LiveDelivered to endpoints created on API version 2026-10-21 or later (every endpoint created since
API v2; apiVersion on the endpoint). An endpoint created before API v2 keeps receiving exactly the
support events below, even on *, until you set its apiVersion.
Each payload is the event's own schema in the reference: ids first, then a minimal snapshot. Every event's full schema is listed under Webhooks there.
Who receives them
An endpoint receives a message or conversation event only when the member who owns the endpoint
(ownerMemberId: whoever created it, or the key's member for an endpoint created with a key) can
see that conversation in the console: their own, their team's, the unassigned queue, or all. Contact
events go to owners who may read contacts. An endpoint whose owner has left receives no
conversation events. Narrow further with connectionIds and projectId (one App) on the endpoint.
Messages
| Event | When |
|---|---|
message.received | A customer sent a message on any channel: text, a file, or the button or list row they tapped. Forwarding guide. |
message.sent | A message was sent to a customer, by a person, Gauge AI, an automation or the API. Fired once per message, when it is created (status is then queued or sent). |
message.status_updated | An outgoing message moved to sent, delivered, read or failed. |
message.received
messageId, conversationId, connection (id, channel family such as whatsapp, kind such
as whatsapp_cloud), contact (id, name, identities[] of { channel, externalId }), kind,
text, media[], reply (the tapped button or list row: { type, id, title }, else null),
quotedMessageId, app (the App the conversation belongs to, else null), receivedAt.
Each media[] item is { index, url, mediaId, contentType, size, filename, available }. Download
the file with GET on url (/v2/messages/{messageId}/attachments/{index}, scope messages:read),
which answers a 5-minute signed link. available: false means Gauge holds no copy of the file (for
example a WhatsApp Web file not fetched yet), and url then answers 404. mediaId is set only for
a file uploaded through POST /v2/media.
message.sent
messageId, conversationId, connection, contact, kind, text, media[] (as above),
authorType (agent, ai, automation (also every API send) or system), status, app,
sentAt.
message.status_updated
messageId, conversationId, connection, status (sent, delivered, read or failed),
error ({ "reason": "…" } on failed, else null), updatedAt.
sent is reported for a message that was queued first (a 202 send, WhatsApp, email) when the
channel accepts it. A message the channel took during the request was created sent, and says so
in its message.sent; no separate sent update follows.
Conversations
| Event | When |
|---|---|
conversation.created | A new conversation started: its first customer or business message. |
conversation.updated | A conversation was opened, snoozed or resolved, or its assignee, team or topic changed. |
conversation.created
conversation (snapshot: id, status, connection, contactId, assigneeId, teamId,
topicId, app, createdAt), contact, initiatedBy (contact or business).
conversation.updated
conversation (the snapshot after the change) and changes: ["status"] or ["assignment"].
Tag, priority and read changes do not raise it.
Contacts
| Event | When |
|---|---|
contact.created | A contact was created, by a person, the API, or a first message from someone new. |
contact.updated | A contact was renamed, merged (or the merge undone), had a handle added or removed, or had fields changed. |
contact (id, name, identities[], mergedIntoId, createdAt) and origin (inbound or
manual) on contact.created, change (renamed, merged, merge_undone, identity_added,
identity_removed, fields_changed) on contact.updated.
Large messages
A delivery body is capped at 64 KB. A message.received or message.sent over it has its text
cut to 4,096 characters, with "truncated": true and "fetchUrl": "/v2/messages/{id}": fetch the
full message there. Any other event still too large is reduced to its ids, truncated: true and
fetchUrl: "/v2/events/{eventId}".
Later, with SMS and voice over the API Coming soon: sms.received, sms.status_updated,
call.completed, call.recording_ready, voicemail.received.
Support events
LiveDelivered today, for the Support API: Apps, their customers, chats, tickets, callbacks, meetings and calls. Each name links to its payload schema in the reference.
| Family | Events |
|---|---|
Callbacks (support.callback.*) | cancelled, completed, failed, requested, scheduled |
Chat (support.chat.*) | answered, ended, handoff_to_ticket, message_created, offered, ownership_changed, queued, session_started, unclaimed |
Customers (support.customer.*) | access_granted, access_revoked, blocked, created, deactivated, unblocked, unread_changed, updated, verified |
Knowledge base (support.kb.*) | article_published, article_unpublished, deflected |
Meetings (support.meeting.*) | cancelled, created, ended, participant_joined, started |
Apps (projects) (support.project.*) | branding_updated, created, updated |
Sign-in links (support.session_link.*) | created, redeemed, revoked |
Tickets (support.ticket.*) | assigned, created, escalated, escalation_acknowledged, merged, replied, sla_breached, split, status_changed, tier_changed, updated |
Support calls (support.voice.*) | abandoned, answered, ended, queued |
Payloads
Every event shares the envelope; payload holds the event's
own fields, and the envelope id is the event id (evt_… for the events above). Payloads carry ids and facts, never secrets or internal routing data. When you need
more, fetch the resource by its id.
Payloads are versioned: new fields can appear at any time (an additive change), so ignore fields you do not know. A breaking change would be a new event name.
The test event
webhook.test is sent only when you choose Send test event. It carries "test": true.
See Testing and replay.