# Use Gauge with AI tools (/ai-tools)

Coding assistants write better integrations when they read the real docs instead of guessing.
These docs are published in forms AI tools can read directly.

## Give your assistant the docs [#give-your-assistant-the-docs]

| | |
| --- | --- |
| [`/llms.txt`](/llms.txt) | An index of every page with a one-line summary, following the [llms.txt](https://llmstxt.org) convention. Point an assistant here first. |
| [`/llms-full.txt`](/llms-full.txt) | Every guide in one plain-text file. Paste it, or attach it, as context. |
| [`/openapi/v2.json`](/openapi/v2.json) | The exact OpenAPI 3.1 document: every endpoint, schema, scope and error. |
| **Copy page** | The button at the top of every page copies it as Markdown. **Open** sends it to ChatGPT or Claude. |

A prompt that works well:

> Read https://docs.gauge.chat/llms.txt and https://docs.gauge.chat/openapi/v2.json. Using plain
> `fetch` (no SDK), write a Node function that sends a WhatsApp message with the Gauge API, with an
> `Idempotency-Key`, and retries on 429 using `Retry-After`.

## Keep keys out of prompts [#keep-keys-out-of-prompts]

Never paste an API key or a webhook signing secret into an AI tool. Use an environment variable
(`GAUGE_API_KEY`) in the code it writes, and set the value yourself.

## Coming next: a Gauge MCP server [#coming-next-a-gauge-mcp-server]

<Status is="soon" />

The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools
directly. A Gauge MCP server is planned. It will be generated from the same OpenAPI document as this
reference, and will be **read-only by default**: an assistant could look up conversations, contacts
and connections with your key, and could only send when you grant it a key with write scopes.

Until then, the files above give an assistant everything it needs to write the integration with
you.


# Authentication and keys (/authentication)

Every request is authenticated with an API key, sent as a bearer token:

```http
GET /backend/v2/me HTTP/1.1
Host: app.gauge.chat
Authorization: Bearer pulse_k_live_9c2Rk1...
```

A request without a key, or with an unknown, revoked or expired one, gets `401 unauthorized`.

## Who can create keys [#who-can-create-keys]

- **The workspace must be on a paid plan.** The API is available on **Growth** and **Scale**. On
  Free, every request answers `402 plan_required` ([Plans](/conventions/plans)).
- **The member must be allowed to manage API keys.** Keys are created in **Developers → API keys**
  by a member whose role includes the API keys permission.

## Keys belong to a person [#keys-belong-to-a-person]

A key is not a free-floating credential. It acts **as the member who created it**:

- It can only do what that member can do in the console. A key never sees a conversation its
  member could not open, so a key made by an Agent who sees only their own conversations sees only
  those.
- Contacts are the exception the console already makes: every member with contact access sees the
  whole workspace's contacts, and so does their key.
- If the member is deactivated or removed, **every key they made stops working at once** with
  `401 key_owner_inactive`. Create a new key under an active member and swap it in.

<Callout type="warn" title="Plan for people leaving">
  Create integration keys from a member who will stay, such as an owner or a dedicated integration
  seat, and keep a note of who owns which key. The **API keys** list shows each key's creator.
</Callout>

## Scopes [#scopes]

A key carries a list of scopes; each endpoint needs one. The scope a route needs is shown on every
[reference](/reference) page (`x-scopes`). A key's power is **its scopes and its member's role,
together**: a scope the member's role cannot use grants nothing.

| Scope | Lets the key | Needs this in the member's role |
| --- | --- | --- |
| `conversations:read` | List and open conversations the member can see | Conversations · view |
| `conversations:write` | Change status, assignee and tags; mark read | Conversations · view, create, edit |
| `messages:read` | Read message history and delivery status, and download a message's files | Conversations · view |
| `messages:write` | Send messages and templates as the member | Conversations · view, create |
| `contacts:read` | List, search and open contacts | Contacts · view |
| `contacts:write` | Create, edit, upsert, tag and merge contacts. Erasing one (`DELETE`) also needs the member to hold the erasure right (Owner or Admin) | Contacts · view, create, edit |
| `connections:read` | See connected channels and what each can send | Conversations · view |
| `templates:read` | See approved WhatsApp templates | Conversations · view |
| `media:read` | Get short-lived links to files you uploaded with `POST /v2/media` | Conversations · view |
| `media:write` | Upload files to attach to messages | Conversations · view, create |
| `webhooks:read` | List webhook endpoints and their delivery state | Settings · view |
| `webhooks:write` | Create, change, test and rotate webhook endpoints; redeliver events | Settings · view, edit |
| `events:read` | List and read the last 30 days of events | Settings · view |

**Write includes read.** `messages:write` also grants `messages:read`.

**Wildcards.** `*:read` grants every area's `:read` scope, and `*:write` grants every area scope.
They are capped at use to exactly what the member holds, so a wildcard can never reach further than
the member's role.

**Spending scopes.** `sms-send` and `voice-dial` are reserved for SMS and calls over the API,
which open after a compliance review. They are granted **only by name**: no wildcard, and no key
created as "full access", ever includes them.

**You cannot grant what you do not have.** When you create a key, the console offers only the
scopes your own role can use. Asking for more over the console API answers
`400 validation_failed` with "Your role cannot grant: …".

When a key calls a route without the scope it needs, the answer is `403 insufficient_scope`, and
`error.details.required` names the missing scope.

<Callout title="Version 1 scopes">
  Keys made for `/v1` carry v1 scopes such as `contacts:rw` or `support:read`. They keep working on
  `/v1`. A v1 `<area>:rw` scope also counts as `<area>:write` on `/v2`.
</Callout>

## Environments [#environments]

Every key is **live** or **test**, fixed when it is created and visible in its prefix:

| | Live key | Test key |
| --- | --- | --- |
| Prefix | `pulse_k_live_` | `pulse_k_test_` |
| Reaches | Your real workspace data | Sandbox data only |
| `GET /v2/me` `key.environment` | `live` | `test` |

### Test keys [#test-keys]

A test key works only on endpoints that support the sandbox. Elsewhere it answers
`403 forbidden` with `reason: sandbox_key_not_supported`; nothing it does can reach a real
customer. Test keys are accepted by `/v2/me`, `/v2/connections`, `/v2/templates` and the
[Support API](/support).

**Test keys are refused on every messaging and webhook route**: contacts, conversations,
messages, media, `/v2/webhook-endpoints` and `/v2/events`. There is no sandbox send: a send always
reaches a real customer, so it needs a live key. To try a send safely, send to your own number or
address on a live key.

<Callout title="Key prefixes">
  Keys are issued as `pulse_k_live_…` and `pulse_k_test_…` today. A `gauge_live_` / `gauge_test_`
  prefix is planned; when it ships, existing keys keep working unchanged.
</Callout>

## Pinning a key to an App [#pinning-a-key-to-an-app]

If you use the [Support API](/support), you can pin a key to one **App** (a support project). A
pinned key sees only that App's data: on `/v2/connections`, only the App's chat line. On `/v2` a
key may be pinned to **one** App; a key pinned to several answers `403 forbidden` with
`reason: key_pinned_to_projects`. `GET /v2/me` returns the pin as `key.pinnedAppId`.

A pinned key can read `/v2/me` and `/v2/connections`, and manage the webhook endpoints and events of
its own App. It is **refused on the messaging routes** (contacts, conversations, messages, media,
templates) with `403 forbidden` and `reason: key_pinned_to_projects`: a contact or a conversation
belongs to no single App. Use an unpinned key for messaging.

## IP allowlist [#ip-allowlist]

Give a key a list of up to 20 IPv4 or IPv6 addresses or CIDR ranges (`203.0.113.7`,
`198.51.100.0/24`, `2001:db8::/32`), and it works only from those addresses. A request from
anywhere else answers `403 forbidden` with `reason: ip_not_allowed`. An empty list means any
address.

## Expiry [#expiry]

A key can expire after 30, 60, 90 or 365 days, or never. After its expiry it answers
`401 unauthorized`. Expiring keys are a good default for anything that is not a long-lived server
integration.

## Rotating a key [#rotating-a-key]

Rotate (**roll**) a key from its row in **Developers → API keys**. Rolling issues a new secret for
the same key: same name, scopes, pin, allowlist and usage history. You choose how long the old
secret keeps working alongside the new one:

| Overlap | Use it when |
| --- | --- |
| 0 hours | The key leaked. The old secret stops at once. |
| 1 hour | You can redeploy within the hour. |
| 24 hours | A normal scheduled rotation. |
| 72 hours | Several systems share the key and take time to update. |

During the overlap both secrets authenticate. Deploy the new one, then let the old one lapse.

To stop a key for good, **revoke** it. Revocation is immediate and cannot be undone.

## Keeping keys safe [#keeping-keys-safe]

- Keep keys on your server. Never ship one in a browser bundle, a mobile app, or a public repository.
- One key per integration, so you can rotate or revoke one without breaking the others.
- Grant the fewest scopes that work, and add an IP allowlist for fixed servers.
- Every request a key makes is in **Developers → Logs** for 14 days, by key, status and request id.

## Authentication errors [#authentication-errors]

| Status | `error.code` | `reason` | Meaning |
| --- | --- | --- | --- |
| 401 | `unauthorized` | | No key, or an unknown, revoked, expired or rolled-out key |
| 401 | `key_owner_inactive` | `key_owner_inactive` | The key's member is no longer active |
| 402 | `plan_required` | | The workspace is not on Growth or Scale |
| 403 | `workspace_suspended` | | The workspace is suspended; contact Gauge support |
| 403 | `forbidden` | `ip_not_allowed` | The request came from outside the key's allowlist |
| 403 | `forbidden` | `sandbox_key_not_supported` | A test key on an endpoint without sandbox support |
| 403 | `forbidden` | `key_pinned_to_projects` | A pinned key on an endpoint that cannot honour the pin |
| 403 | `insufficient_scope` | | The key, or its member's role, lacks the route's scope |

The full list is in [Errors](/conventions/errors).


# Changelog (/changelog)

Breaking changes only ship behind a new [`Gauge-Version`](/conventions/versioning) date and are
announced here first, with a `Deprecation` and `Sunset` period.

## 21 October 2026: start WhatsApp Cloud conversations with a template [#21-october-2026-start-whatsapp-cloud-conversations-with-a-template]

Additive, on API version `2026-10-21`.

- `POST /v2/messages` with `to` or `contactId` and an approved `template` now **starts a WhatsApp
  Cloud conversation**: Gauge creates or reuses the contact and the conversation and sends the
  template. The connection reports `startConversations: true` when templates are enabled.
  [Start a conversation with a template](/messaging/templates#start-a-conversation-with-a-template).
- Free text to someone on WhatsApp Cloud with no conversation answers `422` with reason
  `outside_24h_window` (it answered `cannot_start_conversations` before).
- New `422` reasons, checked before anything is written: `template_not_approved`,
  `template_language_not_found`, `template_variable_mismatch` (previously a template that was not
  approved, or a missing variable, was refused without a `reason`; extra variables were ignored and
  are now refused).

## 21 October 2026: messaging and webhooks on `/v2` [#21-october-2026-messaging-and-webhooks-on-v2]

Additive, on API version `2026-10-21`.

**New**

- [Messaging](/messaging): contacts (with upsert by channel identity, tags, merge and GDPR erasure),
  conversations (filters, status, assignment, team, topic, tags, notes, read), messages (text,
  templates, buttons and lists, files, quoted replies, metadata), media uploads, and templates.
- `POST /v2/messages` answers `201` when sent during the request and **`202` with `status: queued`**
  when dispatched in the background; the `Idempotency-Key` also de-duplicates the send beyond 24 hours.
- WhatsApp Web [warm-up caps](/channels/whatsapp-web#send-caps) (`429`, `whatsapp_web_minute_cap` /
  `whatsapp_web_daily_cap`) and the `whatsapp_web_unofficial` warning on every send.
- `GET /v2/messages/{id}/attachments/{index}`: a signed download of any file on a message.
- `503 media_unavailable` on file uploads and downloads where a deployment has no public storage.
- [Message events](/webhooks/events): `message.received`, `message.sent`,
  `message.status_updated` (including `sent` for queued messages), `conversation.created`,
  `conversation.updated`, `contact.created`, `contact.updated`, delivered by the owner's visibility.
- [Webhooks from code](/webhooks#manage-endpoints-from-code): `/v2/webhook-endpoints` and the 30-day
  event log `/v2/events`, with redelivery (20 an hour per workspace, shared with the console).
- The `Gauge-Signature` header (`t=<ms>,v1=<hex>`) and `Gauge-Event-Id`, `Gauge-Event-Type`,
  `Gauge-Delivery-Attempt`, `Gauge-Webhook-Id` on every delivery; the `x-pulse-*` headers stay.

**Changed**

- An endpoint failing every delivery for 3 days is [switched off](/webhooks/delivery#endpoints-that-keep-failing-are-switched-off)
  and its owner told.
- A delivery body is capped at 64 KB; a longer message is truncated with a `fetchUrl`.
- Test keys and App-pinned keys are refused on the messaging routes.

## 21 October 2026: API version `2026-10-21` [#21-october-2026-api-version-2026-10-21]

The first dated version of `/v2`.

**New**

- `GET /v2/me`: who a key is, its scopes, environment and rate-limit budget.
- `GET /v2/connections` and `GET /v2/connections/{id}`: connected channels with their effective
  API capabilities, and a ban-risk `warning` on WhatsApp Web.
- `GET /v2/openapi.json`: a generated OpenAPI 3.1 document with shared `Error` and `Page` schemas,
  an `operationId` and tags on every operation, and the webhook catalogue.
- One [error envelope](/conventions/errors) and a closed list of error codes on `/v1` and `/v2`.
- `X-Request-Id` on every response, and [bring your own](/conventions/request-ids) UUID or ULID.
- [Idempotency keys](/conventions/idempotency), required on every `/v2` POST.
- [Rate limits](/conventions/rate-limits) per key and per workspace, with `RateLimit-*` headers.
- [Scopes](/authentication#scopes) by area (`messages:write`, `contacts:read`, …), capped by the
  member's role when a key is created and when it is used.
- Per-key [IP allowlists](/authentication#ip-allowlist), and a request log in **Developers → Logs**.

**Changed**

- API access requires the Growth or Scale plan (`402 plan_required` otherwise).
- A key stops working when its member leaves the workspace (`401 key_owner_inactive`).
- `/v1/conversations` and `/v1/contacts` now respect the member's own and team visibility, as the
  console does.
- Webhook `*` subscriptions receive the public catalogue only, and payloads carry only each event's
  documented fields.

## Coming next [#coming-next]

- **SMS and voice** over the API, after a compliance review.
- **`@silquetech/gauge-sdk`**, the official Node SDK.


# Email (/channels/email)

<Status is="live" />

`kind: "email"` is a connected inbox (for example `support@yourcompany.com`). Mail sent to it
arrives in Gauge as conversations; replies go out from it and thread correctly in the customer's
mail client.

## What it can do [#what-it-can-do]

| | |
| --- | --- |
| Text | Yes |
| Attachments | Not yet over the API |
| Start a conversation | Yes: address the recipient by email address |
| Campaigns | Yes |
| Delivery | `immediate`, or `queued` when your workspace uses the newer email pipeline (see `capabilities.delivery`) |

## Threading [#threading]

Replies keep the email thread: Gauge sets the standard `In-Reply-To` and `References` headers, so
the customer sees one conversation in their mail client, and their answer comes back into the same
Gauge conversation.

## Who the mail is from [#who-the-mail-is-from]

How a reply is sent depends on how the inbox is connected:

| Connected as | From | Replies come back via | Signed by |
| --- | --- | --- | --- |
| **A mailbox** (IMAP/SMTP, Gmail or Microsoft 365) | The mailbox itself, with the connection's display name. A copy lands in its Sent folder. | The mailbox (Gauge reads it) | Your mail provider, as for any mail you send |
| **A forwarding address** (no mailbox) | Gauge's shared sending address; your inbox address is the `Reply-To` | The `Reply-To` | Gauge's sending domain, not yours |

Gauge does not yet sign mail with **your** domain's DKIM key. If recipients must see your own
domain as the sender, connect the inbox as a mailbox. Either way the threading headers are kept, so
the customer sees one conversation.


# Channels and capabilities (/channels)

A **connection** is one connected channel account: a WhatsApp number, an email inbox, a web chat
widget, an Instagram account. You connect channels in the console (**Channels**); the API reads
them and sends through them.

Channels are not interchangeable. WhatsApp only allows a free-text message inside a 24-hour window,
Instagram cannot carry an attachment from Gauge yet, a web chat visitor cannot be messaged until
they open the chat. Gauge does not hide those differences behind a send that quietly drops
something. It tells you up front, and refuses clearly when you ask for something a channel cannot do.

## Read a connection's capabilities [#read-a-connections-capabilities]

`GET /v2/connections` and `GET /v2/connections/{id}` return each connection's **effective**
capabilities: what it can do over the API right now, with your workspace's settings applied. This is
the source of truth. Check it instead of hard-coding a channel's abilities.

```json
"capabilities": {
  "sendText": true,
  "sendMedia": false,
  "sendTemplates": false,
  "sendInteractive": false,
  "quotedReplies": false,
  "startConversations": true,
  "broadcast": false,
  "delivery": "immediate"
}
```

| Field | Meaning |
| --- | --- |
| `sendText` | Can send a text message at all |
| `sendMedia` | Can attach a file (image, document, audio, video) |
| `sendTemplates` | Can send an approved WhatsApp template |
| `sendInteractive` | Can send buttons, lists or quick replies |
| `quotedReplies` | Can send a reply that quotes an earlier message |
| `startConversations` | Can send with `to` or `contactId` (a new or existing person) rather than only into an existing `conversationId` |
| `broadcast` | Can be used for campaigns (bulk sends) |
| `delivery` | `immediate`: sent during the request. `queued`: accepted, sent just after; follow `message.status_updated`. `none`: cannot send. |

`flags` lists the workspace settings the capabilities were computed from, and `warning` is set when
a channel carries a risk you must accept (WhatsApp Web).

Asking a connection for something its capabilities say it cannot do answers
`422 unsupported_channel_action`. Nothing is sent, and nothing is silently dropped.

## At a glance [#at-a-glance]

The typical capabilities of each channel. Some depend on features being enabled for your workspace,
so the connection's own `capabilities` always win.

| Channel | `kind` | Status | Text | Media | Templates | Start a conversation | Delivery |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [WhatsApp Cloud API](/channels/whatsapp-cloud) | `whatsapp_cloud` | <Status is="live" /> | Yes | When enabled | When enabled | With a template, when templates are enabled | Queued when media is enabled, else immediate |
| [WhatsApp Web](/channels/whatsapp-web) | `whatsapp_web` | <Status is="live" /> | Yes | Yes | No | Yes | Queued |
| [Email](/channels/email) | `email` | <Status is="live" /> | Yes | No | No | Yes | Immediate or queued |
| [Web chat](/channels/web-chat) | `webchat` | <Status is="live" /> | Yes | No | No | No | Immediate |
| [Instagram](/channels/instagram-messenger) | `instagram` | <Status is="live" /> | Yes | No | No | No | Immediate or queued |
| [Messenger](/channels/instagram-messenger) | `messenger` | <Status is="live" /> | Yes | No | No | No | Immediate or queued |
| [SMS](/channels/sms) | `sms` | <Status is="soon" /> | | | | | |
| [Voice](/channels/voice) | `voice` | <Status is="soon" /> | | | | | |

Reading connections and sending through them ([messaging endpoints](/messaging)) are both
<Status is="live" />. `GET /v2/connections/{id}` also returns `limits`: the reply window in hours
(`sessionWindowHours`), whether a template is required outside it, the WhatsApp Web warm-up
`sendCaps`, and the largest file it accepts (`maxMediaBytes`).

## The 24-hour window and templates [#the-24-hour-window-and-templates]

WhatsApp (Cloud API) lets a business send **free-form** messages only within **24 hours of the
customer's last message**. This is WhatsApp's rule, not Gauge's, and it protects customers from
unsolicited messages.

- **Inside the window** (the customer wrote in the last 24 hours): send any text, media or
  interactive message the connection supports.
- **Outside the window**: you can only send an approved **message template**, a pre-written
  message Meta has reviewed, with placeholders for your values. A free-text send answers
  `422 unsupported_channel_action` with reason **`outside_24h_window`**.
- **Each customer reply reopens the window** for another 24 hours.

The window is not a field on the conversation; compute it from the conversation's `lastInboundAt`
and the connection's `limits.sessionWindowHours`, or just send and handle the `422`.

Someone who has never written to you has no window at all, so on WhatsApp Cloud **a template is
how you start a conversation**. With templates enabled, the connection reports
`startConversations: true`: send a template with `to` (a phone number) or `contactId`, and Gauge
finds or creates the contact and the conversation, sends the template, and the customer's reply
lands in that same conversation. Free text to someone with no conversation answers `422` with
reason `outside_24h_window`. Templates are created and submitted for approval in the console
(**Templates**); the API lists them and sends them. See
[Start a conversation with a template](/messaging/templates#start-a-conversation-with-a-template).

Instagram and Messenger have Meta's own reply window where it is enforced for your workspace
(`limits.sessionWindowHours` says so); a send outside it answers `422` with reason
`outside_session_window`, and there is no template to reopen it. The other channels have no
window, but each has its own reach limits, listed on its page.


# Instagram and Messenger (/channels/instagram-messenger)

<Status is="live" />

`kind: "instagram"` is an Instagram professional account; `kind: "messenger"` is a Facebook Page.
Both are connected through Meta.

## What they can do [#what-they-can-do]

| | |
| --- | --- |
| Text | Yes, into conversations the customer started |
| Attachments | Not yet |
| Start a conversation | No: Meta only reveals who someone is after they message you |
| Campaigns | No |
| Delivery | `immediate`, or `queued` when your workspace uses the newer Meta send path (see `capabilities.delivery`) |

Meta applies its own reply window to Instagram and Messenger. Where Gauge enforces it for your
workspace, the connection's `limits.sessionWindowHours` says how long it is, and a send outside it
is refused **before** anything reaches Meta: `422 unsupported_channel_action` with reason
`outside_session_window`. Unlike WhatsApp there is no template to reopen it; wait for the customer
to write again.

A send Meta itself refuses (the person blocked the account, or Meta rejects the message) is not an
error on your request: the message is created, then reported `failed` with Meta's reason in a
[`message.status_updated`](/webhooks/events#messagestatus_updated) event and on
`GET /v2/messages/{id}`.


# SMS (/channels/sms)

<Status is="soon" />

Gauge workspaces can already send and receive SMS from the console on their Gauge numbers. **SMS
over the API is not available yet.**

Sending SMS from code costs money per message and reaches people's phones, so it opens only after
a compliance review covering consent records, do-not-contact lists, quiet hours in the recipient's
time zone, and spending caps.

When it ships:

- it will need the **`sms-send`** scope, granted only by name: no wildcard or "full access" key will
  ever include it ([Scopes](/authentication#scopes));
- an SMS you send will not have to open an inbox conversation, so notifications do not land in your
  team's queue;
- `sms.received` and `sms.status_updated` webhook events will report replies and delivery.

Follow the [changelog](/changelog).


# Voice (/channels/voice)

<Status is="soon" />

Gauge's phone system (numbers, calls, recordings, transcripts, voicemail) works today in the
console. **Voice over the API is not available yet.**

The plan, in order:

1. **Read**: list numbers, calls and voicemails; fetch a call's transcript; get a short-lived
   signed link to a recording. Webhook events `call.completed`, `call.recording_ready` and
   `voicemail.received`.
2. **Act**: place a call that rings one of your team and then the customer. This needs the
   **`voice-dial`** scope, granted only by name, and opens after the same compliance review as SMS
   (consent, do-not-call lists, recording notices, spending caps).

Follow the [changelog](/changelog).


# Web chat (/channels/web-chat)

<Status is="live" />

`kind: "webchat"` is the Gauge chat widget, on your website or inside your app. Messages arrive
live in the visitor's open chat.

## What it can do [#what-it-can-do]

| | |
| --- | --- |
| Text | Yes, into a conversation the visitor started |
| Quick-reply buttons and lists | When enabled for your workspace (`sendInteractive`) |
| Attachments | Not yet over the API |
| Start a conversation | No: a visitor is not addressable until they open the chat |
| Delivery | `immediate` |

## Putting the chat in your product [#putting-the-chat-in-your-product]

To put the widget on your site or in your app, signed in as your own user, use the
[Support API](/support): [Quick start: web app](/support/quickstart-web-app),
[mobile WebView](/support/quickstart-webview) or [API only](/support/quickstart-api).


# WhatsApp Cloud API (/channels/whatsapp-cloud)

<Status is="live" />

`kind: "whatsapp_cloud"` is a number connected through Meta's official **WhatsApp Business
Platform (Cloud API)**. It is the right choice for anything automated or at volume: it is what
WhatsApp built for businesses, and it is the channel Meta will not ban you for using as intended.

## What it can do [#what-it-can-do]

| | |
| --- | --- |
| Text | Yes, inside the 24-hour window |
| Templates | Yes, when templates are enabled for your workspace (`sendTemplates`) |
| Media | Yes, when WhatsApp Cloud media is enabled for your workspace (`sendMedia`) |
| Interactive (buttons, lists) | When enabled for your workspace (`sendInteractive`) |
| Quoted replies | When interactive messages and media are enabled for your workspace (`quotedReplies`) |
| Start a conversation | Yes, **with an approved template** (`startConversations`, when templates are enabled). Free text to someone with no conversation answers `422`, reason `outside_24h_window` |
| Campaigns | Yes |
| Delivery | `queued` (`202`) when media is enabled for your workspace, else `immediate` (`201`) |

Read the connection's `capabilities` for what is enabled for you; the table is the full feature
set.

## Start a conversation [#start-a-conversation]

WhatsApp only lets a business message someone first with an approved template. Send one with `to`
(an E.164 number) or `contactId`:

```bash
curl https://app.gauge.chat/backend/v2/messages \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
    "to": "+447700900123",
    "template": {
      "name": "appointment_reminder",
      "language": "en_GB",
      "variables": { "1": "Layla", "2": "Tuesday 22 October", "3": "10:30" }
    }
  }'
```

Gauge creates the contact and the conversation if they do not exist yet (or reuses the ones that
do), sends the template, and answers `202` with the `conversationId`. When the customer replies,
the 24-hour window opens and you can send free text into that conversation. The template must be
`approved`, in the `language` you name, with exactly its variables; see
[Templates](/messaging/templates#start-a-conversation-with-a-template).

## The 24-hour window [#the-24-hour-window]

Free-form messages are allowed only within 24 hours of the customer's last message. Outside it,
a free-text send answers `422 unsupported_channel_action` with reason `outside_24h_window`: send an
approved template instead. Details: [The 24-hour window and templates](/channels#the-24-hour-window-and-templates).

## Delivery status [#delivery-status]

A queued send answers `202` with `status: queued`: Gauge accepted the message and hands it to
WhatsApp right after the request. WhatsApp's progress arrives as
[`message.status_updated`](/webhooks/events#messagestatus_updated) events, each with `status` one of
`sent`, `delivered`, `read` or `failed`. A `failed` event carries `error: { "reason": "…" }`, the
reason in plain words (for example "This number is not on WhatsApp."); every other status has
`error: null`. The same history is at `GET /v2/messages/{id}/status-history`.

## Costs [#costs]

Meta charges for some WhatsApp messages, by category and country. Gauge passes those fees through
at cost, with no markup, exactly as for messages sent from the console.

## Recipient numbers [#recipient-numbers]

Send to numbers in international (E.164) format: `+447700900123`. Gauge normalises them for
WhatsApp.


# WhatsApp Web (/channels/whatsapp-web)

<Status is="live" />

<Callout type="error" title="You are responsible for this account, and WhatsApp can ban it">
  A WhatsApp Web connection runs on an ordinary WhatsApp account (a phone number using the WhatsApp
  or WhatsApp Business app), linked to Gauge the way WhatsApp Web is linked to a browser. It is
  **not** Meta's official Business Platform.

  **WhatsApp may restrict or permanently ban an account that sends automated or high-volume
  messages**, messages people did not ask for, or messages many recipients report or block. A ban
  takes the number off WhatsApp, usually with its chat history, and Gauge cannot reverse it.

  By sending through a WhatsApp Web connection over the API, **you accept that risk, and you are
  responsible for your send volume, your pacing and your recipients' consent.** For automation,
  notifications or anything at volume, use the [WhatsApp Cloud API](/channels/whatsapp-cloud).
</Callout>

Every WhatsApp Web connection says so in the API itself. Its `warning` field is never null:

```json
"warning": {
  "code": "whatsapp_web_ban_risk",
  "message": "WhatsApp Web connections run on a personal WhatsApp account, not the official Business API. WhatsApp may restrict or ban an account that sends automated or high-volume messages. You are responsible for your send volume and limits on this connection."
}
```

The same warning appears in the console when a key is created and on the connection itself, and
every `POST /v2/messages` on a WhatsApp Web connection answers with
`"warnings": ["whatsapp_web_unofficial"]`.

## What it can do [#what-it-can-do]

| | |
| --- | --- |
| Text | Yes, with no 24-hour window |
| Media | Yes |
| Quoted replies | Yes |
| Templates | No (templates are a Cloud API feature) |
| Start a conversation | Yes |
| Campaigns | **No.** Bulk sending is not available on WhatsApp Web, by design |
| Delivery | `queued`: every send answers `202` |

## Using it responsibly [#using-it-responsibly]

These lower the risk. None of them removes it.

- **Answer, do not broadcast.** Replying to people who wrote to you is the safest use. Cold
  messages to numbers that never contacted you are the riskiest.
- **Pace your sends.** Spread messages out; do not fire hundreds in a burst. Gauge applies its own
  per-connection [send caps](#send-caps) on WhatsApp Web, and you should stay well under them.
- **Only message people who expect it**, and stop when someone asks you to.
- **Keep the phone healthy.** The linked phone must stay online and signed in; if it logs out, the
  connection stops until it is re-linked.
- **Move volume to the Cloud API.** If a WhatsApp Web number is becoming important to your
  business, migrate it to the official platform.

## Send caps [#send-caps]

A newly linked number warms up: Gauge caps how much it sends while the account is young, and lifts
the cap as it ages. The caps count **every** outbound message on the connection (console and API
alike, queued ones included), per minute and per UTC day:

| Warm-up tier | Account age | Per minute | Per day |
| --- | --- | --- | --- |
| 0 | from linking | 1 | 30 |
| 1 | 3 days | 3 | 120 |
| 2 | 7 days | 8 | 400 |
| 3 | 14 days | 15 | 1,000 |

The connection's current tier and caps are in `limits.sendCaps` on
[`GET /v2/connections/{id}`](/channels): `{ "perMinute": 1, "perDay": 30, "warmupTier": 0 }`.

A send over a cap is **refused, not delayed**: `429 rate_limited` with reason
`whatsapp_web_minute_cap` or `whatsapp_web_daily_cap`, `details.limit`, and a `Retry-After` header
(seconds until the minute, or the UTC day, resets). Nothing is queued. Wait and retry with the same
`Idempotency-Key`.


# Errors (/conventions/errors)

Every error from `/v1` and `/v2` has the same shape:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Invalid query parameters.",
    "details": [{ "path": "query.limit", "message": "Number must be less than or equal to 100" }],
    "requestId": "4f6c1d2e-8a3b-4c5d-9e0f-1a2b3c4d5e6f"
  }
}
```

| Field | |
| --- | --- |
| `code` | One of the codes below. **Branch on this**, never on `message`. |
| `message` | A sentence for a human. It may be reworded at any time. |
| `reason` | Optional. A finer sub-code for some refusals, such as `ip_not_allowed`. |
| `details` | Optional. For `validation_failed`, a list of `{ path, message }`, one per bad field. |
| `requestId` | The same id as the `X-Request-Id` header. Quote it to support. |

A `5xx` never carries a stack trace or internal detail: its message is always "Something went wrong
on our side. Quote the request id if you contact support."

## Codes [#codes]

The list is closed: a new code is an additive change, and renaming one is a breaking change that
needs a new [version](/conventions/versioning).

| HTTP | `code` | When | What to do |
| --- | --- | --- | --- |
| 400 | `validation_failed` | A parameter, header or body field is invalid. `details` names each one. Also: a missing `Idempotency-Key` on a POST, an invalid cursor, an unknown `Gauge-Version`. | Fix the request. Do not retry unchanged. |
| 401 | `unauthorized` | No key, or an unknown, revoked or expired one. | Check the key. |
| 401 | `key_owner_inactive` | The key's member is no longer active in the workspace. | Create a new key under an active member. |
| 402 | `plan_required` | The workspace is not on Growth or Scale. | Upgrade in **Settings → Billing**. |
| 403 | `forbidden` | Refused for a reason in `reason`: `ip_not_allowed`, `sandbox_key_not_supported`, `key_pinned_to_projects`. | See [Authentication](/authentication#authentication-errors). |
| 403 | `insufficient_scope` | The key, or its member's role, lacks the route's scope. `details.required` names it. | Add the scope, or use another key. |
| 403 | `workspace_suspended` | The workspace is suspended. | Contact Gauge support. |
| 404 | `not_found` | The resource does not exist, or this key cannot see it. | Check the id. Gauge does not tell you which. |
| 409 | `conflict` | The request clashes with the current state, or an identical request is still running (`reason: idempotency_in_flight`). | Re-read the resource, or retry shortly. |
| 409 | `idempotency_mismatch` | An `Idempotency-Key` was reused with a different body. | Use a new key for a new request. |
| 413 | `payload_too_large` | The body or file is over the limit. | Send less. |
| 422 | `unsupported_channel_action` | The channel cannot do this, such as media on a channel without media, or free text outside WhatsApp's 24-hour window. | Check the connection's `capabilities`. See [Channels](/channels). |
| 429 | `rate_limited` | Over the [rate limit](/conventions/rate-limits). | Wait `Retry-After` seconds, then retry. |
| 500 | `internal` | Our fault. | Retry with backoff. If it persists, contact support with the request id. |

`404` is also the answer for another workspace's ids and for anything outside the key's visibility.
Gauge never confirms that a resource exists to a caller who may not see it.

## Retrying safely [#retrying-safely]

| Retry? | Codes |
| --- | --- |
| Yes, after a wait | `429 rate_limited` (honour `Retry-After`), `500 internal`, network errors and timeouts |
| Yes, shortly | `409 conflict` with `reason: idempotency_in_flight` |
| No, fix first | Every other `4xx` |

Send POSTs with an [`Idempotency-Key`](/conventions/idempotency) and every retry is safe: a request
that already succeeded replays its first response instead of running twice.

<Tabs groupId="lang" items={['Node', 'Python']} persist>
<Tab value="Node">

```js
async function gauge(path, init = {}, attempt = 0) {
  const res = await fetch(`https://app.gauge.chat/backend${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.GAUGE_API_KEY}`, ...init.headers },
  });
  if (res.ok) return res.status === 204 ? null : res.json();

  const { error } = await res.json();
  const retryable = res.status === 429 || res.status >= 500 || error.reason === 'idempotency_in_flight';
  if (retryable && attempt < 4) {
    const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250));
    return gauge(path, init, attempt + 1);
  }
  throw Object.assign(new Error(error.message), { code: error.code, reason: error.reason, requestId: error.requestId });
}
```

</Tab>
<Tab value="Python">

```python
import os, random, time
import requests

def gauge(method, path, attempt=0, **kwargs):
    headers = {"Authorization": f"Bearer {os.environ['GAUGE_API_KEY']}", **kwargs.pop("headers", {})}
    res = requests.request(method, f"https://app.gauge.chat/backend{path}", headers=headers, timeout=15, **kwargs)
    if res.ok:
        return None if res.status_code == 204 else res.json()

    error = res.json()["error"]
    retryable = res.status_code == 429 or res.status_code >= 500 or error.get("reason") == "idempotency_in_flight"
    if retryable and attempt < 4:
        wait = float(res.headers.get("Retry-After") or 2 ** attempt)
        time.sleep(wait + random.random() / 4)
        return gauge(method, path, attempt + 1, headers=headers, **kwargs)
    raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})")
```

</Tab>
</Tabs>


# Idempotency (/conventions/idempotency)

Networks fail in the worst place: after Gauge sent the message, before you got the answer. An
**idempotency key** makes the retry safe. Send the same key again and Gauge returns the first
answer instead of doing the work twice.

**Every `POST` on `/v2` requires an `Idempotency-Key` header.** A POST without one answers
`400 validation_failed`, naming the header.

```bash
curl https://app.gauge.chat/backend/v2/messages \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d1f8c2a-7e3b-4a9d-b6c0-2f8e1a4d7c93" \
  -d '{"connectionId":"…","to":"+447700900123","text":"Hello"}'
```

## Choosing a key [#choosing-a-key]

- 1 to 255 visible ASCII characters (no spaces).
- **One key per distinct operation.** A UUID generated when you decide to do the thing works, as
  does an id from your own system that names the operation: `order-1042-confirmation`.
- Generate it **before** the first attempt and reuse it for every retry of that operation. A new
  key on each retry defeats the point.

## What happens [#what-happens]

Keys are scoped to the API key, the method and the path, and are kept for **24 hours**.

| You send | Gauge answers |
| --- | --- |
| A key it has not seen | Runs the request and stores the answer |
| The same key and the same body, after the first finished | The **stored** status and body, with `Idempotent-Replayed: true` |
| The same key and the same body, while the first is still running | `409 conflict`, `reason: idempotency_in_flight`. Retry shortly. |
| The same key with a **different** body | `409 idempotency_mismatch`. A new request needs a new key. |
| The same key after the first attempt **failed** | Runs again: a failed attempt releases its key, so an honest retry is not stuck behind an error |

A replay is visible in **Developers → Logs**, where it is marked as a replay.

## Sending messages [#sending-messages]

For `POST /v2/messages`, the idempotency key is also how a message is identified as "the same send".
Gauge derives the message's own de-duplication reference from your API key and the
`Idempotency-Key`, and stores it on the message. So:

- **Within 24 hours**, a retry replays the first answer exactly: the same status (`201` or `202`)
  and body, with `Idempotent-Replayed: true`.
- **After 24 hours**, the replay record is gone, but the message still carries the reference: a
  retry with the same key answers that **same message** (with its current status, so `201` once it
  has been sent) and never sends a second one.

The reference is per API key: the same `Idempotency-Key` on two different keys is two sends.


# Conventions (/conventions)

Every `/v2` endpoint shares the same contract. Build your client around these once and every new
endpoint behaves the way you expect.

| Convention | In one line |
| --- | --- |
| [Versioning](/conventions/versioning) | `/v2` in the path; pin a dated `Gauge-Version` for additive changes. |
| [Errors](/conventions/errors) | One envelope; branch on `error.code`, never on the message. |
| [Request ids](/conventions/request-ids) | Every response has `X-Request-Id`; quote it to support. |
| [Idempotency](/conventions/idempotency) | Every POST needs an `Idempotency-Key`; retries replay the first answer. |
| [Pagination](/conventions/pagination) | Opaque cursors, `{ data, nextCursor, prevCursor }`, up to 100 per page. |
| [Rate limits](/conventions/rate-limits) | Per key and per workspace, by plan; `RateLimit-*` headers, `429` with `Retry-After`. |
| [Plans](/conventions/plans) | The API is included on Growth and Scale. |

Requests and responses are JSON (`Content-Type: application/json`), in UTF-8. Timestamps are
ISO 8601 in UTC (`2026-10-21T09:12:44.000Z`). Ids are opaque strings, today UUIDs; do not parse them.


# Pagination (/conventions/pagination)

Every list endpoint answers with the same envelope:

```json
{
  "data": [{ "id": "…" }, { "id": "…" }],
  "nextCursor": "c1_WyIyMDI2LTEwLTIxVDA5OjEyOjQ0LjAwMFoiLCI5YjJm…",
  "prevCursor": null
}
```

Lists are **newest first**, ordered by creation time and then id, so a page never skips or repeats a
row even when new ones arrive while you are paging.

| Query parameter | |
| --- | --- |
| `limit` | Page size, 1 to 100. Default 25. |
| `after` | A `nextCursor` from the previous page: continue to older items. |
| `before` | A `prevCursor`: go back to newer items. Send `after` or `before`, not both. |

`nextCursor` is `null` on the last page; `prevCursor` is `null` on the first.

**Cursors are opaque.** Pass them back exactly as you got them. Do not build, parse or store them
long-term; their format can change. A string that is not a cursor Gauge issued answers
`400 validation_failed`.

## Fetch every page [#fetch-every-page]

<Tabs groupId="lang" items={['Node', 'Python']} persist>
<Tab value="Node">

```js
async function* listAll(path) {
  let after = null;
  do {
    const url = new URL(`https://app.gauge.chat/backend${path}`);
    url.searchParams.set('limit', '100');
    if (after) url.searchParams.set('after', after);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.GAUGE_API_KEY}` } });
    const page = await res.json();
    if (!res.ok) throw new Error(`${page.error.code} (${page.error.requestId})`);
    yield* page.data;
    after = page.nextCursor;
  } while (after);
}

for await (const connection of listAll('/v2/connections')) console.log(connection.displayName);
```

</Tab>
<Tab value="Python">

```python
def list_all(path):
    after = None
    while True:
        params = {"limit": 100, **({"after": after} if after else {})}
        res = requests.get(
            f"https://app.gauge.chat/backend{path}",
            headers={"Authorization": f"Bearer {os.environ['GAUGE_API_KEY']}"},
            params=params,
            timeout=15,
        )
        page = res.json()
        if not res.ok:
            raise RuntimeError(f"{page['error']['code']} ({page['error']['requestId']})")
        yield from page["data"]
        after = page["nextCursor"]
        if not after:
            return

for connection in list_all("/v2/connections"):
    print(connection["displayName"])
```

</Tab>
</Tabs>

Paging through a large list spends one request per page against your
[rate limit](/conventions/rate-limits). Use `limit=100` for bulk reads.


# Plans (/conventions/plans)

| | Free | Growth | Scale |
| --- | --- | --- | --- |
| API access | Not included | Included | Included |
| Requests per minute, workspace | | 600 | 3,000 |
| Requests per minute, per key | | 300 | 1,500 |

Rate limits are [provisional](/conventions/rate-limits).

On Free, every API request answers:

```json
{
  "error": {
    "code": "plan_required",
    "message": "The Gauge API is available on the Growth and Scale plans. Upgrade in Settings → Billing to use this key.",
    "requestId": "…"
  }
}
```

with status `402`. Upgrade in **Settings → Billing**, and the same keys start working at once.

- **Trials count.** A workspace trialling Scale has API access for the trial.
- **Payment problems do not cut you off at once.** A subscription that is past due keeps API access
  through the same grace period as the rest of the product.
- **There is no separate API bill or quota.** API traffic counts against the plan's normal limits
  and usage, exactly as work done in the console does. Messages you send over the API cost what
  they cost in the console (for example, Meta's own WhatsApp fees, passed through at cost).


# Rate limits (/conventions/rate-limits)

<Callout type="warn" title="Provisional numbers">
  The limits below are the launch values and may change before the API leaves preview. Read the live
  values from the `RateLimit-*` headers or `GET /v2/me` rather than hard-coding them.
</Callout>

## The limits [#the-limits]

Each request spends one token from **two buckets**: one for the key and one for the whole workspace.
A request goes through only when both have a token.

| Plan | Workspace | Each key |
| --- | --- | --- |
| Growth | 600 requests per minute | 300 per minute |
| Scale | 3,000 requests per minute | 1,500 per minute |
| Free | The API is not included | |

Each key gets **half** the workspace budget, so one runaway integration cannot starve the others.
Buckets refill continuously, not at the top of the minute: a key on Growth gets a token back every
200 ms.

API traffic is not metered or billed separately. It counts against your plan's normal limits and
usage, like work done in the console.

## Headers [#headers]

Every `/v2` response that reached the limiter carries:

```http
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 3
```

| Header | |
| --- | --- |
| `RateLimit-Limit` | Requests per minute in the tighter of your two buckets |
| `RateLimit-Remaining` | Tokens left in that bucket |
| `RateLimit-Reset` | Seconds until that bucket is full again |

`GET /v2/me` returns both buckets in `rateLimit`, including `workspaceLimit` and
`workspaceRemaining`.

## When you hit it [#when-you-hit-it]

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 60
```

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit reached. Retry after 2 s.",
    "details": { "limit": 300, "workspaceLimit": 600 },
    "requestId": "…"
  }
}
```

Wait `Retry-After` seconds, then retry. A refused request spends no token, but requests to a route
the key cannot call still count: the limit is checked before the scope.

## Staying under [#staying-under]

- Page with `limit=100` instead of many small pages.
- Use [webhooks](/webhooks) instead of polling for changes.
- Spread batch jobs over time, and give each integration its own key.
- Back off on `429` with jitter, so many workers do not retry in the same instant.

Gauge also applies a per-IP safety limit in front of the API, to protect the platform from floods.
Normal integrations never meet it.


# Request ids (/conventions/request-ids)

Every response from the API, success or error, carries a request id:

```http
HTTP/1.1 200 OK
X-Request-Id: 4f6c1d2e-8a3b-4c5d-9e0f-1a2b3c4d5e6f
```

The same id is in the body of every error, as `error.requestId`. Gauge's own logs are keyed on it,
so with the id support can find your exact request in seconds; without it, they are searching by
time.

**Log it** next to your own record of the call, at least for errors.

## Bring your own id [#bring-your-own-id]

If you already trace requests with your own id, send it as `X-Request-Id` and Gauge uses it instead
of minting one, end to end. It must be a **UUID** or a **ULID**; anything else is ignored and Gauge
mints a fresh UUID.

```bash
curl https://app.gauge.chat/backend/v2/me \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "X-Request-Id: 01JAXQ7M3R9K5V2T8N4P6W1Y0Z"
```

## Find a request in the console [#find-a-request-in-the-console]

**Developers → Logs** lists every `/v2` request for the last 14 days: method, route, status,
latency, the key that made it, and whether it was an idempotent replay. Paste a request id into the
search to jump to it.


# Versioning (/conventions/versioning)

## Two layers [#two-layers]

**The path** carries the major version: `/v2/...`. A new major version is a new path, and the old
one keeps working. `/v1` is frozen: it gets security fixes only, and new work lands on `/v2`.

**The `Gauge-Version` header** carries a dated version for changes inside `/v2`:

```http
Gauge-Version: 2026-10-21
```

- **Leave it out** and you get the current version. Fine while you build.
- **Send it** in production to pin the behaviour your code was written against.
- An **unknown** value answers `400 validation_failed` rather than silently using another version,
  so a typo cannot change behaviour without you noticing.
- Every `/v2` response echoes the version it followed in its own `Gauge-Version` header.

Published versions: **`2026-10-21`** (current).

## What counts as a breaking change [#what-counts-as-a-breaking-change]

These are **additive** and can ship at any time, without a new version. Write your client to
tolerate them:

- a new endpoint, or a new optional request field or query parameter;
- a new field in a response object;
- a new value in an enum we document as extensible (event names, `error.reason`, connection `kind`);
- a new webhook event type.

These are **breaking** and only ever ship behind a new `Gauge-Version` date or a new path:

- removing or renaming a field, an endpoint or an `error.code`;
- changing a field's type or meaning;
- making an optional request field required.

## Deprecation [#deprecation]

Before an endpoint is retired, its responses carry the standard headers:

```http
Deprecation: @1798761600
Sunset: Sun, 01 Aug 2027 00:00:00 GMT
Link: <https://docs.gauge.chat/changelog>; rel="deprecation"
```

Nothing is deprecated today. Every deprecation is also announced in the [changelog](/changelog).


# Glossary (/glossary)

| Term | Meaning |
| --- | --- |
| **Workspace** | Your Gauge account: the tenant. Everything a key can reach belongs to one workspace. |
| **Member** | A person with a seat in the workspace. A key always acts as a member. |
| **Role** | What a member may do and see. A key can never do more than its member's role. |
| **API key** | A secret that authenticates requests as one member, within its scopes. `pulse_k_live_…` or `pulse_k_test_…`. |
| **Scope** | A permission on a key, by area: `messages:write`, `contacts:read`. |
| **Live / test** | A key's environment. Test keys reach sandbox data only. |
| **Connection** | One connected channel account: a WhatsApp number, an inbox, a Facebook Page. Not the same as a *channel* (the type) or an *identity* (the person's address). |
| **Channel** | The kind of connection: WhatsApp Cloud API, WhatsApp Web, email, web chat, Instagram, Messenger, SMS, voice. In the API, a connection's `kind`. |
| **Capabilities** | What a connection can do over the API right now: text, media, templates, starting conversations. |
| **Contact** | A person, merged across channels. |
| **Identity** | One way to reach a contact: a channel plus the id on it, such as a WhatsApp number. |
| **Conversation** | A contact on one connection: a thread with a status, an assignee and tags. |
| **Message** | One item in a conversation: inbound or outbound text, media, template or interactive. |
| **Template** | A WhatsApp message pre-approved by Meta, the only kind allowed outside the 24-hour window. |
| **24-hour window** | WhatsApp's rule: free-form messages only within 24 hours of the customer's last message. |
| **App** | A product of yours connected to Gauge Support (in older docs and the API, a *project*). |
| **Integration** | One way into an App: in-app chat, a WhatsApp number, an email address. It has a key such as `customer` or `salon`. Not an API key. |
| **Webhook endpoint** | Your URL that receives events, with its subscriptions and signing secret. |
| **Event** | Something that happened, delivered to webhooks: `support.ticket.created`. Has a stable `id`. |
| **Delivery** | One attempt to POST an event to an endpoint. An event can have several. |
| **Idempotency key** | A header that makes a retried POST safe: the same key never does the work twice. |
| **Request id** | The id of one API request, in `X-Request-Id`. Quote it to support. |
| **Cursor** | An opaque marker for the next or previous page of a list. |


# The Gauge API (/)

Gauge is a revenue inbox: a business's WhatsApp, Instagram, Messenger, email, web chat and phone
calls land in one priority-sorted queue. The Gauge API gives your code the same access a member of
the team has in the console. It can see the connected channels, send and read messages, keep
contacts in step with your own system, and receive events the moment they happen.

<Cards>
  <Card title="Quickstart" href="/quickstart">
    Create a key, make your first call, send a WhatsApp message and receive replies by webhook.
  </Card>
  <Card title="Authentication and keys" href="/authentication">
    Bearer keys, scopes, live and test environments, IP allowlists, expiry and rotation.
  </Card>
  <Card title="API reference" href="/reference">
    Every /v2 endpoint and webhook event, generated from the API's own OpenAPI document.
  </Card>
  <Card title="Webhooks" href="/webhooks">
    The event catalogue, signature verification, retries, replay and inbound message forwarding.
  </Card>
</Cards>

## What you can build [#what-you-can-build]

- **Reply from your own product.** Read a conversation and answer it from your CRM, booking system
  or back office, on the channel the customer used.
- **Forward inbound messages.** Receive every new customer message at your endpoint, signed, and
  route it wherever it needs to go.
- **Keep contacts in sync.** Create and update contacts from your system of record, so the team sees
  the same customer you do.
- **Embed support in your app.** The [Support API](/support) puts Gauge's chat, tickets and
  callbacks inside your own web or mobile app, signed in as your user.

## What is available today [#what-is-available-today]

The API is versioned by path. `/v2` is the current version and is being built out area by area.
This table is the honest state of each area; every page in these docs carries the same marks.

| Area | Status | Where |
| --- | --- | --- |
| Who a key is (`GET /v2/me`) | <Status is="live" /> | [Reference](/reference) |
| Connections and their capabilities | <Status is="live" /> | [Channels](/channels) |
| Webhooks: signed delivery, retries, replay, test events | <Status is="live" /> | [Webhooks](/webhooks) |
| Support API (`/v1/support`): customers, chat, tickets, callbacks | <Status is="live" /> | [Support API](/support) |
| Contacts, conversations, messages, media, templates | <Status is="live" /> | [Messaging](/messaging) |
| Message events (`message.received` and friends) | <Status is="live" /> | [Events](/webhooks/events) |
| SMS and voice | <Status is="soon" /> | [Channels](/channels) |

**Coming soon** means the area is planned and not yet available. Watch the [changelog](/changelog).

## The basics [#the-basics]

| | |
| --- | --- |
| Base URL | `https://app.gauge.chat/backend` |
| Version | `/v2` in the path, plus an optional dated `Gauge-Version` header ([Versioning](/conventions/versioning)) |
| Authentication | `Authorization: Bearer <key>` ([Authentication](/authentication)) |
| Format | JSON in, JSON out, UTF-8 |
| Errors | One envelope, `{ "error": { "code", "message", "requestId" } }` ([Errors](/conventions/errors)) |
| Plans | Growth and Scale. The API is not included on Free ([Plans](/conventions/plans)) |

There is no Gauge SDK yet. Every example in these docs is plain HTTP in curl, Node (`fetch`) and
Python (`requests`), so it works with whatever HTTP client you already use. An official Node SDK,
`@silquetech/gauge-sdk`, will follow the v2 endpoints.

## Using an AI assistant? [#using-an-ai-assistant]

These docs are published for AI tools as well: [`/llms.txt`](/llms.txt) indexes every page,
[`/llms-full.txt`](/llms-full.txt) has all of it in one file, and every page has a **Copy page**
button. See [Use Gauge with AI tools](/ai-tools).


# Contacts (/messaging/contacts)

<Status is="live" />

A contact is a person, merged across channels. Contacts are workspace-wide: a key with contact
access sees every contact, the same list the console shows. Every contact endpoint needs a live key
that is not pinned to an App.

| Endpoint | Scope | |
| --- | --- | --- |
| `GET /v2/contacts` | `contacts:read` | List and search contacts |
| `POST /v2/contacts` | `contacts:write` | Create a contact (`201`) |
| `GET /v2/contacts/{id}` | `contacts:read` | One contact |
| `PATCH /v2/contacts/{id}` | `contacts:write` | Update fields or custom fields |
| `PUT /v2/contacts/by-identity/{channel}/{externalId}` | `contacts:write` | Create (`201`) or update (`200`) by channel identity |
| `GET`, `POST /v2/contacts/{id}/identities` | `contacts:read`, `contacts:write` | List or add a handle (`{ "channel", "externalId" }`) |
| `DELETE /v2/contacts/{id}/identities/{identityId}` | `contacts:write` | Remove a handle |
| `POST /v2/contacts/{id}/tags`, `DELETE /v2/contacts/{id}/tags/{tag}` | `contacts:write` | Add tags (`{ "tags": [...] }`), remove one |
| `POST /v2/contacts/{id}/merge` | `contacts:write` | Merge `sourceId` into this contact |
| `DELETE /v2/contacts/{id}` | `contacts:write` + erasure right | Erase the contact (irreversible) |

## The contact object [#the-contact-object]

```json
{
  "id": "2b9d4f61-7a3c-4e8b-9d0f-1a2b3c4d5e60",
  "displayName": "Layla Haddad",
  "email": "layla@example.com",
  "phone": "+447700900123",
  "title": null,
  "companyId": null,
  "companyName": null,
  "lifecycleStage": "customer",
  "isVip": false,
  "tags": ["vip"],
  "customFields": { "plan": "gold" },
  "identities": [
    { "id": "8c1d…", "channel": "whatsapp_cloud", "externalId": "447700900123", "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f" },
    { "id": "9d2e…", "channel": "email", "externalId": "layla@example.com", "connectionId": null }
  ],
  "createdAt": "2026-10-20T16:02:11.903Z",
  "updatedAt": "2026-10-21T09:28:40.112Z"
}
```

## Search [#search]

`GET /v2/contacts` takes, all optional: `q` (name, email, phone or company contains), `email`,
`phone` (any format, matched on digits), `tag`, `company`, `updatedSince`, `createdSince`,
`channel` + `externalId` (the contact holding that handle), and `sort` (`-createdAt`, the default,
`createdAt`, `updatedAt` or `-updatedAt`).

## Create and update [#create-and-update]

`POST /v2/contacts` takes `displayName`, `email`, `phone`, `country` (for a national phone number:
`US`, `CA` or `GB`), `title`, `companyId` or `companyName` (found or created), `customFields` and
`tags`. It needs at least a `displayName`, an `email` or a `phone`. An email or phone another
contact already holds answers `409 conflict`.

`PATCH /v2/contacts/{id}` takes the same fields except `email` and `tags` (add handles and tags
with their own endpoints).

## Sync from your system: upsert by identity [#sync-from-your-system-upsert-by-identity]

The simplest way to keep Gauge in step with your CRM or database is to **upsert** each customer by
something both systems know, such as their phone number on a WhatsApp connection or their email
address:

```bash
curl -X PUT "https://app.gauge.chat/backend/v2/contacts/by-identity/whatsapp_cloud/+447700900123" \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "Layla Haddad", "customFields": { "plan": "gold" } }'
```

The body takes `displayName`, `title`, `companyId` or `companyName`, `customFields` and `country`.
The handle in the path is normalized the way the inbox files it (a phone to E.164). If a contact
holds that handle, it is updated and the answer is `200`; otherwise a contact is created with that
handle and the answer is `201`. Run it as often as you like: the result is the same.

## Erase a contact [#erase-a-contact]

`DELETE /v2/contacts/{id}` is the GDPR erasure: the contact's handles are deleted and their
messages redacted. It **cannot be undone**. It needs `contacts:write` **and** the key's member must
hold the erasure right (Owner or Admin); otherwise it answers `403`. Pass an optional `?reason=` for
the audit log. The answer counts what was erased:

```json
{ "id": "2b9d…", "erased": true, "erasedAt": "2026-10-21T10:00:00.000Z", "identitiesDeleted": 2, "messagesRedacted": 14 }
```

## Events [#events]

Creating, renaming, merging and changing a contact's handles or fields raise
[`contact.created` and `contact.updated`](/webhooks/events#contacts) webhooks, as in the console.


# Conversations (/messaging/conversations)

<Status is="live" />

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](/conventions/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 [#the-conversation-object]

```json
{
  "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 [#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 [#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 |

```bash
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 [#leave-a-note-for-the-team]

`POST /v2/conversations/{id}/notes` · requires `Idempotency-Key`

```bash
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 [#events]

A status change (open, snooze, resolve) and an assignment, team or topic change made through the
API raise the same [`conversation.updated`](/webhooks/events#conversationupdated) webhook as one
made in the console. Tag and priority changes do not raise a webhook.


# Messaging (/messaging)

<Status is="live" />

The [API reference](/reference) is generated from the running API's own specification and lists
every field of every operation below.

## The model [#the-model]

| Resource | What it is |
| --- | --- |
| **Connection** | One connected channel account: a WhatsApp number, an inbox. [Live](/channels). |
| **Contact** | A person, merged across channels. One contact can have a WhatsApp number, an email address and an Instagram handle. |
| **Identity** | One way to reach a contact: a channel plus the id on it, such as `whatsapp` + `+447700900123`. |
| **Conversation** | A contact on one connection: a thread with a status, an assignee and tags. |
| **Message** | One item in a conversation: inbound or outbound, text, media, template or interactive. |
| **Media** | A file you upload with `POST /v2/media` to send. A file already on a message (one a customer sent, or one you sent) is downloaded through that message. |
| **Template** | An approved WhatsApp message template. |

## Endpoints [#endpoints]

| Endpoint | Scope | |
| --- | --- | --- |
| `POST /v2/messages` | `messages:write` | Send a message |
| `GET /v2/messages/{id}` | `messages:read` | One message |
| `GET /v2/messages/{id}/status-history` | `messages:read` | Its delivery history |
| `GET /v2/messages/{id}/attachments/{index}` | `messages:read` | A short-lived download link for a file on a message |
| `GET /v2/conversations` | `conversations:read` | List conversations |
| `GET /v2/conversations/{id}` | `conversations:read` | One conversation |
| `PATCH /v2/conversations/{id}` | `conversations:write` | Status, assignee, team, topic, tags, priority |
| `POST /v2/conversations/{id}/read` | `conversations:write` | Mark read |
| `GET /v2/conversations/{id}/messages` | `messages:read` | A conversation's messages |
| `POST /v2/conversations/{id}/notes` | `conversations:write` | Add an internal note |
| `GET /v2/contacts`, `POST /v2/contacts` | `contacts:read`, `contacts:write` | List, create |
| `GET`, `PATCH /v2/contacts/{id}` | `contacts:read`, `contacts:write` | One contact |
| `DELETE /v2/contacts/{id}` | `contacts:write` + the member's erasure right | Erase a contact (GDPR, irreversible). See [Contacts](/messaging/contacts#erase-a-contact) |
| `PUT /v2/contacts/by-identity/{channel}/{externalId}` | `contacts:write` | Create or update by channel identity |
| `GET`, `POST /v2/contacts/{id}/identities`, `DELETE …/identities/{identityId}` | `contacts:read`, `contacts:write` | A contact's handles |
| `POST /v2/contacts/{id}/tags`, `DELETE …/tags/{tag}` | `contacts:write` | Tag, untag |
| `POST /v2/contacts/{id}/merge` | `contacts:write` | Merge another contact into this one |
| `POST /v2/media` | `media:write` | Get an upload URL |
| `GET /v2/media/{id}` | `media:read` | Get a short-lived download URL |
| `GET /v2/templates`, `GET /v2/templates/{id}` | `templates:read` | WhatsApp templates |

## Which keys can call them [#which-keys-can-call-them]

Every messaging endpoint needs a **live** key that is **not pinned to an App**. A test key gets
`403 forbidden` with reason `sandbox_key_not_supported`, and a key pinned to an App gets
`403 forbidden` with reason `key_pinned_to_projects`: these endpoints read and write real customer
data that belongs to no single App. The one exception is `GET /v2/templates`, which a test key may
read. See [Test keys](/authentication#test-keys).

## Visibility [#visibility]

A key sees what its member sees in the console. For conversations and messages, that is the
member's own, their team's, or all, depending on their role. Contacts are visible workspace-wide to
anyone with contact access, as in the console. See [Keys belong to a person](/authentication#keys-belong-to-a-person).

## Sent as you, marked as the API [#sent-as-you-marked-as-the-api]

A message sent with a key is sent as the key's member and appears in the console like any other
reply, marked as sent through the API. API sends do not count as a person taking over from the AI
assistant.


# Media (/messaging/media)

<Status is="live" />

Files never pass through your API request body. You ask Gauge for an upload URL, upload the file
straight to storage, then send a message that refers to it.

<Steps>
<Step>

### Ask for an upload URL [#ask-for-an-upload-url]

`POST /v2/media` · scope `media:write` · requires `Idempotency-Key` · live, unpinned key

```json
{ "contentType": "application/pdf", "sizeBytes": 183402, "filename": "invoice-1042.pdf", "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f" }
```

| Field | |
| --- | --- |
| `contentType` | One of `image/jpeg`, `image/png`, `image/webp`, `image/gif`, `video/mp4`, `video/3gpp`, `audio/ogg`, `audio/opus`, `audio/webm`, `audio/mpeg`, `audio/mp4`, `audio/aac`, `audio/amr`, `application/pdf`. Anything else answers `400`. |
| `sizeBytes` | The exact size. It is signed into the upload URL: storage refuses a body of any other length. |
| `filename` | Optional, up to 200 characters. |
| `connectionId` | Optional but recommended: the file is checked against that connection's limits now rather than at send time. |

`201` answers the media with a presigned upload:

```json
{
  "id": "5d1c7e2a-9b3f-4a6d-8e0c-2f4a6b8d0e1f",
  "contentType": "application/pdf",
  "sizeBytes": 183402,
  "filename": "invoice-1042.pdf",
  "status": "pending",
  "createdAt": "2026-10-21T09:30:00.000Z",
  "expiresAt": "2026-10-21T09:45:00.000Z",
  "upload": {
    "url": "https://…",
    "method": "PUT",
    "headers": { "Content-Type": "application/pdf", "Content-Length": "183402" },
    "expiresAt": "2026-10-21T09:45:00.000Z"
  },
  "download": null
}
```

</Step>
<Step>

### Upload the file [#upload-the-file]

`PUT` the bytes to `upload.url` with **exactly** `upload.headers`, within 15 minutes. The URL is
valid for that one file only.

```bash
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" -H "Content-Length: 183402" --data-binary @invoice-1042.pdf
```

</Step>
<Step>

### Send it [#send-it]

Use the media `id` as `mediaId` in [`POST /v2/messages`](/messaging/messages), on a connection whose
`capabilities.sendMedia` is `true`. `text` becomes the caption. A send before the upload landed
answers `400` with reason `media_not_uploaded`.

</Step>
</Steps>

## Limits [#limits]

| | Largest file |
| --- | --- |
| Any upload (no `connectionId`) | 16 MB |
| WhatsApp Cloud and WhatsApp Web | 16 MB; photos on WhatsApp Cloud 5 MB |
| Every other channel that sends files | 7 MB |

Over the limit answers `413 payload_too_large` with reason `file_too_large` and `details.maxBytes`.
A connection that cannot send files answers `422 unsupported_channel_action` with reason
`media_not_supported`. Each connection states its own limit as `limits.maxMediaBytes` on
[`GET /v2/connections/{id}`](/channels).

## Download a file you uploaded [#download-a-file-you-uploaded]

`GET /v2/media/{id}` · scope `media:read`

Once the file has landed, `status` is `uploaded` and `download` is a signed link valid for
5 minutes. Fetch the file when you need it rather than storing the link. Until then `download` is
`null`. A key sees the files its member uploaded, or every file when its member sees every
conversation.

Files on messages (what a customer sent you, or any file on a message) are downloaded through the
message: [`GET /v2/messages/{id}/attachments/{index}`](/messaging/messages#download-a-messages-file).
That is the link a webhook's `media[].url` carries.

## When file storage is not available [#when-file-storage-is-not-available]

File uploads and downloads need storage the internet can reach. Where a deployment has none
configured yet, `POST /v2/media`, `GET /v2/media/{id}` and
`GET /v2/messages/{id}/attachments/{index}` answer `503` with code `media_unavailable`. It is a
state of the deployment, not of your request: text, template and interactive sends are unaffected.
Retry later.

Which channels carry files today: [Channels](/channels#at-a-glance).


# Messages (/messaging/messages)

<Status is="live" />

## Send a message [#send-a-message]

`POST /v2/messages` · scope `messages:write` · requires `Idempotency-Key` · live, unpinned key

Choose **where** (exactly one of `to`, `contactId`, `conversationId`) and **what** (text, plus at
most one of `mediaId`, `template`, `interactive`):

| Field | |
| --- | --- |
| `connectionId` | The connection to send from. Required. With `conversationId` it must be that conversation's connection (`400` otherwise). |
| `to` | A recipient: a phone number in E.164 (`+447700900123`) for WhatsApp, an email address for email. Reuses the person's open thread on this connection, wakes a resolved or snoozed one, or opens a new one. |
| `contactId` | An existing contact, reached through their identity on this connection. |
| `conversationId` | Reply into an existing conversation. |
| `text` | The message text, up to 4,096 characters. With `mediaId` it is the caption. |
| `mediaId` | A file uploaded with [`POST /v2/media`](/messaging/media). |
| `template` | An approved WhatsApp template: `{ "id": "…" }` or `{ "name": "…", "language": "en_US" }`, plus `variables` by number (`{ "1": "Layla" }`). See [Templates](/messaging/templates). |
| `interactive` | Up to 3 buttons (`{ "type": "buttons", "body", "buttons": [{ "id", "title" }] }`) or a list (`{ "type": "list", "body", "button", "sections": [{ "title", "rows": [{ "id", "title", "description" }] }] }`), where the connection supports them. |
| `replyTo` | Quote one of this thread's messages (its id). |
| `metadata` | Your own labels, up to 20 string keys (40 characters) and values (500 characters). Stored on the message and returned with it. |

<Tabs groupId="lang" items={['curl', 'Node', 'Python']} persist>
<Tab value="curl">

```bash
curl https://app.gauge.chat/backend/v2/messages \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3a7c0e52-61b9-4d1f-8e2a-9c5b7d3f1e08" \
  -d '{
    "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
    "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
    "text": "Thanks, Layla. Your refund is on its way.",
    "metadata": { "orderId": "A-1042" }
  }'
```

</Tab>
<Tab value="Node">

```js
import { randomUUID } from 'node:crypto';

const res = await fetch('https://app.gauge.chat/backend/v2/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GAUGE_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(), // generate once, reuse on every retry of this send
  },
  body: JSON.stringify({
    conversationId: 'c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c',
    connectionId: '9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f',
    text: 'Thanks, Layla. Your refund is on its way.',
    metadata: { orderId: 'A-1042' },
  }),
});
const { message, status, warnings } = await res.json(); // res.status is 201 or 202
```

</Tab>
<Tab value="Python">

```python
import os, uuid, requests

res = requests.post(
    "https://app.gauge.chat/backend/v2/messages",
    headers={
        "Authorization": f"Bearer {os.environ['GAUGE_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # generate once, reuse on every retry of this send
    },
    json={
        "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
        "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
        "text": "Thanks, Layla. Your refund is on its way.",
        "metadata": {"orderId": "A-1042"},
    },
    timeout=10,
)
body = res.json()  # res.status_code is 201 or 202
```

</Tab>
</Tabs>

### 201 sent, or 202 queued [#201-sent-or-202-queued]

| Status | Means | `status` in the body |
| --- | --- | --- |
| `201 Created` | The channel accepted the message during your request. | `sent` |
| `202 Accepted` | The message is saved and will be dispatched in the background (WhatsApp, email, …). It is **not** sent yet. | `queued` |

Both answer the same body:

```json
{
  "message": {
    "id": "7f3e9a1c-2b4d-4e6f-8a0b-1c2d3e4f5a6b",
    "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
    "type": "message",
    "direction": "outbound",
    "authorType": "automation",
    "authorMemberId": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
    "kind": "text",
    "text": "Thanks, Layla. Your refund is on its way.",
    "status": "queued",
    "failureReason": null,
    "media": null,
    "template": null,
    "via": "api",
    "replyToMessageId": null,
    "metadata": { "orderId": "A-1042" },
    "createdAt": "2026-10-21T09:30:12.418Z"
  },
  "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
  "status": "queued",
  "warnings": []
}
```

A `202` is a promise to try, not a delivery. Follow a queued message to `sent` (or `failed`) with the
[`message.status_updated`](/webhooks/events#messagestatus_updated) webhook, or poll
`GET /v2/messages/{id}`. A message still `queued` after 30 minutes (26 hours on WhatsApp Web, which
may hold a send for its daily cap) is marked `failed`. Retry a timed-out request with the **same**
`Idempotency-Key`: it can never send twice (see [Idempotency](/conventions/idempotency)).

WhatsApp Web connections add `"warnings": ["whatsapp_web_unofficial"]` to every send: see
[WhatsApp Web](/channels/whatsapp-web). A WhatsApp Web number that is still warming up caps how many
messages it sends, new chats included; over the cap a send answers `429`.

## Message someone first [#message-someone-first]

With `to` or `contactId` instead of `conversationId`, a send opens the conversation if there is none
(or reuses and reopens the one there is). On **WhatsApp Cloud** the first message must be an
approved template; WhatsApp allows nothing else:

```bash
curl https://app.gauge.chat/backend/v2/messages \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d2b8e14-7a3c-4f9e-b1d6-0e8c2a4f6b39" \
  -d '{
    "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
    "to": "+447700900123",
    "template": { "name": "appointment_reminder", "language": "en_GB", "variables": { "1": "Layla", "2": "Tuesday 22 October", "3": "10:30" } }
  }'
```

The answer carries the new `conversationId`. See
[Start a conversation with a template](/messaging/templates#start-a-conversation-with-a-template).

## Read a message [#read-a-message]

`GET /v2/messages/{id}` · scope `messages:read`

The message object above. `status` is one of `queued`, `sent`, `delivered`, `read`, `failed`
(outbound) or `received` (inbound). `via` is `api` for a message an API key sent; such a message has `authorType: automation` and
`authorMemberId` set to the key's member. `media` is
`{ mime, filename, mediaId }` when it carries a file (`mediaId` only for a file you uploaded).

## Download a message's file [#download-a-messages-file]

`GET /v2/messages/{id}/attachments/{index}` · scope `messages:read`

A signed download link for a file on a message, one a customer sent or one you sent, valid for
5 minutes. This is the path a webhook's `media[].url` carries. A message carries one file today, so
`index` is `0`.

```json
{
  "messageId": "7f3e9a1c-2b4d-4e6f-8a0b-1c2d3e4f5a6b",
  "index": 0,
  "contentType": "image/jpeg",
  "filename": "receipt.jpg",
  "sizeBytes": 183402,
  "download": { "url": "https://…", "expiresAt": "2026-10-21T09:35:12.000Z" }
}
```

| Answer | Why |
| --- | --- |
| `404 not_found` | No such message for this key, no file at that index, or reason `attachment_not_available`: Gauge holds no copy of the file (for example a WhatsApp Web file that was never fetched) |
| `503 media_unavailable` | File downloads are not available on this deployment yet. Retry later. |

## Delivery history [#delivery-history]

`GET /v2/messages/{id}/status-history` · scope `messages:read`

```json
{
  "messageId": "7f3e9a1c-2b4d-4e6f-8a0b-1c2d3e4f5a6b",
  "status": "delivered",
  "history": [
    { "status": "queued", "occurredAt": "2026-10-21T09:30:12.418Z", "failureReason": null },
    { "status": "sent", "occurredAt": "2026-10-21T09:30:13.020Z", "failureReason": null },
    { "status": "delivered", "occurredAt": "2026-10-21T09:30:15.771Z", "failureReason": null }
  ]
}
```

A message moves `queued` → `sent` → `delivered` → `read`, or ends `failed` with a
`failureReason`. Not every channel reports every step (email has no `read`).

## When a send is refused [#when-a-send-is-refused]

| Answer | `reason` | Why |
| --- | --- | --- |
| `400 validation_failed` | | A missing or conflicting field, an unknown template, or a conversation on another connection; `details` names the field |
| `400 validation_failed` | `media_not_uploaded` | The `mediaId` exists but its file was never `PUT` |
| `403 forbidden` | `sandbox_key_not_supported`, `key_pinned_to_projects` | Test keys and App-pinned keys cannot send |
| `404 not_found` | | The connection, contact or conversation does not exist or is not visible to this key |
| `409 idempotency_mismatch` | | The `Idempotency-Key` was used with a different body |
| `409 conflict` | `idempotency_in_flight` | The first request with this key is still running |
| `413 payload_too_large` | `file_too_large` | The file is over the connection's limit for its type (`details.maxBytes`) |
| `422 unsupported_channel_action` | `outside_24h_window` | Free text to WhatsApp more than 24 hours after the customer's last message, or to someone on WhatsApp Cloud who has no conversation yet: send a template |
| `422 unsupported_channel_action` | `template_not_approved`, `template_language_not_found`, `template_variable_mismatch` | The template is not approved, not in that `language`, or `variables` is not exactly its `{{1}}`..`{{n}}` ([Templates](/messaging/templates#errors)) |
| `422 unsupported_channel_action` | `outside_session_window` | The same, on Instagram or Messenger (their own reply window) |
| `422 unsupported_channel_action` | `send_not_supported`, `media_not_supported`, `templates_not_supported`, `interactive_not_supported`, `quoted_reply_not_supported`, `cannot_start_conversations`, `connection_inactive` | The connection cannot do this (see its `capabilities` on [`GET /v2/connections/{id}`](/channels)) |
| `429 rate_limited` | `whatsapp_web_minute_cap`, `whatsapp_web_daily_cap` | A WhatsApp Web number's warm-up cap; wait `Retry-After` seconds ([caps](/channels/whatsapp-web#send-caps)) |
| `429 rate_limited` | | Your key's or workspace's request rate; see [Rate limits](/conventions/rate-limits) |


# Templates (/messaging/templates)

<Status is="live" />

A **template** is a pre-written WhatsApp message that Meta has reviewed and approved, with
numbered placeholders (`{{1}}`, `{{2}}`, …) for your values. It is the only kind of message you may
send a customer on the WhatsApp Cloud API outside the
[24-hour window](/channels#the-24-hour-window-and-templates): use one to **start a conversation**
with someone who has never written to you, or to pick one back up after the customer has gone
quiet.

Templates are written and submitted for approval in the console (**Templates**), where you can see
Meta's review status, rejection reasons and quality rating. The API reads them; it does not create
them.

| Endpoint | Scope | |
| --- | --- | --- |
| `GET /v2/templates` | `templates:read` | Templates, filtered by `connectionId`, `status`, `language`, `category` |
| `GET /v2/templates/{id}` | `templates:read` | One template |

Test keys may read templates; App-pinned keys may not.

## The template object [#the-template-object]

```json
{
  "id": "6a0e2c4d-8f1b-4d3a-9e5c-7b9d1f3a5c7e",
  "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
  "name": "appointment_reminder",
  "language": "en_GB",
  "category": "UTILITY",
  "status": "approved",
  "body": "Hi {{1}}, a reminder of your appointment on {{2}} at {{3}}.",
  "components": [],
  "variables": ["1", "2", "3"],
  "rejectionReason": null,
  "qualityRating": "GREEN",
  "createdAt": "2026-09-30T12:00:00.000Z",
  "updatedAt": "2026-10-01T08:15:00.000Z"
}
```

`status` is `draft`, `pending`, `approved`, `rejected`, `paused` or `disabled`; only an `approved`
template can be sent. `variables` lists the placeholders a send must fill.

## Send a template [#send-a-template]

Pass `template` to [`POST /v2/messages`](/messaging/messages): the template's `id`, **or** its
`name` and `language` on that connection, and `variables` keyed by placeholder number:

```json
{
  "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
  "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
  "template": {
    "name": "appointment_reminder",
    "language": "en_GB",
    "variables": { "1": "Layla", "2": "Tuesday 22 October", "3": "10:30" }
  }
}
```

## Start a conversation with a template [#start-a-conversation-with-a-template]

Address the send with `to` (an E.164 phone number) or `contactId` instead of `conversationId`, and
the template opens the conversation:

```json
{
  "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
  "to": "+447700900123",
  "template": {
    "name": "appointment_reminder",
    "language": "en_GB",
    "variables": { "1": "Layla", "2": "Tuesday 22 October", "3": "10:30" }
  }
}
```

- **A new number**: Gauge creates the contact, its WhatsApp identity and the conversation, then
  sends the template.
- **A known contact or number**: Gauge uses that contact's conversation on this connection,
  reopening it if it was resolved, so the history stays in one place.
- The answer is `202` with `status: queued` (or `201` with `status: sent` when delivery is
  immediate) and the `conversationId`. Watch
  [`message.status_updated`](/webhooks/events#messagestatus_updated) for delivery.
- Send an `Idempotency-Key`: a retry with the same key answers the same message and sends nothing.

The connection's `capabilities.startConversations` is `true` when templates are enabled for your
workspace. Free text to someone who has no conversation answers `422 unsupported_channel_action`
with reason `outside_24h_window`: WhatsApp allows only a template as the first message.

## Errors [#errors]

Every template check runs **before** anything is written, so a refused send never creates a
contact or an empty conversation.

| Status | `reason` | When |
| --- | --- | --- |
| `400 validation_failed` | | No template with that id, or that name, on this connection |
| `422 unsupported_channel_action` | `template_language_not_found` | The template exists but not in that `language`; `details.languages` lists the ones it has |
| `422 unsupported_channel_action` | `template_not_approved` | The template is `pending`, `rejected`, `paused`, `disabled` or a `draft` |
| `422 unsupported_channel_action` | `template_variable_mismatch` | `variables` is not exactly `{{1}}`..`{{n}}` of the template body; `details.expected` lists them |
| `422 unsupported_channel_action` | `templates_not_supported` | The connection cannot send templates |
| `422 unsupported_channel_action` | `consent_opted_out` | A marketing template to a contact who opted out of marketing (utility templates still send) |

Header parameters (an image, document or video header, or a header variable) and button parameters
(a quick-reply payload or a URL suffix) are not supported over the API yet. Body variables are.


Meta may charge for template messages, depending on their category and the recipient's country.
Gauge passes these fees through at cost.


# Quickstart (/quickstart)

About ten minutes from nothing to a working integration. You need a Gauge workspace on the
**Growth** or **Scale** plan, and a member role that can create API keys.

<Steps>
<Step>

### Create an API key [#create-an-api-key]

In the console, open **Developers → API keys** and choose **Create key**.

- **Name** it after the integration that will use it ("CRM sync"), so the request log reads well.
- **Pick scopes.** Grant only what this integration needs. For this quickstart: `connections:read`
  and `messages:write`. You can only grant scopes your own role can use; the rest are shown but
  disabled, with the reason.
- **Choose live or test.** A test key reaches sandbox data only. See [Environments](/authentication#environments).
- Optionally pin the key to one App, restrict it to your servers' IP addresses, or give it an expiry.

Copy the key when it is shown. **It is shown once.** Gauge stores only a hash, so a lost key cannot
be recovered, only replaced.

A key looks like `pulse_k_live_` followed by 32 characters (`pulse_k_test_…` for a test key). Store
it as a secret on your server, never in a browser or a mobile app.

```bash
export GAUGE_API_KEY="pulse_k_live_..."
```

<Callout title="A key acts as you">
  An API key is tied to the member who created it. It can do what that member can do in the console,
  within the scopes you picked, and nothing more. If that member leaves the workspace, the key stops
  working. See [Keys belong to a person](/authentication#keys-belong-to-a-person).
</Callout>

</Step>
<Step>

### Make your first call [#make-your-first-call]

`GET /v2/me` answers for any valid key. It tells you who the key is, what it may do, and how much
rate-limit budget is left: the quickest way to check a setup.

<Tabs groupId="lang" items={['curl', 'Node', 'Python']} persist>
<Tab value="curl">

```bash
curl https://app.gauge.chat/backend/v2/me \
  -H "Authorization: Bearer $GAUGE_API_KEY"
```

</Tab>
<Tab value="Node">

```js
const res = await fetch('https://app.gauge.chat/backend/v2/me', {
  headers: { Authorization: `Bearer ${process.env.GAUGE_API_KEY}` },
});
const me = await res.json();
if (!res.ok) throw new Error(`${me.error.code}: ${me.error.message} (${me.error.requestId})`);
console.log(me.workspace.name, me.key.scopes);
```

</Tab>
<Tab value="Python">

```python
import os
import requests

res = requests.get(
    "https://app.gauge.chat/backend/v2/me",
    headers={"Authorization": f"Bearer {os.environ['GAUGE_API_KEY']}"},
    timeout=10,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} ({body['error']['requestId']})")
print(body["workspace"]["name"], body["key"]["scopes"])
```

</Tab>
</Tabs>

```json title="200 OK"
{
  "key": {
    "id": "6f1c2a7e-0b8d-4c39-9a51-2f7d3e8b1c40",
    "name": "CRM sync",
    "prefix": "pulse_k_live_x9Qa",
    "environment": "live",
    "scopes": ["connections:read", "messages:write"],
    "pinnedAppId": null,
    "allowedCidrs": null,
    "expiresAt": null,
    "createdAt": "2026-10-21T09:12:44.000Z"
  },
  "member": {
    "id": "0d9e4b12-6a3f-4e8c-b7d1-5c2a9f0e3b87",
    "name": "Amira Haddad",
    "teamIds": []
  },
  "workspace": {
    "id": "a3b5c7d9-1e2f-4a6b-8c0d-2e4f6a8b0c1d",
    "name": "Northwind Dental",
    "plan": "growth"
  },
  "apiVersion": "2026-10-21",
  "rateLimit": {
    "limit": 300,
    "remaining": 299,
    "resetSeconds": 1,
    "workspaceLimit": 600,
    "workspaceRemaining": 599
  }
}
```

Every response also carries an `X-Request-Id` header. Quote it if you ever contact support about a
request.

</Step>
<Step>

### Find the WhatsApp connection to send from [#find-the-whatsapp-connection-to-send-from]

A **connection** is one connected channel account: a WhatsApp number, an email inbox, a web chat.
List them, and pick the WhatsApp one.

```bash
curl https://app.gauge.chat/backend/v2/connections \
  -H "Authorization: Bearer $GAUGE_API_KEY"
```

Each connection says what it can do over the API right now, with your workspace's settings already
applied:

```json
{
  "data": [
    {
      "id": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
      "kind": "whatsapp_cloud",
      "displayName": "+44 20 7946 0958",
      "status": "active",
      "createdAt": "2026-09-02T14:03:11.000Z",
      "capabilities": {
        "sendText": true,
        "sendMedia": true,
        "sendTemplates": true,
        "sendInteractive": false,
        "quotedReplies": false,
        "startConversations": true,
        "broadcast": true,
        "delivery": "queued"
      },
      "flags": { "waTemplates": true, "waCloudMedia": true },
      "warning": null
    }
  ],
  "nextCursor": null,
  "prevCursor": null
}
```

`startConversations: true` on WhatsApp Cloud means you can message someone first, **with an
approved template**: WhatsApp allows nothing else as a first message. See
[The 24-hour window](/channels#the-24-hour-window-and-templates).

</Step>
<Step>

### Send a WhatsApp message [#send-a-whatsapp-message]

`POST /v2/messages` sends on a connection (scope `messages:write`, a live key). Address it one way:
reply into an existing `conversationId`, or reach a `contactId` or a new number (`to`) on a
connection that can start conversations. On WhatsApp Cloud, the first message to someone must be
an approved template (next step); the example below replies into a conversation the customer
started.

Every POST needs an `Idempotency-Key`: if your request times out, retry with the same key and
Gauge sends the message once.

<Tabs groupId="lang" items={['curl', 'Node', 'Python']} persist>
<Tab value="curl">

```bash
curl https://app.gauge.chat/backend/v2/messages \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
    "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
    "text": "Your appointment is confirmed for Tuesday at 10:30."
  }'
```

</Tab>
<Tab value="Node">

```js
const res = await fetch('https://app.gauge.chat/backend/v2/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GAUGE_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-confirmation',
  },
  body: JSON.stringify({
    connectionId: '9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f',
    conversationId: 'c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c',
    text: 'Your appointment is confirmed for Tuesday at 10:30.',
  }),
});
const { message, status } = await res.json(); // res.status: 201 sent, 202 queued
```

</Tab>
<Tab value="Python">

```python
res = requests.post(
    "https://app.gauge.chat/backend/v2/messages",
    headers={
        "Authorization": f"Bearer {os.environ['GAUGE_API_KEY']}",
        "Idempotency-Key": "order-1042-confirmation",
    },
    json={
        "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
        "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
        "text": "Your appointment is confirmed for Tuesday at 10:30.",
    },
    timeout=10,
)
body = res.json()  # res.status_code: 201 sent, 202 queued
```

</Tab>
</Tabs>

The answer is `{ message, conversationId, status, warnings }`. **`202 Accepted` with
`status: queued`** is the normal answer on WhatsApp: the message is saved and leaves right after the
request returns, so it is not yet sent. Its progress (`sent`, `delivered`, `read`, or `failed` with
a reason) arrives as [`message.status_updated`](/webhooks/events#messagestatus_updated) events. A
channel that sends during the request answers `201` with `status: sent`.

More than 24 hours after the customer's last message, free text is refused with
`422 unsupported_channel_action` and reason `outside_24h_window`; send an approved
[template](/messaging/templates) instead.

</Step>
<Step>

### Message a customer first, with a template [#message-a-customer-first-with-a-template]

To reach someone who has not written to you, send an approved template with `to` (an E.164 number)
or `contactId`. Find the template's `name`, `language` and `variables` with
`GET /v2/templates?connectionId=…&status=approved`.

```bash
curl https://app.gauge.chat/backend/v2/messages \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reminder" \
  -d '{
    "connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
    "to": "+447700900123",
    "template": {
      "name": "appointment_reminder",
      "language": "en_GB",
      "variables": { "1": "Layla", "2": "Tuesday 22 October", "3": "10:30" }
    }
  }'
```

Gauge creates the contact and the conversation (or reuses them), sends the template and answers
with the `conversationId`. When the customer replies, the window opens and free text works there.
See [Start a conversation with a template](/messaging/templates#start-a-conversation-with-a-template).

</Step>
<Step>

### Receive replies by webhook [#receive-replies-by-webhook]

When the customer answers, Gauge can POST the message to your server.

1. Open **Developers → Webhooks** and choose **Add endpoint**.
2. Enter your HTTPS URL and subscribe to `message.received`.
3. Copy the **signing secret**. It is shown once, like a key.
4. Choose **Send test event** to check that your endpoint answers `2xx`.

Your endpoint must verify the signature before it trusts the body. Here is a complete receiver in
Node; [Verify signatures](/webhooks/verify-signatures) has Python and PHP, and every detail.

```js title="server.js"
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.GAUGE_WEBHOOK_SECRET;

// Verify against the RAW body: re-serialised JSON would not match the signature.
app.post('/gauge/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyGaugeSignature(req.headers, req.body, SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(204); // answer fast; do the work after
  handle(event).catch(console.error);
});

app.listen(3000);
```

Copy `verifyGaugeSignature` from [Verify signatures](/webhooks/verify-signatures#node). Then read
[Forward inbound messages](/webhooks/inbound-messages) for retries, deduplication and ordering.

</Step>
</Steps>

## Next [#next]

- [Authentication and keys](/authentication): scopes, test keys, rotation.
- [Conventions](/conventions): errors, idempotency, pagination and rate limits, which apply to every call.
- [Channels](/channels): what each channel can and cannot do over the API.


# API reference (/reference)

This reference is **generated**. Every page under it is built from the OpenAPI 3.1 document the API
itself serves at `GET /v2/openapi.json`, at the same commit. It lists exactly what is live, with
the scope each endpoint needs, its parameters, its responses and samples in curl, Node and Python.

- **Machine-readable:** [`/openapi/v2.json`](/openapi/v2.json) (or `https://app.gauge.chat/backend/v2/openapi.json`).
  Feed it to a code generator or an API client.
- **Server:** `https://app.gauge.chat/backend`.
- **Authentication:** `Authorization: Bearer <key>` on every operation ([Authentication](/authentication)).
- **Scopes:** each operation shows the scope it needs as `x-scopes`; `x-idempotent: true` marks
  operations that need an `Idempotency-Key`.
- **Errors:** every operation answers errors in the shared `Error` envelope ([Errors](/conventions/errors)).

Every live `/v2` endpoint is listed here, including the messaging and webhook-management
operations; the guides ([Messaging](/messaging), [Webhooks](/webhooks)) explain how to use them.

## Version 1 [#version-1]

`/v1` is frozen: it keeps working and gets security fixes only. The [Support API](/support) lives
on `/v1/support` and is documented in its own section; its OpenAPI document is served by the API at
`GET /openapi.json`.


# Status and help (/status)

## Is it you or us? [#is-it-you-or-us]

1. **Read the error.** Every error has a `code` and a `message`; [Errors](/conventions/errors) says
   what to do about each. A `4xx` is almost always about the request; a `5xx` is ours.
2. **Check the key.** `GET /v2/me` answers for any valid key and shows its scopes, environment,
   pin, allowlist and remaining rate limit.
3. **Look at the request log.** **Developers → Logs** shows every `/v2` request for 14 days, with
   its status and request id.
4. **For webhooks**, open the endpoint in **Developers → Webhooks**: every attempt, its status or
   failure reason, and your server's response.

Gauge does not publish a public status page yet.

## Contact support [#contact-support]

Email **[support@gauge.chat](mailto:support@gauge.chat)**, or use the help menu in the console. To
get an answer quickly, include:

- the **request id** (`X-Request-Id`, or `error.requestId`) of a failing request;
- the time it happened, with your time zone;
- the endpoint and method, and the `error.code` you got;
- for a webhook, the endpoint URL and the event id.

**Never send an API key or a signing secret**, not even a test one. The key's prefix (shown in the
console, like `pulse_k_live_x9Qa`) is enough to identify it.

## Security issues [#security-issues]

If you believe you have found a security vulnerability in Gauge, email
[support@gauge.chat](mailto:support@gauge.chat) with "Security" in the subject, and do not test it
against other customers' data.


# Support embed S1: the API core (/support/api-s1)

{/* GENERATED from docs/support/api-s1.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

This page is the reference for the console UI lane and for integrators. Machine truth lives in `GET /openapi.json`, and the zod sources are in `packages/types/src/support-embed.ts`, `support-customer-sync.ts`, `support-public-api.ts` and `api-keys.ts`. The customer-sync guide is in [customer-sync.md](/support/customer-sync).

Migrations: **0227** (chat embed columns), **0228** (customer status `deactivated`, `metadata`, `updated_at` cursor, `support_customer_sync_runs`), **0229** (`api_keys.project_ids`).

## 1. Project chat and voice enablement (S0 finding 0.1) [#1-project-chat-and-voice-enablement-s0-finding-01]

Before S1, nothing wrote `chat_enabled` or `chat_connection_id`. Now both doors write them through **one** writer, `SupportProjectsService.update`, under the K-8 `version`:

| Door | Route | Auth |
|---|---|---|
| console | `PATCH /support/projects/:id` (`If-Match: <version>`) | session, `support:edit` |
| console | `POST /support/projects/:id/chat/secret/reveal` | `support:edit` |
| console | `POST /support/projects/:id/chat/secret/rotate` `{overlapHours: 0\|24}` | `support:edit` |
| API | `GET` / `PATCH /v1/support/projects/:id` (`version` in body) | `support:read` / `support:rw` |
| API | `POST /v1/support/projects/:id/chat/secret/reveal` · `/rotate` | `support:rw` |

**PATCH fields** (shared, `SupportProjectEmbedPatchFields`): `chatEnabled`, `voiceEnabled`, `identityMode`, `chatConnection`, `chatAllowedOrigins` (`[]` clears), `chatIdentityTsRequired`.

`chatConnection` is an **act**, not a column write:

- `{mode:"provision"}` mints a `webchat` connection (`routing.provisionedBy="support"`) with a fresh 32-byte secret, sealed AES-256-GCM (`@pulse/db` channel-credentials), and binds it.
- `{mode:"bind",connectionId}` adopts a live `webchat` connection of the same workspace that no other project holds. Another tenant's id returns 404, a non-webchat line 422, a line already held 409. A line without a secret gets one minted.
- `{mode:"unbind"}` detaches the line and switches chat off. It soft-deletes the connection only if support provisioned it.

The act runs in the same transaction as the version-checked UPDATE, so a stale version rolls back a provision. `chatEnabled:true` with no line returns 409 `Chat needs a chat line first`. A second `provision` returns 409.

**Project DTO additions** (console `SupportProjectDto`, all optional on the wire; public `SupportPublicProjectDto`, all present): `chatEnabled`, `voiceEnabled`, `chatConnectionId`, `chatAllowedOrigins`, `chatIdentityTsRequired`, `chatSecretPendingReveal`, and on the console only `chatPreviousSecretExpiresAt`. **The secret is never on a read.**

**Reveal-once.** `revealSecret` claims the window with one conditional UPDATE (`revealed_at IS NULL OR < set_at`), so a second or racing reveal returns 409. It's audited as `support.project.chat_secret_revealed`. The response is `SupportChatSecretDto {projectId, connectionId, secret, previousSecretExpiresAt}` with `Cache-Control: no-store`, and it's never stored for Idempotency-Key replay.

**Rotate.** This mints a new secret. The response is its reveal. With `overlapHours: 24`, the old secret stays sealed in `support_projects.chat_previous_secret` and keeps verifying until it expires. `0` kills it immediately. Audited as `support.project.chat_secret_rotated`.

**Console UI notes:** show a "Reveal secret" button only while `chatSecretPendingReveal`. After a reveal, offer "Rotate" (24 h overlap by default; "0 h" labelled *the secret leaked*). Show `chatPreviousSecretExpiresAt` as "old secret still accepted until …".

### Widget identity: identityHash v2 (default) and v1 [#widget-identity-identityhash-v2-default-and-v1]

The hash always travels in the `x-pulse-identity` header; the visitor id travels as `externalId` in
the `POST /support/chat/session` body.

- **v2 (the documented default):** hash `"v2\n" + externalId + "\n" + identityTs` and send `identityTs` (epoch
  **seconds**) in the session body. It's accepted within **±10 min**, so a leaked hash cannot be
  replayed later. The hosted widget sends it when the page passes `identityTs` to
  `PulseWebchat.init` (and `loadWidget` in `@gauge/support/browser`); the SDK helpers are
  `signIdentity` / `sign_identity`. A project with `chatIdentityTsRequired: true` refuses v1.
- **v1 (legacy):** `hex(HMAC-SHA256(secret, externalId))`, no `identityTs`. Still accepted while
  `chatIdentityTsRequired` is off, so existing embeds keep working.
- During a rotation overlap, a hash under the previous secret verifies too (v1 or v2).

### Origin allowlist [#origin-allowlist]

`chatAllowedOrigins` holds up to 50 entries of `https://host[:port]` or `https://*.host`. `http` is allowed only for localhost. A wildcard matches subdomains and never the apex. It's checked at `POST /support/chat/session` **and** `/offline` before any write. A non-empty list refuses a missing `Origin` too. A refusal is `403 {error:{code:"forbidden",message:"origin not allowed"}}`. An empty list means unrestricted (the pre-S1 behaviour).

### The sandbox project (Support DX) [#the-sandbox-project-support-dx]

Every workspace has exactly one **sandbox** support project (`isSandbox: true` on both project
DTOs; `support_projects.is_sandbox`, one per workspace by 0237's partial unique index). It is
created on the first `pulse_k_test_` request to `/v1/support` or the first visit to
`/developers/support` (`POST /support/projects/sandbox`, console, `support:create`).

- **Key modes.** A test key (`pulse_k_test_`) acts **only** on the sandbox: the server pins it there
  whatever it was minted with. A live key never reaches the sandbox. A named project of the wrong
  mode — route `projects/:id`, `:projectId`, a body `projectId` / `projectIds` /
  `customers[].projectIds`, a query `projectId` — is `403 {code:"forbidden", reason}` with
  `reason` `test_key_live_project` or `live_key_sandbox_project`; a test key gets that 403 for any
  non-sandbox id, existing or not. A ticket or article of the wrong mode is the usual 404. Minting a
  test key pinned to a live project, or a live key pinned to the sandbox, is a 400.
- **Customers.** A customer whose every grant is on the sandbox is sandbox data: a live key cannot
  see, list, reconcile, claim (by ref: 404; by email: 422 `email_unavailable`) or adopt it. A
  customer shared with a live project stays live data; a live key never sees its sandbox grant.
- **Free.** It never takes a support-project slot, and its conversations never count toward
  `conversationsPerMonth`, billing meters or analytics (overview, SLA, conversation reports).
- **Nothing leaves the building.** Emails are recorded `sent` with `provider_ref: "sandbox"` and a
  `support_sandbox_email_suppressed` log line, never handed to the transport (magic links too: sign
  sandbox customers in with session links). No voice (refused by name and by a CHECK), no phone
  number binding, no AI agent turns and no Pulse scoring (so no AI credits).
- **Webhooks** carry `livemode: false` for sandbox events (see below).
- **Reset** (`POST /support/projects/:id/sandbox/reset`, console, `support:delete`, body
  `{confirm: <project key>}`) deletes the sandbox's customers, tickets, chats and articles in one
  transaction, audited as `support.project.sandbox_reset` with the counts. The project, its id, its
  chat line and its portal host survive. Refused on a live project (422 `not_sandbox`).

### Webhook envelope: `livemode` [#webhook-envelope-livemode]

Every delivery body carries `livemode` (additive): `false` when the event is about the sandbox
project — its `projectId`, a project/ticket/article entity in it, a conversation on its chat line,
or a sandbox-only customer — and `true` otherwise (including console test events). A receiver
that ignores it sees the same body as before; one that serves production should drop
`livemode: false`.

## 2. Customer lifecycle [#2-customer-lifecycle]

| Route | Scope | Notes |
|---|---|---|
| `GET /v1/support/customers` | `support:read` | filters `email`, `externalRef`, `status`, `projectId`; `updatedSince` reconcile mode |
| `GET /v1/support/customers/:id` | `support:read` | `SupportCustomerRecordDto` |
| `PUT /v1/support/customers/by-ref/:externalRef` | `support:rw` | upsert, wraps `findOrCreateByEmail` (unedited) |
| `PATCH /v1/support/customers/:id` | `support:rw` | `name`, `locale`, `metadata`, `status` |
| `POST` / `DELETE /v1/support/customers/:id/projects/:projectId` | `support:rw` | delegates to `SupportProjectCustomersService` (audited, evented) |
| `POST /v1/support/customers/:id/sessions/revoke` | `support:rw` | `{revoked: n}`; REST and live sockets |
| `POST /v1/support/customers/:id/erase` `{reason}` | `support:rw` **+ `support-erase:rw`** | delegates to `CustomerErasureService` |
| `POST /v1/support/customers/sync` | `support:rw` | ≤500, Idempotency-Key, per-item results |
| `POST /v1/support/customers/status` | `support:rw` | batch status move |

`SupportCustomerRecordDto`: `id, externalRef, email, name, locale, status, metadata, projectIds (filtered to the key's pin), emailVerifiedAt, createdAt, updatedAt`. The console's `SupportCustomerDto` gained optional `metadata` and `updatedAt`. The console `PATCH /support/customers/:id` accepts `status: deactivated` and routes every status through `SupportCustomersService.changeStatus`.

**Console lane: render `metadata` as text, never as HTML.** `metadata` is written by the tenant's integration, so on our side it is untrusted input. Agents will see it. As of S1, no console, portal or widget path renders it (checked 2026-10-10: `apps/web`, `apps/portal`, `apps/widget` have no reader). The first surface that shows it must:

- render every key and value as a React text node. Don't use `dangerouslySetInnerHTML`, Markdown or linkification, and don't use the value in an `href`/`src` or a `style`.
- truncate long values visibly, not silently.
- ship with a component test proving that a value like `<img src=x onerror=alert(1)>` renders as literal text.

If metadata ever reaches an AI agent's prompt, the same rule applies there: quote it as data, never as instructions. (Security review #10.)

**Status semantics** (founder decision):

- `blocked` is a full lockout. Every session row is revoked and `customer_session_revoked` is published, so sockets drop immediately.
- `deactivated` is **read-only**. The session resolver admits it as `readOnly`, and `CustomerSessionGuard` refuses every non-GET/HEAD with `403 This account is read-only`. That covers portal replies, attachments, CSAT, new tickets, voice and meetings.
- **Project-pinned keys (security review).** A customer's status applies to every project. A pinned key changes it only for a customer served **exclusively** by its pinned projects. If another project also serves the customer, `blocked`/`deactivated` lands at **project level** instead: the customer's grants on the key's projects are revoked (`access_revoked`, audited), along with the portal sessions bound to those projects. The customer's own status, its other grants and its other sessions are untouched. Project level is a full revoke of that project's access, not a read-only mode. The answer marks it:
  - `PATCH` returns `{scope:"project", customerId, status, revokedProjectIds}` instead of the record.
  - `PUT` by-ref adds `scope:"project"`.
  - Batch and sync results add `scope:"project"`.
- A pinned key **cannot lift** a shared customer's workspace-wide block or deactivation: `403 forbidden`. Restoring that customer is for a workspace-wide key or the console.
- `POST /customers/:id/sessions/revoke` with a pinned key revokes only the sessions bound to the key's projects.

**Events (new):**

- `support.customer.unblocked`, `support.customer.deactivated`: `{version, customerId, projectId}`, one per granted project.
- `support.customer.updated`: `{version, customerId, projectId, fields: ("name"|"locale"|"email"|"metadata")[]}`.

All carry ids only. A no-op change emits nothing.

## 3. Enforcement: blocked and deactivated open nothing new [#3-enforcement-blocked-and-deactivated-open-nothing-new]

Every door uses one predicate, `customers/customer-status.ts customerCanOpenNew`:

| Door | Refusal |
|---|---|
| `POST /v1/support/projects/:id/tickets` (`resolveRequester`, by ref **or** email) | 403 `reason: customer_inactive`, before any grant |
| widget chat open, when the hmac `externalId` equals a customer's externalRef, or there's a portal session | 403 at session open, before ingest |
| chat escalate and offline capture | 403, no ticket, no grant |
| inbound email, new thread | bridge outcome `skipped`, no ticket |
| portal writes (deactivated) | guard 403; reads still work |
| request a callback: portal, widget, `POST /v1/support/callbacks` (also a grant blocked on that project) | 403 `reason: customer_inactive`, before any ticket ([callbacks.md](/support/callbacks)) |

Each refusal is mutation-proven: deleting the check turns its test red.

**Callbacks** ([callbacks.md](/support/callbacks)). `callback_enabled` (0238) turns "Request a callback" on with or
without `voiceEnabled`. The API surface is `POST/GET /v1/support/callbacks`, `GET /v1/support/callbacks/:id`
and `POST /v1/support/callbacks/:id/cancel`, under the same pins, test-key rule and `Idempotency-Key` as the
rest of `/v1/support`.

## 4. Security hardening [#4-security-hardening]

- **Project-pinned keys.** Mint with `projectIds: [...]` (`MintApiKeyBody`; validated against the workspace). On `/v1/support`, every other project, its tickets, and any customer reachable only through it is a **404**, the same answer as cross-tenant. A pinned key can't create projects (403). Customers it creates default into its pin. Outside `/v1/support`: `POST /v1/agents/events` with a pinned key accepts only its projects (any other `projectId` is the unknown-project 404) and `GET /v1/agents/events` lists only their events; the `/v1` contacts / conversations / deals surface has no project notion and refuses a pinned key with `403 {reason: "key_pinned_to_projects"}` (use a workspace-wide key). Every new api-key controller must declare how it treats pins (`@ApiKeyPins`, census-tested); an undeclared one refuses pinned keys. `ApiKeyDto.projectIds` exposes the pin for the console.
- **Capability scopes** `support-sessions:rw` (handoff, session link and meeting mints) and `support-erase:rw` (GDPR erase). `ApiKeyGuard` checks them **on top of** CASL; `*:rw` never implies them. They're exported as `API_KEY_CAPABILITY_SCOPES` and deliberately kept off the permission-grid catalogue, which round-trips them via `custom`. **Console lane:** add two explicit checkboxes. **Migration note:** existing keys that mint sessions need the new scope. Prod had 0 support keys on 2026-10-10.
- **API session links**: `ttlSeconds ≤ 900`, single-use only.
- **Webhooks**: each body carries `id` (= outbox id, stable across retries and resends). The documented replay window is ±5 min on `x-pulse-timestamp`.
- **D254**: `webhook.*` filters are refused at create and update.
- **D248**: a `{project}` template is never a link origin.
- **Handoff**: both exchange routes answer `Referrer-Policy: no-referrer`. **Portal lane:** add the same header to `/auth/handoff`, the page whose URL holds the token. `apps/portal/next.config.mjs` currently sends `strict-origin-when-cross-origin`.

## 5. Assumptions recorded (no questions asked, per the brief) [#5-assumptions-recorded-no-questions-asked-per-the-brief]

1. `support-sessions` is a capability scope, not a new RBAC `PermissionArea`. A new area would touch `rbac.ts` and role seeds outside this lane. The guard-level check gives the same isolation.
2. GDPR erase over the API requires a second explicit capability, because keys never receive `delete`.
3. The audit trail is a dedicated table, so integrators and the console can list runs. Per-item rows hold ids and codes only.
4. Deactivate leaves sessions alive (read-only). Block revokes them.
5. An hmac visitor is mapped to a support customer **only** when its verified externalId equals that customer's `external` identity. No new identity rows are written at chat open.
6. Unbind soft-deletes only connections support provisioned. A bound Channels connection is left intact.
7. The Referrer-Policy on the token page itself belongs to the portal lane (see §4).

## 6. Native Help & Support screens: live status and the help centre [#6-native-help--support-screens-live-status-and-the-help-centre]

For a native app's Help & Support screen (Salonvira is the first consumer). The founder rule: hours, staffing and "who answers" are configured **in Gauge only**. The app reads them here and stores none of it. Call these from your **backend** with the server key. Never ship the key in the app. Zod sources: `packages/types/src/support-native.ts`. Guide: [native-screens.md](/support/native-screens).

| Route | Scope | Notes |
|---|---|---|
| `GET /v1/support/projects/:id/status?integration=<key>` | `support:read` | live status, cached ≤ 10 s, 600/min per key |
| `GET /v1/support/projects/:id/articles/search?q=&locale=en\|ar&integration=&limit=` | `support:read` | published + public only, highlights, 120/min per key |
| `GET /v1/support/projects/:id/articles/:article?locale=&integration=` | `support:read` | `:article` is the id or the slug, 600/min per key |

All three: a pinned key gets **404** outside its projects. A test key acts only on the sandbox, and a live project is 403 `test_key_live_project`. `integration` is an integration key of the App. An unknown key is 404 with message `unknown_integration: …`, the same as the session mints. Over budget answers 429 `rate_limited` (budgets: `public-api/native-api-limits.ts`, keyed by API key id).

### Status (`SupportProjectStatusDto`) [#status-supportprojectstatusdto]

| Field | Source (all live) |
|---|---|
| `answering` | `decide`'s `effectiveMode` for a new chat on the integration, **after** the day/night switch (`after_hours_mode`). `null` only for an App with no integration row. |
| `aiActive` | the Decision's `aiAllowed`. Always `false` in the sandbox, because it never runs AI turns. |
| `teamOnline`, `availableCount.chat` | the integration's roster (its Team, else the App's members), online in agent presence or (under `apps.v2.routing`) Available in the one agent state |
| `availableCount.call` | the in-app call pool (`availableAgentIds`: Available, not DND, `taking_calls` 0259) ∩ the integration's Team |
| `hours` | the clock `decide` reads: the Team calendar, else the App's SLA clock (project calendar with holidays, team, workspace). `openNow` **is** decide's `inHours`. `todayRanges` is walked with the same evaluator, so holidays and special hours apply. `configured: false` means nothing is set anywhere, so the desk is always open (`openNow: true`, no ranges). |
| `typicalFirstReply` | median of `support_chat_sessions.first_response_secs` (time to the first reply from a **person**), chats queued in the last **30 days**, scoped to the integration (an unstamped chat counts for the App's default integration). Below **10** conversations it is `{seconds: null, reason: "not enough data", sampleSize, minimumSample: 10, windowDays: 30}`. |
| `channels.chat` | `not_offered` (integration offers), `project_paused`, `integration_paused`, `chat_disabled`, else the widget's own `resolveChatAvailability` (`outside_business_hours` / `no_agents_online`) |
| `channels.call` | the portal call probe (`SupportVoiceCapabilityService.readForServer`): `voice_disabled`, `queue_closed`, `wallet_floor`, …; `not_configured` when voice isn't mounted |
| `channels.ticket` | `not_offered`, `project_paused` or `integration_paused`, else available |

**Cache.** The answer is cached in-process per (workspace, project, integration) for **10 s** (`SUPPORT_STATUS_CACHE_SECONDS`) and sent with `Cache-Control: private, max-age=10`. A console change shows within 10 s.

### Help centre [#help-centre]

These routes use the **portal's** `KbPublicService`, so results match the portal exactly. It runs the hybrid search (folded full-text with Arabic alef/ta-marbuta/diacritic folding, title trigram, and the pgvector leg when words find too little). It serves only published, public live revisions, with related articles and language variants. Integration scope follows the P3 rules. A shelf limited to no integration is shared. A shelf limited to `salon` is returned **only** for `integration=salon`, never for `customer` and never without an integration. The key asserts the integration, the same way the session mints take `integration`. With `apps.v2.knowledge` off, or a paused or draft integration, only shared shelves are returned (fail closed). Search hits carry `highlights: {title, excerpt}` as `[start, end)` UTF-16 offsets into the original strings. They are data, never markup.

Static `search` wins over `:article`, so an article slugged `search` has to be read by id.

**Mutation-proven** (each turns its test red when removed): pinned key 404 (status and articles), drafts and internal never returned (search, slug, id), salon-only article never returned for `customer`, first-reply integration isolation.

**Assumptions recorded (status lane).** (1) `typicalFirstReply` measures the first reply from a person, the moment `markAnswered` records. AI replies are instant and would make the number meaningless. (2) With `?integration` omitted, `typicalFirstReply` covers the whole App while `answering` uses the App's default integration. (3) `channels.chat` passes the Decision to the widget rule only when `apps.v2.decide` enforces, as the widget does, so the API never claims chat is open where the widget would say offline. (4) The help-centre `offers.helpCentre` switch is not applied to these reads. It governs the widget's display, and a server read is the tenant's own choice. (5) No migration was needed.

## 7. Native Help & Support screens: requests, threads and unread [#7-native-help--support-screens-requests-threads-and-unread]

The customer's side of their requests, driven by your **backend** AS one signed-in user, named by `externalRef` (your user id). Zod sources: `packages/types/src/support-native-threads.ts` (+ `SupportTicketContext` in `support.ts`). Guide: [native-screens.md](/support/native-screens#requests-threads-and-unread).

| Route | Scope | Notes |
|---|---|---|
| `GET /v1/support/projects/:id/tickets?externalRef=&statusGroup=&cursor=&limit=` | `support-tickets:read` | the customer's requests (§7.1) |
| `GET /v1/support/projects/:id/topics?integration=` | `support-tickets:read` | the App's topics for a native screen (§7.2a) |
| `POST /v1/support/projects/:id/tickets` | `support-tickets:rw` | create; takes `context`, `integration`, `topicId`, `details` (§7.2, §7.2a) |
| `GET /v1/support/projects/:id/tickets/:ticketId/messages?externalRef=&cursor=&limit=` | `support-tickets:read` | the thread (§7.3) |
| `POST /v1/support/projects/:id/tickets/:ticketId/messages` | `support-tickets:rw` | reply AS the requester, `Idempotency-Key` |
| `POST /v1/support/projects/:id/tickets/:ticketId/attachments` | `support-tickets:rw` | upload AS the requester, `Idempotency-Key` |
| `GET /v1/support/projects/:id/customers/by-ref/:externalRef/unread` | `support-tickets:read` | unread counts (§7.4) |
| `POST /v1/support/projects/:id/customers/by-ref/:externalRef/read` | `support-tickets:rw` | mark read (§7.4), `Idempotency-Key` |

All of them: a pinned key gets **404** outside its projects; a test key works only on the sandbox (403 `test_key_live_project` / `live_key_sandbox_project`); another tenant's ids are 404.

**`Idempotency-Key` (409 rule).** On every POST here, and on `POST /projects/:id/tickets` and `POST /tickets/:id/replies|notes`, the key's fingerprint is the body **plus the route's resource ids** (project id, ticket id, or project id + `externalRef`; a create's requester is in its body). The same key with the same ids and body replays the first answer; the same key with a different body **or a different id** (another ticket, project or customer) is **409 `conflict`**, never another resource's stored answer.

**Rate limits** (per customer per project, on top of the per-key budgets): reply as the customer **30 / minute**; upload as the customer spends the portal's own upload bucket (**10 / hour**, shared with the portal). Over budget: **429 `rate_limited`** with `Retry-After` (seconds) and `error.details.retryAfterSecs`; nothing is written and an `Idempotency-Key` claim is released, so retry the same key after the wait.

### 7.1 List items [#71-list-items]

`SupportTicketListItem` = the public ticket + `statusGroup` (`open` = new/open/on_hold, `waiting_on_customer` = pending, `resolved` = solved/closed), `lastActivityAt`, `lastReply` (`{messageId, authorType: customer|agent|ai|system, preview ≤140 chars, truncated, createdAt}`, never an internal note, or `null`), `sla` (`{state: none|on_track|at_risk|breached, clock, nextDueAt}`), `integration` (`{id, key}` or `null`), **`context`** (`{type, id}` or `null`) and **`unread`** (team messages the requester has not read). Newest first; the cursor is the last row's id. An unknown requester is an empty page.

### 7.2 Create with `context` and `integration` [#72-create-with-context-and-integration]

`context: {type: booking|transaction|invoice|voucher|payout, id}`: `id` is YOUR record id (`[A-Za-z0-9][A-Za-z0-9._:-]*`, ≤128). Gauge never dereferences it. **You verify the customer owns the record before sending it.** It is stored in `support_tickets.custom_fields.context`, shown to agents on the ticket ("About: Booking BK-1042"), and returned as `context` on the ticket (`GET /tickets/:id`, the create answer), the list items and the thread header. `integration` (a key) stamps the ticket's write-once `integration_id`: unknown on this App → 404 `unknown_integration: …` (checked before any write); with `apps.v2.identity` on, a requester not granted it → 403 `integration_not_granted: …`, also checked **before any write** (no project grant, no find-or-created customer, no ticket).

### 7.2a Topics: list them, file a request under one (0269) [#72a-topics-list-them-file-a-request-under-one-0269]

`GET /v1/support/projects/:id/topics?integration=<key>` (`support-tickets:read`) → `PublicTopicsResponse` `{topics: [{id, name, description, starter, detailFields}]}`: the App's **active** topics, this integration's starter buttons first (`starter: true`, in their order), then the rest by position. `integration` absent = the App's default integration; unknown → 404 `unknown_integration`. `detailFields` (≤3): `{key, label, type: text|choice|date, required, options? (choice), fromAttr? (chat fills it from that app attribute)}`. The built-in "Other" is never listed. Zod: `packages/types/src/support-topics-ai.ts`.

`POST /v1/support/projects/:id/tickets` takes optional **`topicId`** (an active topic of THIS App, else 422 `invalid_topic`, nothing written) and **`details`** (key → value, needs `topicId`; checked against the topic's `detailFields`: an unknown key, a choice off its list, an unparseable date or a missing required value → 422 `invalid_details: “<label>” …`). The topic lands in `support_tickets.topic_id` (0269) and the details in `custom_fields.topic_details`, in the creation transaction. Ticket rows (`GET …/tickets`, `GET /tickets/:id`, the create answer) and thread headers carry **`topic: {id, name}`** or `null`. `GET …/status` carries **`topics`** (this integration's starter topics, `{id, name}`, in order).

### 7.3 Thread, reply and upload [#73-thread-reply-and-upload]

The rules are in `native-threads.service.ts`'s header: `externalRef` must be the ticket's requester, else the **same 404** as an unknown id; customer-visible messages only (`inbound` / `outbound`, never `internal` notes or `system` lines) from the ticket's creation on; the reply goes through the portal's own `TicketsService.addPublicReply` (customer actor, no member) so status, events, SLA and notifications match the portal; blocked / deactivated / ungranted requesters read (`readOnly: true`) but every write is 403 `reason: customer_read_only`. `SupportThreadTicketDto` carries `context` and `createdAt`.

Attachments carry `downloadState`: `scanning` / `refused` (infected) / `unavailable` / `ready` (+ `download: {url, expiresAt}`). A URL is only ever minted by the SAME object-store presigner the portal's download uses; **no deployment binds one yet** (the store refuses, `portal.module.ts`), so today every clean file reads `unavailable` with `download: null`, on the portal and here alike. Gauge never returns a URL that cannot work. When a presigner is bound, `ready` URLs are short-lived (its TTL; `expiresAt` says when).

### 7.4 Unread and mark-read [#74-unread-and-mark-read]

The customer's read state is **one table** (`support_customer_read_marks`, migration **0260**, RLS quad): one row per (customer, thread) holding the newest message read, `(read_through_at, read_through_message_id)` in the thread's own order. It is shared with the portal: opening a ticket's timeline there moves the same mark (`markTicketSeenSafely`), so a badge cleared on the web is cleared in the app.

Unread = customer-visible **team** messages (`outbound`: agent, AI, API sends) after the mark, over the customer's tickets as requester (from the ticket's creation) and their chats in the project (up to the handoff, if the chat became a ticket, so nothing counts twice). The customer's own words, notes and system lines never count.

`GET …/unread` → `SupportCustomerUnreadDto` `{externalRef, customerId|null, total, ticketsUnread, chatsUnread, tickets: [{ticketId, unread, lastUnreadAt}], chats: [{chatId, unread, lastUnreadAt}]}` (only threads with something unread, newest first, lists ≤100, `total` always complete). Unknown `externalRef` → zeros with `customerId: null`. Unknown project → 404. `Cache-Control: no-store`.

`POST …/read` body `SupportMarkReadBody`: `{scope: "ticket", ticketId, throughMessageId?}` | `{scope: "chat", chatId, throughMessageId?}` | `{scope: "all"}`. Without `throughMessageId` the mark moves to the thread's newest visible message. A thread or message that is not this customer's → 404. Marks only move forward (`ON CONFLICT … WHERE old < new`); an older id answers 200 and changes nothing. Allowed for read-only customers (it writes no message). Answers the new summary.

**Webhook `support.customer.unread_changed`** (ids + counts only): `{version, projectId, customerId, externalRef|null, cause: read|team_message, total, ticketsUnread, chatsUnread, tickets: [{ticketId, unread}], chats: [{chatId, unread}]}`. Emitted in the same transaction as the write that moved the count: a mark-read that moved something (`cause: read`, also from the portal), an agent's public ticket reply and a team (agent / AI / system) chat line for a known customer (`cause: team_message`). The team-message emits run inside a SAVEPOINT, so a failure there is logged and never rolls the message back. `version` is **commit-ordered** (a per-customer lock is taken before the counts are read and the version drawn, in the writer's transaction), so the highest `version` always carries the latest counts: keep the highest per customer and ignore lower ones. It is an increasing integer, not a time. On any doubt (a gap, a restart, an out-of-order delivery) re-fetch `GET …/unread`: the webhook is a hint, the GET is the truth.

### 7.5 Security, mutation-proven [#75-security-mutation-proven]

`native-tickets.integration.test.ts`, `native-threads.integration.test.ts`, `native-unread.integration.test.ts`, `native-rate-limit.integration.test.ts`, plus the [review] cases in `support-public.integration.test.ts` and `session-mint.integration.test.ts` (★ cases). Each must turn red when its guard is removed:

| Guard | Mutation | Test that must fail |
|---|---|---|
| requester in the thread WHERE (`loadRequesterTicket`) | drop `AND t.requester_customer_id = …` | threads ★ cross-customer 404, ★ impersonation |
| visibility predicate (`read-state/visibility.ts`) | `IN ('inbound','outbound','internal')` | threads ★ note never appears; unread ★ note never counted; tickets ★ preview |
| unread ownership (`customerUnread` / `markPoint`) | drop `requester_customer_id = ${customerId}` / `s.customer_id = …` | unread ★ cross-customer, ★ mark another's ticket/chat 404 |
| project pin (`projectOutOfScope`) | return `false` | threads/unread ★ pinned key 404 |
| read-only (`readOnlyRefusal`) | skip the check | threads ★ deactivated / blocked |
| portal writer requester-only | mark on any visible ticket | unread ★ non-requester no-op |
| path-bound `Idempotency-Key` (`boundRequest`) | pass `rawBody` alone | threads ★ reuse on another ticket; unread ★ another customer; support-public ★ another project / ticket |
| grant check before writes (`resolveRequester`) | check after `ensureProjectGrant` | session-mint ★ no project grant / no customer on 403 |
| commit-ordered `version` (`emitUnreadChanged`) | `version = Date.now()`, no lock | unread ★ racing replies and mark-reads |
| per-customer write budgets (`spend`) | skip `spend` | native-rate-limit ★ 429 + Retry-After |

**Assumptions recorded (requests lane).** (1) The requester is named by `requesterExternalRef` on create (the existing field) and `externalRef` everywhere else; there is no second alias. (2) A mark-read is allowed for blocked/deactivated customers: it is a read position, not a message. (3) An unknown `externalRef` on `GET …/unread` is zeros (the list's "matched no one" rule), never a 404 that would reveal which refs exist. (4) `context` is stored in `custom_fields.context` (an existing JSONB column), so no ticket migration was needed; 0260 is only the read marks. (5) The portal moves the mark when the customer opens the ticket's timeline; the portal UI itself shows no unread state yet.


# Support callbacks: "Request a callback" (/support/callbacks)

{/* GENERATED from docs/support/callbacks.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

A customer asks to be called back from the portal, the chat widget, or your own backend through the API.
The request lands on a ticket, so the desk sees it, and carries a promised time that the project's hours
honour. This discharges ledger rows D207 and D211's route half: Tier 3 is back on the portal and in the Slip.

- Server: `apps/api/src/support/callbacks/`
- Table: `support_callbacks` (migration 0238)
- Types: `packages/types/src/support-callbacks.ts`

## 1. Turning it on [#1-turning-it-on]

A project offers callbacks when **`voice_enabled` OR `callback_enabled`** is true. `callback_enabled` (0238)
turns callbacks on with browser calling off. A sandbox project may turn it on to exercise the integration
(see §5). With both off, every surface shows nothing and the routes answer 409 `callbacks_off`.

## 2. The window and the promise [#2-the-window-and-the-promise]

Every time a customer sees comes from the server, worked out on the project's own clock: the
`SlaClock` from `resolveSlaClock`, the same one behind the ticket SLA and the chat's "we'll reply by".

| Window | Promise (`promisedBy`) | Rules |
|---|---|---|
| `{kind:"asap"}` | 30 **open** minutes from now, or from the next opening when closed | Refused (422 `slot_unavailable`) when no opening is in reach. The server never invents a time. |
| `{kind:"slot", start}` | the slot's end (30 minutes after `start`) | `start` must be on the half hour, ≥ 1 h out, ≤ 7 days, and wholly inside open hours. The server re-checks every slot the client sends. |

`GET …/callbacks/options` returns `{enabled, prefillE164, open, nextOpenAt, timezone, asapBy, slots[≤12], live}`.
The form renders from it alone. Times are shown in the customer's own timezone.

**SLA.** `promisedBy` feeds the ticket's first-response deadline: `sla_first_due_at` becomes the earlier of
the two while nobody has replied. An **answered** callback sets `first_replied_at`, because a phone call is a reply.

## 3. The doors [#3-the-doors]

| Door | Route | Who | Edge limit |
|---|---|---|---|
| Portal (home, `/chat`, a case) | `GET /support/portal/callbacks/options` · `GET /support/portal/callbacks` · `POST /support/portal/callbacks` · `POST /support/portal/callbacks/:id/cancel` | customer session (`CustomerSessionGuard`); deactivated = read-only, blocked = no session | 3 / hour / customer (Redis, before any DB work) |
| Widget (Slip) | `GET /support/chat/:sessionId/callbacks/options` · `POST /support/chat/:sessionId/callbacks` | signed chat token; **`hmac` or `authenticated` only** (anonymous gets 403, and the chunk is never fetched) | 3 / hour / customer |
| API | `POST /v1/support/callbacks` · `GET /v1/support/callbacks` · `GET /v1/support/callbacks/:id` · `POST /v1/support/callbacks/:id/cancel` | API key, `support-tickets:rw` / `:read`; project pins enforced; test keys reach only the sandbox; `Idempotency-Key` on create | key limits |
| Desk | `GET /support/callbacks` · `GET :id` · `POST :id/call-now` · `POST :id/outcome` · `POST :id/cancel` | member session, `support-tickets` view/edit | — |

**Refusals, in this order, before anything is written** (a refused request costs no ticket number):

1. 409 `callbacks_off`: the project offers no callbacks.
2. 403 `customer_inactive`: the customer is blocked or deactivated, or the grant on **this** project is blocked or missing.
3. The customer already has a **live** callback on this project. That one is returned (200), not a second. This is the dedupe every door meets, enforced by a unique index.
4. 429 `daily_cap`: 5 requests per customer per project in 24 h, counted across every door.
5. 422 `slot_unavailable`: the window, per §2.

A live key never reaches a sandbox callback (read, cancel or list): **404**, as for an unknown id. A pinned API key naming another project gets **404**, the same answer as an unknown id, so a pin is never an
existence oracle.

**The ticket.** `ticketId` (portal and API) attaches the callback to the customer's own case. Someone else's
case gets a 404. In the widget, the chat's existing case is reused. Otherwise a case "Callback requested" is opened
through the one creation family (`createFromPortal` / `createFromChat` / `createFromApi`).

## 4. Dispatch: who actually dials [#4-dispatch-who-actually-dials]

Decided server-side per request and stored as `dispatch`:

| `dispatch` | When | What happens |
|---|---|---|
| `voice` | `voice_enabled`, not sandbox, the contact-centre platform on (`PULSE_FLAG_CALLBACKS` + `PULSE_FLAG_CONTACT_CENTRE`) and active for the workspace, a `voice_queues` row whose team is the project's **L1 tier team**, a live line in `support_project_numbers`, and the queue's **number policy** accepts the number | A `voice_callbacks` row is booked (`via 'api'`, `created_by NULL`: "the caller asked", 0152). The **existing** contact-centre dispatcher rings an agent, dials, retries and expires it. The sweep `support.callback_reconcile` (60 s) and every desk read carry its ending back. |
| `manual` | anything else | The agent dials from their own phone (`tel:`) and records the outcome. |
| `sandbox` | sandbox project | **Never dialled.** No voice row is ever booked, the desk offers no Call now and no `tel:`, and outcomes are recorded only to test the integration. |

**The contact centre's caps hold too** ([review]): under one per-number lock, a number already live on the L1 queue,
a number with 3 live callbacks in the workspace, or a queue whose daily cap is spent is not booked again. The callback
stays `manual`, so a typed number (many customers, one victim) is never dialled past the operator's limits.

**The number policy is the operator's.** The contact-centre default is `ani_only`: call back only a number that
called in. A typed number has no inbound call, so on such a queue the callback stays `manual` instead of
overriding the operator. Set the L1 queue to `same_country` or `any` to let Gauge dial typed numbers.

**The seam.** `VoiceModule` does not export `CallbacksService`. The support pillar's `@Global`
`SupportCallbackVoiceSeam` is bound at boot by `voice/callbacks/support-callback-port.ts` (the D198 seam, run in reverse).
With no voice pillar the seam is empty, and every callback is `manual`.

## 5. The desk [#5-the-desk]

A case shows its callbacks above its history. The queue shows the project's **waiting** callbacks above the
rack, soonest promise first, with "Overdue" in words as well as in red.

- **Call now** (voice only): the row becomes the agent's personal callback, and the shipped personal ring dials them
  first. If the agent isn't routable, the refusal says to call from their phone.
- **Call from your phone** (manual only): a `tel:` link.
- **Record what happened**: answered · no answer · busy · voicemail · wrong number, plus an optional note
  (≤ 500). **Retry policy:** answered → completed. Wrong number → failed. A miss → the next try 30 **open**
  minutes later, up to 3 tries, then failed. Recording by hand on a voice row cancels the idle voice row,
  and the callback continues as manual. A call that is ringing right now can't be overwritten (409 `in_progress`).
- **Cancel**: by the customer, an agent or the API. Any of them cancels the voice row too.

## 5a. Events and webhooks [#5a-events-and-webhooks]

`support.callback.requested` · `.scheduled` (a chosen slot, or a retry) · `.completed` · `.failed` · `.cancelled`.
They carry **ids only**: `{version, callbackId, projectId, customerId, ticketId}`. Never the number, the reason or a
note. They are written to the outbox in the same transaction, published in the OpenAPI `webhooks` block, and audience
`members`. Read the callback itself with `GET /v1/support/callbacks/{callbackId}`.

## 6. Privacy [#6-privacy]

`e164`, `reason` and `outcome_note` are REST-only and never logged. `CustomerErasureService` deletes the
customer's callbacks, and the contact-centre rows they booked, except one whose call is ringing at that
moment. The customer FK cascades as well. The PII census lists every text column.

## 7. Bundles [#7-bundles]

The widget arm is a lazy, SRI-pinned chunk, `support/callback.js` (10.2 KB gz, budget 15 KB). The base is
30.9 KB gz (budget 50, +0.9 KB for the strings, the loader and the type roles). `size.mjs` fails the build if the
chunk is inlined. That guard was proven by inlining the chunk.

## 8. What this does not do (recorded, not hidden) [#8-what-this-does-not-do-recorded-not-hidden]

- **The overflow chain's callback arm OFFERS; it never books.** When a browser call's queue overflows on a
  queue configured `callback` (or `voicemail`, which degrades to it), and `SupportCallbacksService.options` says
  this customer could book (project offers callbacks, customer active and granted), overflow records `callback`,
  opens the call's ticket, and closes the room. The caller's status read then carries
  `callbackOffer: { ticketId }`: the portal shows "Nobody could take your call this time. We can call you back
  instead." with its Tier 3 arm booking against that ticket, and the widget call slip opens the callback form
  for it. The booking goes through the normal door (edge limit, daily cap, one live callback, sandbox dispatch).
  Nothing is ever dialled on overflow's say-so: the caller confirms the number. Phone (PSTN) callers and anonymous
  widget visitors have no customer row, so they get no offer and the chain degrades as before. `/chat?embed=1`
  shows the sentence without a key; the native app books through `/v1` (mobile.md), and the
  `support.voice.abandoned` event names the action taken.
- **Browser calls are separate from callbacks.** In-app calls (portal, `/chat?embed=1`, the widget's own
  call key) are LiveKit rooms and need nothing from Twilio (`docs/ops/support-embed.md` §5). Callbacks are
  the PSTN path and stay on Twilio. The widget Slip shows both when the project has both on.
- **Desk reads follow the ticket's data scope (S5).** An own/team-scoped agent sees and works a callback only when its
  ticket passes the `support-tickets` scope predicate (`ticket-scope.ts`): the list and every `:id` route, 404 otherwise.
  There is still no per-project membership, matching `GET /support/tickets`.


# Keeping your users in sync with Gauge Support (/support/customer-sync)

{/* GENERATED from docs/support/customer-sync.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

This is the integrator's guide to the customer **sync** API. It's written for a SaaS backend (Salonvira is the first one) that owns its users and wants Gauge Support to mirror them: who exists, what they can reach, whether they're allowed in, and a few facts agents should see.

All routes are under `/v1/support` and authenticate with `Authorization: Bearer pulse_k_…`. Reads need `support:read`; writes need `support:rw`. A key pinned to projects (`projectIds` at mint) only sees and changes customers in those projects. Everything else returns 404. A test key (`pulse_k_test_`) is always pinned to the workspace's **sandbox** project, so it only sees sandbox customers; a live key never sees a customer whose every grant is on the sandbox (by ref it is a 404, by email a 422 `email_unavailable`), and never reads or reconciles a sandbox grant. Use different test emails and refs from your production ones, or reset the sandbox.

## 1. The key is *your* user id [#1-the-key-is-your-user-id]

Every customer is addressed by **`externalRef`**: your own stable user id, as a string of 1–200 chars. Use the id that never changes. Don't use the email.

| You want to… | Call |
|---|---|
| create or update one user | `PUT /customers/by-ref/{externalRef}` |
| create or update up to 500 users | `POST /customers/sync` |
| look one up | `GET /customers?externalRef=…` or `GET /customers/{id}` |
| deactivate, reactivate or block many | `POST /customers/status` |
| pull every change since time T | `GET /customers?updatedSince=T` |

### Fields you can set [#fields-you-can-set]

| field | meaning |
|---|---|
| `email` | Required to **create**. Changing it on an existing ref moves the identity (see §3). |
| `name`, `locale` | Display name and BCP-47-ish locale (`ar`, `en-GB`). `null` clears. |
| `status` | `active` · `deactivated` (read-only, see §4) · `blocked` (full lockout). |
| `projectIds` | **Authoritative** when present: we add missing grants and revoke extra ones, *within your key's projects*. Omit it to leave access untouched. |
| `metadata` | Your facts, shown to agents (§5). Replaced wholesale when present; omit to leave it. |
| `attrs` | **Verified** attributes your server vouches for (`tier`, `role`, `plan` …). Up to 20 keys, scalar values (string ≤120, number, boolean). Agents cannot edit them; SLA by tier reads `attrs.tier` when the customer has no organization tier. Replaced wholesale when present. GDPR erase clears them. |
| `organization` | The customer's company: `{"externalRef":"acc-42","name":"Acme","tier":"enterprise"}`. Upserted by your account id; `tier` (lower-cased slug) picks the customer's SLA policy (Team → SLA & escalation). Omit `tier` to keep the stored one, `null` to clear it. `"organization": null` removes the customer from it. A customer has one synced organization; naming another replaces it. A project-pinned key can create or join an organization but needs a workspace-wide key to change an existing one's name or tier (`forbidden`). Membership never merges people and never widens what a customer sees in the portal. |

## 2. Batch sync: `POST /customers/sync` [#2-batch-sync-post-customerssync]

```json
{ "customers": [
  { "externalRef": "u_1029", "email": "layla@example.com", "name": "Layla", "locale": "ar",
    "projectIds": ["<project uuid>"], "metadata": { "plan": "pro", "branch": "Riyadh" } },
  { "externalRef": "u_2210", "status": "deactivated" }
] }
```

- Up to **500 items** per call. Each `externalRef` may appear only once per call.
- **Each item stands alone.** One bad row never fails the batch. You get a result per item, in order:

```json
{ "runId": "…", "counts": { "created": 1, "updated": 0, "unchanged": 1, "error": 0 },
  "results": [
    { "externalRef": "u_1029", "customerId": "…", "outcome": "created",   "error": null },
    { "externalRef": "u_2210", "customerId": "…", "outcome": "unchanged", "error": null }
  ] }
```

- **Outcomes:**
  - `created`: a new customer.
  - `updated`: something changed.
  - `unchanged`: nothing differed. Nothing is written, no event fires, and the cursor doesn't move.
  - `error`: see `error.code`.
- **Idempotent twice over.** Re-sending the same batch converges to `unchanged`. If you also send an `Idempotency-Key` header (recommended for scheduled jobs), a retry with the same key and body replays the first response exactly. Reusing the key with a different body returns 409.
- **Audit trail.** Every call writes one `support_customer_sync_runs` row: who ran it, the counts, and per-item ids, outcomes and error codes. It never stores an email, a name or a metadata value.

### Per-item error codes (stable; branch on these) [#per-item-error-codes-stable-branch-on-these]

| code | why | what to do |
|---|---|---|
| `email_required` | unknown `externalRef` and no `email` | send the email to create |
| `email_in_use` | that email belongs to a customer with a **different** `externalRef` | see §3; we never merge two of your users |
| `email_unavailable` | (**project-pinned keys only**, instead of `email_in_use`) the address can't be used with this key. It is `422` like `email_required`, and it never says whether the address is held or by which project | use another address, or resolve it with a workspace-wide key |
| `project_not_found` | a `projectIds` entry isn't a project this key may use | fix the id, or the key's pin |
| `forbidden` | a project-pinned key tried to change the email of a customer that **another** project also serves, or to set such a customer back to `active` (erase is refused the same way, 403) | do it with a workspace-wide key |
| `metadata_too_large` | `metadata` is over 8 KB as stored (see §5). On `PUT`/`PATCH` it is `400` with `error.code: "validation_failed"`, `error.reason: "metadata_too_large"` | trim the metadata; the batch's other items are unaffected |

**Pinned keys and shared customers.** Suppose a project-pinned key sets `status: blocked` or `deactivated` on a customer that another project also serves. The customer's status does not change, because it applies to every project. Instead, the customer loses access to **your** projects: grants and the portal sessions on them are revoked. The item answers `updated` with `scope: "project"`. After that, the customer is outside your key's projects, so it reads as 404.
| `not_found` | (status batch) unknown ref/id, or outside your key's projects | — |
| `internal` | unexpected failure for that item | retry the item |

`PUT /customers/by-ref/{ref}` follows the same rules for a single user. It answers `201 {outcome:"created"}` or `200 {outcome:"updated"|"unchanged"}`, plus the record. An item error becomes the HTTP status (`422 email_required`, `409 email_in_use`, or `422 email_unavailable` for a pinned key, `404`), with the code in `error.reason`. `POST /customers`, a ticket's `requesterEmail` and a session link answer a pinned key the same `422 email_unavailable`.

## 3. Conflict rules [#3-conflict-rules]

1. **`externalRef` wins.** If the ref is known, we update that customer, whatever the email says.
2. **Email change on a known ref.** The address and its identity move to the new email. Email verification is **reset**, so the customer proves the new address the first time they sign in by magic link. Tickets and history stay with the customer. If the new email already belongs to another customer, the item fails with `email_in_use`.
3. **New ref with an email we already know:**
   - **without** an `externalRef` (they signed up through the portal, or you created them by email): we **adopt** them. Your ref is attached and the outcome is `updated`.
   - **with a different** `externalRef`: `email_in_use`. Two of your users are never merged. Fix the duplicate on your side, or change one user's email first.
4. **Concurrency.** Writes to one `externalRef` are serialized server-side, so two jobs syncing the same user can't create two customers.

## 4. Status: active, deactivated, blocked [#4-status-active-deactivated-blocked]

| status | portal | new ticket / chat / escalation / emailed thread | live sessions |
|---|---|---|---|
| `active` | full | allowed | kept |
| `deactivated` | **read-only**: sees existing tickets, can't reply, upload, rate or call | **refused** | kept (read-only) |
| `blocked` | none | **refused** | **revoked immediately**, including open sockets |

Moving to `active` again (from either state) reverses it. Each change fires a webhook to the customer's projects: `support.customer.deactivated`, `support.customer.blocked` or `support.customer.unblocked`. Use `POST /customers/status` to change many at once:

```json
{ "status": "deactivated", "externalRefs": ["u_2210", "u_3301"] }
```

Use `POST /customers/{id}/sessions/revoke` to sign someone out everywhere without changing their status.

## 5. Metadata [#5-metadata]

A **flat** object of your own facts, shown to agents next to the customer's tickets: `plan`, `tier`, `branch`, `salonId` and so on.

- Up to 50 keys. Keys match `[A-Za-z0-9_.-]`, max 64 chars.
- Values are a string (≤500 chars), number, boolean, `null`, or an array of up to 50 scalars.
- At most **8 KB** as stored. That is the database's JSON text form, which puts a space after every `:` and `,`, so it is a little larger than compact JSON. Allow about 2 bytes per key and array element. Over the limit the item answers `metadata_too_large`, and the rest of the batch still applies.
- Text values cannot contain the NUL character (`\u0000`) or unpaired UTF-16 surrogates. The database cannot store them, so the request is a `400 validation_failed`.
- **Don't** put secrets, payment data, health data or anything regulated in it. It's visible to every agent with access to support. GDPR erase clears it.
- A change fires `support.customer.updated` with `fields: ["metadata"]`. The values themselves are never sent on webhooks.

## 6. The nightly reconcile [#6-the-nightly-reconcile]

The batch sync pushes your changes to us. The reconcile read lets you **verify** them and pick up changes made on our side (an agent blocks someone, a customer is erased, access is revoked in the console):

```
GET /v1/support/customers?updatedSince=2026-10-09T00:00:00Z&limit=500
→ { "rows": [ … ], "nextCursor": "…" | null, "highWatermark": "2026-10-10T02:14:07.123456Z" }
```

- Rows come back in **ascending `updatedAt`, then id** order, at most 500 per page.
- `updatedAt` moves on **every** change to a field in the record, including a project grant or revoke and an erasure. It's maintained by the database, so no writer can forget it. Changes we keep internally, such as linking the customer to a CRM contact, don't move it, so they don't wake your reconcile.
- Follow `nextCursor` until it's `null`. The cursor is opaque and microsecond-exact, so a page boundary never skips or repeats a row. A malformed cursor returns 400, not a silent restart.

**The algorithm:**

1. Load `W`, the watermark you stored last time (on the first run, use your epoch).
2. Call `GET /customers?updatedSince=W − 5 minutes&limit=500` and follow `nextCursor` to the end. The 5-minute overlap covers clock skew and in-flight writes. Overlapping rows simply compare equal.
3. For each row, compare with your user `externalRef`. Repair whichever side is wrong (usually by putting the item in your next `POST /customers/sync`).
4. Store the final page's `highWatermark` as the new `W` **only after** step 3 succeeds. Store it exactly as returned, and don't subtract the overlap before you store it. The 5 minutes come off at read time, in step 2. On a page with rows, `highWatermark` is the last row's `updatedAt`. On an **empty** page, it's our clock when the query started, and never earlier than your `updatedSince`. So a quiet night still moves `W` forward, and repeated empty runs don't drift it backwards.
5. Push your own changes with `POST /customers/sync` (with an `Idempotency-Key` per batch) and check every `error` result.

If a run crashes, nothing is lost: you resume from the old `W`.

## 7. Webhooks you'll want [#7-webhooks-youll-want]

Subscribe your endpoint to `support.customer.*`. Every body carries a stable `id` (the event id). It stays the same across retries and resends, so dedupe on it. Reject a request whose `x-pulse-timestamp` is more than **5 minutes** from your clock. Signature details are in the OpenAPI document (`GET /openapi.json`).


# Support API (/support)

<Status is="live" />

The Support API lets a software company give **its own customers** support inside its product,
answered by its team in Gauge. Your backend keeps Gauge in step with your users; your app opens the
chat already signed in; Gauge sends events back to your server.

It lives on `/v1/support` and uses the same [API keys](/authentication) with the `support:read` and
`support:rw` scopes. A key can be pinned to one **App** (a support project), and a test key reaches
only the sandbox App.

## Start here [#start-here]

<Cards>
  <Card title="Quick start" href="/support/quickstart">
    Provision users, embed the widget or portal, and receive verified webhooks, in about 15 minutes.
  </Card>
  <Card title="Web app" href="/support/quickstart-web-app">
    Chat for signed-in users in your website or web app.
  </Card>
  <Card title="Mobile app (WebView)" href="/support/quickstart-webview">
    Chat inside your iOS, Android, Flutter or React Native app.
  </Card>
  <Card title="API only" href="/support/quickstart-api">
    Your backend provisions users and mints sign-in links. No widget.
  </Card>
</Cards>

Per framework: [Next.js, Express, Django, Laravel, Rails and Go](/support/quickstarts).

## Guides [#guides]

| Guide | |
| --- | --- |
| [Signed integration tokens](/support/integration-token) | Tell Gauge who your user is and which Integration they are on |
| [Keeping users in sync](/support/customer-sync) | Provision, update, deactivate and grant access |
| [Callbacks](/support/callbacks) | "Request a callback" from the portal, widget or your backend |
| [Native Help & Support screens](/support/native-screens) | Build your app's own support screens on Gauge data |
| [Native apps](/support/mobile) | Live chat in a WebView, and push on reply |
| [WebView recipes](/support/webview-recipes) | Copy-paste screens for React Native, iOS and Android |
| [The API core (S1)](/support/api-s1) | The full route-by-route reference for the support embed |

The events these send are in the [event catalogue](/webhooks/events#support-events).


# Signed integration tokens (/support/integration-token)

{/* GENERATED from docs/support/integration-token.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

An **integration token** tells Gauge who your user is and which **Integration** of your App they are
on (for example `customer` or `salon`). Your server mints it; the widget, WebView or portal passes it
on. Gauge verifies it on every session open.

Use it instead of the older `identityHash` for anything new. `identityHash` keeps working, but only on
your App's default integration, and it never unlocks actions that read a customer's data (order
lookups, payouts). A token does.

## Mint one (your server) [#mint-one-your-server]

Node (`npm install @gauge/support`):

```js snippet=mint
import { mintIntegrationToken } from '@gauge/support';

const token = await mintIntegrationToken(process.env.GAUGE_IDENTITY_SECRET, {
  appId: process.env.GAUGE_APP_ID, // Console → Apps → your App → Install
  userId: 'u_1029',                // YOUR user id
  integration: 'customer',         // the Integration key
  attrs: { plan: 'pro' },          // optional, verified attributes
});
```

Python (`pip install gauge-support`):

```python snippet=mint
import os
from gauge_support import mint_integration_token

token = mint_integration_token(
    os.environ["GAUGE_IDENTITY_SECRET"],
    app_id=os.environ["GAUGE_APP_ID"],
    user_id="u_1029",
    integration="customer",
    attrs={"plan": "pro"},
)
```

Never send the secret to a browser or ship it in an app. Mint a new token for every session open.

## What is inside [#what-is-inside]

A compact JWT: header `{"alg":"HS256","typ":"JWT"}`, HMAC-SHA256 with a **token key derived from** your
App's identity secret: `tokenKey = hex(HMAC-SHA256(key = "gauge.integration-token.v1", message = secret))`
(lowercase hex, used as the HS256 secret). The SDK helpers do this for you; with another JWT library, pass
`integrationTokenKey(secret)` / `integration_token_key(secret)` as its secret. Never sign with the raw
identity secret: a token signed that way is refused (`bad_signature`), because an `identityHash` your
server hands out is an HMAC under that same secret.

| Claim | Meaning |
|---|---|
| `iss` | Your App id |
| `sub` | Your user id. Gauge keys the conversation and the customer record on it |
| `key` | The Integration key (`^[a-z][a-z0-9_]{0,31}$`) |
| `attrs` | Optional. Up to 16 flat values (string ≤ 200, number, boolean). Assistant rules and SLA tiers read them, and only from a verified token |
| `name`, `email` | Optional, shown to your team |
| `iat`, `exp` | Epoch seconds. `exp - iat` ≤ 600 |
| `jti` | Single-use nonce (≤ 128 chars). The SDK helpers set a random one for every token. See [Replay](#replay-one-token-one-session-open) |

Rules Gauge applies, in this order: `alg` must be HS256 · signature (current secret, or the previous
one while a rotation overlap is open) · no unknown claims · life ≤ 600 s · not expired (60 s grace) ·
`iat` not in the future (60 s grace) · `iss` is this App · `key` is the integration being opened ·
the user is granted that integration · `jti` not used before.

### Replay: one token, one session open [#replay-one-token-one-session-open]

A token is a bearer credential for up to 10 minutes. So that a copied token (a log line, a proxy, a
browser extension) can't open a **verified** chat as your user and reach their orders or payouts, a token
that carries a `jti` is **single-use**: the first session open consumes it, and any later open with the
same token (from any browser) is refused with `token_replayed`. Gauge only consumes a `jti` after the
signature checks out, so a forged token can't burn one of yours.

- `mintIntegrationToken` (JS) and `mint_integration_token` (Python) always add a random `jti` (pass your
  own with `jti` if you need to correlate). The console's **Test as …** tokens carry one too.
- In the widget, use `getToken` (it fetches a fresh token on every open and re-open). A static `token`
  works once: the widget's later re-reads with the same token are refused and it keeps the session it
  already has, but a page that re-initialises with the same token will not reopen.
- **Backward compatibility during P1:** a token **without** `jti` (hand-signed with another JWT library)
  is still accepted and is not replay-checked. Add a random `jti` now; a later release will require it.

## Why a token was refused [#why-a-token-was-refused]

The error message starts with the code. The console's **Token checker** (Developers → Support)
decodes a pasted token and tells you which rule failed. It never shows the secret or the user's data.

| Code | HTTP | Fix |
|---|---|---|
| `malformed` | 401 | Not a JWT, or a claim Gauge doesn't know. Use the SDK helper |
| `bad_alg` | 401 | Header must be `{"alg":"HS256","typ":"JWT"}` |
| `bad_signature` | 401 | Wrong secret, or the token was edited. Re-sign after rotating |
| `expired` | 401 | Mint a new token per session open |
| `not_yet_valid` | 401 | Your server clock is ahead. Sync it (NTP) |
| `too_long` | 401 | Keep `exp - iat` at 600 s or less |
| `wrong_app` | 401 | `iss` is another App's id |
| `wrong_key` | 401 | The token names a different integration than the one being opened |
| `revoked` | 401 | The user's grants changed after the token was minted. Mint again |
| `token_replayed` | 401 | This token (its `jti`) already opened a session. Mint a fresh token per open (`getToken`) |
| `unknown_integration` | 404 | No integration with that key on the App |
| `integration_not_granted` | 403 | The user isn't granted that integration. Add it with customer sync |
| `sandbox_only` | 401 | A console test token was used on a live integration |

## Grants [#grants]

On an App with more than one integration, a user may open only the integrations listed for them:

```json
PUT /v1/support/customers/by-ref/u_1029
{ "email": "layla@example.com", "projectIds": ["<appId>"], "integrationKeys": { "<appId>": ["customer"] } }
```

An empty list means the default integration only. Removing a key ends the user's live chats on it
at their next message, and refuses tokens minted before the change. A user Gauge has never seen
(no customer record) is bound by the `key` your server signed.

## Rotating the secret [#rotating-the-secret]

Generate a new secret in the console. The old one keeps verifying during the overlap window, so
roll your servers onto the new one inside it.

## Testing [#testing]

`verifyIntegrationToken` (JS) and `verify_integration_token` (Python) apply the same rules and return
the same codes, which is handy in your own tests. Both SDKs pass the shared vectors in
`packages/sdk-testvectors/integration-token.json`, which the Gauge server generates. In the console,
**Test as &lt;integration>** mints a token for draft and sandbox integrations only.


# Support in a native app: live chat in a WebView, and push on reply (/support/mobile)

{/* GENERATED from docs/support/mobile.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

1. **Open the live support chat inside the app**, signed in as the app's own user, with no login screen.
2. **Know when the support team replies**, so the app can send a push notification.

Machine truth lives in `GET /openapi.json`: the `/v1/support/sessions` operation, and the `webhooks` block for `support.chat.message_created` and `support.ticket.replied`. The zod sources are `packages/types/src/support-session-links.ts`, `support-portal-chat.ts` and `events.ts`. The S1 API core is in [api-s1.md](/support/api-s1).

---

## 1. How it fits together [#1-how-it-fits-together]

```
 App (user taps "Chat")
   │  1. "open support chat for me"            (your app ↔ YOUR backend, your own auth)
   ▼
 Your backend
   │  2. POST /v1/support/sessions  target: "chat"   (Gauge API key, server-side ONLY)
   ▼
 Gauge  →  { url, expiresAt }   a single-use link, valid ≤ 15 minutes
   │  3. your backend returns the url to the app; the app appends &embed=1
   ▼
 WebView opens  https://<your-portal-host>/auth/handoff?token=…&embed=1
   │  4. the portal spends the token once, sets its session cookie, lands on /chat?embed=1
   ▼
 Live chat, as that customer, with no login. Replies are read over HTTPS, files are sent from the
 native picker, and it works in Arabic/RTL.

 Agent replies ──► webhook support.chat.message_created (ids only) ──► your backend ──► FCM / APNs
                                                    user taps the push ──► back to step 1
```

**The API key never leaves your backend.** The app asks *your* backend for a link, authenticated however your app already authenticates its users, and your backend mints one. A key embedded in an app binary is a key anyone can extract, and with it they can mint a sign-in for any of your customers.

---

## 2. Mint a chat link (your backend) [#2-mint-a-chat-link-your-backend]

```http
POST /v1/support/sessions
Authorization: Bearer pulse_k_live_…          # needs support:rw + support-sessions:rw
Content-Type: application/json

{
  "projectId": "<your support project id>",
  "externalRef": "user_8812",                  # YOUR id for this person
  "email": "layla@example.com",                # needed only the first time we see this ref
  "name": "Layla Haddad",
  "target": "chat"
}
```

```json
201 { "url": "https://help.salonvira.com/auth/handoff?token=…", "expiresAt": "2026-10-14T16:45:00.000Z" }
```

- **Targets.** `chat` opens the live chat. `ticket:<ticketId>` opens one request. `portal` opens the request list. `chat` is matched exactly: `chat:x` or `chats` is a 400.
- **The link is a one-time sign-in.** It expires in at most 15 minutes (`ttlSeconds` ≤ 900, default 900), and `use: "multi"` is a 400. **Mint a fresh link every time the user opens the chat.** Never cache one, never put one in a push payload, and never log it: it is a bearer credential until it is spent.
- **Embed mode.** Append `&embed=1` to the url before loading it. The portal then renders the chat without its own header and footer, edge to edge, padded by the device's safe-area insets. Your app draws its own title bar and back button.
- **Not idempotent, by design.** Each call mints a new single-use link, so don't retry a mint with an `Idempotency-Key`.
- **Identity.** A customer opened this way is in **`authenticated`** mode, even when your web widget uses `hmac_verified`. The portal session is the proof.
- **Blocked and deactivated customers.** A **blocked** customer's link signs nobody in: every session check refuses a blocked customer, so the WebView shows "Your sign-in has ended". A **deactivated** customer is signed in read-only, and the chat page tells them "Chat isn't available on this account". Don't rely on the mint itself to refuse a blocked customer; check your own user's state before you ask for a link.

Node (your server):

```js
async function chatLinkFor(user) {
  const res = await fetch(`${GAUGE_API}/v1/support/sessions`, {
    method: 'POST',
    headers: { authorization: `Bearer ${process.env.GAUGE_SUPPORT_KEY}`, 'content-type': 'application/json' },
    body: JSON.stringify({ projectId: SUPPORT_PROJECT_ID, externalRef: user.id, email: user.email, name: user.name, target: 'chat' }),
  });
  if (!res.ok) throw new Error(`support link: ${res.status}`);
  const { url } = await res.json();
  return `${url}&embed=1`;
}
```

---

## 3. The WebView [#3-the-webview]

> Shortcut: `gauge_support_webview` (Flutter) and the copy-paste
> screens in [webview-recipes.md](/support/webview-recipes) (React Native, iOS, Android) apply every rule below.

The chat is an ordinary HTTPS page on **your portal host**. Its session cookie is **first-party** (the page is the top-level document) and **host-only** (no `Domain`). So:

- **JavaScript must be on.**
- **Third-party cookies are not needed. Leave them off.** The page never relies on a cookie from another site.
- **Keep navigation on your portal host.** Open any other link in the system browser.
- **File upload uses the native picker.** The page asks for `image/jpeg, image/png, image/webp, image/gif, image/heic, image/heif, application/pdf`, one file at a time, at most 7 MB. On a phone that opens the camera and photo-library sheet.
- **Keyboard.** The page keeps its composer on the keyboard's top edge by itself. It uses `interactive-widget=resizes-content` on Android, and sizes itself to the visual viewport on iOS. Let your WebView resize with the keyboard (below) and don't add your own keyboard padding.

### 3.1 In-app support calls (microphone) [#31-in-app-support-calls-microphone]

When the project has voice on, the chat page shows a **Call support** key. The call runs in the WebView
over WebRTC (LiveKit), so the WebView must be allowed to use the **microphone**. Without it the page says
"Microphone access is blocked" and the customer can still message. You need nothing from Twilio.

- **Android:** declare `<uses-permission android:name="android.permission.RECORD_AUDIO" />` (and
  `MODIFY_AUDIO_SETTINGS`), ask for `RECORD_AUDIO` at runtime before opening the chat, and grant the page's
  request in `WebChromeClient.onPermissionRequest`. Grant **only** `PermissionRequest.RESOURCE_AUDIO_CAPTURE`,
  and only when `request.origin` is your portal host. Otherwise call `request.deny()`.
- **iOS:** add `NSMicrophoneUsageDescription` to `Info.plist` (WKWebView refuses the microphone without it),
  and set `allowsInlineMediaPlayback = true` on the `WKWebViewConfiguration`. Otherwise the agent's audio
  tries to open full screen. On iOS 15+, return `.grant` from
  `webView(_:requestMediaCapturePermissionFor:initiatedByFrame:type:decisionHandler:)` for your portal host
  and `.microphone` only.
- **Flutter:** `webview_flutter_android` → `setOnPlatformPermissionRequest` and grant
  `WebViewPermissionResourceType.microphone`. With `flutter_inappwebview`, return
  `PermissionResponseAction.GRANT` from `onPermissionRequest` for `PermissionResourceType.MICROPHONE`,
  and set `mediaPlaybackRequiresUserGesture: false` and `allowsInlineMediaPlayback: true`.
- **React Native:** `react-native-webview` needs `allowsInlineMediaPlayback` and
  `mediaPlaybackRequiresUserGesture={false}`, and on iOS 15+ `mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"`.
  Request `RECORD_AUDIO` with `PermissionsAndroid` before opening the chat on Android.

The page asks for the microphone only when the customer presses Call, never on load.

### Flutter: `webview_flutter` (4.x) [#flutter-webview_flutter-4x]

```dart
import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_android/webview_flutter_android.dart';
import 'package:file_picker/file_picker.dart';
import 'package:url_launcher/url_launcher.dart';

const portalHost = 'help.salonvira.com';

WebViewController supportChat(String link, {required VoidCallback onSignedOut}) {
  final controller = WebViewController()
    ..setJavaScriptMode(JavaScriptMode.unrestricted)
    ..setNavigationDelegate(NavigationDelegate(
      onNavigationRequest: (request) {
        final uri = Uri.parse(request.url);
        if (uri.host != portalHost) {
          launchUrl(uri, mode: LaunchMode.externalApplication);   // never inside the chat
          return NavigationDecision.prevent;
        }
        if (uri.path == '/logout/done') onSignedOut();            // see §5
        return NavigationDecision.navigate;
      },
    ))
    ..loadRequest(Uri.parse(link));

  // Android only: route <input type="file"> to the native picker (iOS does this by itself).
  final platform = controller.platform;
  if (platform is AndroidWebViewController) {
    platform.setOnShowFileSelector((params) async {
      final picked = await FilePicker.platform.pickFiles(
        type: FileType.custom,
        allowedExtensions: ['jpg', 'jpeg', 'png', 'webp', 'gif', 'heic', 'heif', 'pdf'],
      );
      final path = picked?.files.single.path;
      return path == null ? <String>[] : [Uri.file(path).toString()];
    });
  }
  return controller;
}

// The screen: let the WebView resize with the keyboard.
Scaffold(resizeToAvoidBottomInset: true, appBar: AppBar(title: const Text('Support')),
         body: WebViewWidget(controller: controller));
```

### Flutter: `flutter_inappwebview` (6.x) [#flutter-flutter_inappwebview-6x]

```dart
InAppWebView(
  initialUrlRequest: URLRequest(url: WebUri(link)),
  initialSettings: InAppWebViewSettings(
    javaScriptEnabled: true,
    thirdPartyCookiesEnabled: false,            // first-party cookie only — see above
    supportMultipleWindows: false,
    javaScriptCanOpenWindowsAutomatically: false,
    allowsInlineMediaPlayback: true,
    useHybridComposition: true,                 // Android: correct keyboard + input behaviour
    isFraudulentWebsiteWarningEnabled: true,
  ),
  shouldOverrideUrlLoading: (controller, action) async {
    final uri = action.request.url!;
    if (uri.host != portalHost) {
      await launchUrl(uri, mode: LaunchMode.externalApplication);
      return NavigationActionPolicy.CANCEL;
    }
    if (uri.path == '/logout/done') onSignedOut();
    return NavigationActionPolicy.ALLOW;
  },
)
```

`flutter_inappwebview` handles `<input type="file">` on both platforms.

### Platform settings (both Flutter packages) [#platform-settings-both-flutter-packages]

- **Android `AndroidManifest.xml`:** `android:windowSoftInputMode="adjustResize"` on the activity, plus `CAMERA` / `READ_MEDIA_IMAGES` if the picker should offer the camera.
- **iOS `Info.plist`:** `NSCameraUsageDescription` and `NSPhotoLibraryUsageDescription`. WKWebView refuses to open the camera or library without them. For in-app calls, also `NSMicrophoneUsageDescription` (§3.1).

### React Native: `react-native-webview` [#react-native-react-native-webview]

```jsx
<WebView
  source={{ uri: link }}
  javaScriptEnabled
  thirdPartyCookiesEnabled={false}
  setSupportMultipleWindows={false}
  allowsInlineMediaPlayback
  originWhitelist={[`https://${portalHost}`]}
  onShouldStartLoadWithRequest={(req) => {
    const { host, pathname } = new URL(req.url);
    if (host !== portalHost) { Linking.openURL(req.url); return false; }
    if (pathname === '/logout/done') onSignedOut();
    return true;
  }}
/>
```

File inputs work on both platforms. On Android, request camera and media permissions first if you want the camera offered. Use `android:windowSoftInputMode="adjustResize"`, and don't wrap the WebView in a `KeyboardAvoidingView`: the page already handles the keyboard.

### Native iOS: `WKWebView` [#native-ios-wkwebview]

- Use `WKWebsiteDataStore.default()` to keep the session across launches, or `.nonPersistent()` to sign in again (with a fresh link) on every open.
- In `webView(_:decidePolicyFor:)`, allow only your portal host and send everything else to `UIApplication.shared.open`.
- `<input type="file">` presents the system picker. Add the two `Info.plist` keys above.
- Leave `contentInsetAdjustmentBehavior` at its default. The page pads itself by `env(safe-area-inset-*)`.

### Native Android: `WebView` [#native-android-webview]

- Set `settings.javaScriptEnabled = true` and `settings.domStorageEnabled = true`. `CookieManager.setAcceptCookie(true)` is the default. Leave `setAcceptThirdPartyCookies` **off**.
- Implement `WebChromeClient.onShowFileChooser` with an `ActivityResultLauncher` (`ACTION_GET_CONTENT`, the MIME types above) and pass the result to the callback.
- Use `WebViewClient.shouldOverrideUrlLoading` to keep navigation on your portal host.
- Activity: `android:windowSoftInputMode="adjustResize"`.
- For in-app calls: `RECORD_AUDIO` in the manifest and at runtime, and grant `RESOURCE_AUDIO_CAPTURE` for your portal host in `WebChromeClient.onPermissionRequest` (§3.1).

---

## 4. Push notifications on reply [#4-push-notifications-on-reply]

Gauge never sends a push to your users. Your backend gets a signed webhook and sends the push through FCM or APNs. Every payload carries **ids only**: no message text, name or email ever leaves Gauge on this path.

**Subscribe** a webhook endpoint (console → Developers → Webhooks) to:

| Event | When | Push it when |
|---|---|---|
| `support.chat.message_created` | a message lands in a live chat: from a team member (`member`), the AI agent (`ai`), an automation or API send (`system`), or the customer (`customer`) | `payload.authorType !== "customer"` |
| `support.ticket.replied` | a reply is added to a request | `payload.replyVisibility === "public"` and `payload.authorType === "member"` |

A delivery body (`support.chat.message_created`):

```json
{
  "id": "4b1f6c1e-…",
  "event": "support.chat.message_created",
  "workspaceId": "…",
  "entity": "message",
  "entityId": "<messageId>",
  "occurredAt": "2026-10-14T16:24:00.000Z",
  "payload": {
    "version": 1,
    "sessionId": "…",
    "projectId": "…",
    "conversationId": "…",
    "messageId": "…",
    "authorType": "member",
    "customerId": "…",
    "externalRef": "user_8812"
  }
}
```

- **`externalRef` is your own user id.** It is the customer's `external` identity, or the hmac-verified id your web widget opened with. It is `null` for an anonymous web visitor, who has no phone to push to. `customerId` is Gauge's id for the same person.
- `support.ticket.replied` now carries `requesterCustomerId` and `externalRef` too. This is a minor, backwards-compatible change: both are always sent, and either may be `null`.

**Verify, then dedupe.** Each delivery has `x-pulse-signature: sha256=<hex>`, an HMAC-SHA256 of `<x-pulse-timestamp>.<raw body>` keyed with the endpoint secret. The timestamp is epoch **milliseconds**; reject anything more than 5 minutes from your clock. During a secret rotation there are two signatures, separated by a comma, and either may match. Retries and manual resends carry the **same envelope `id`**. Store it and drop a delivery whose `id` you have already handled, so a user is never pushed twice for one reply.

**Send the push.** Look up the devices for `externalRef` and send a **data** message, with a body you write yourself. The webhook carries no message text, by design.

FCM (HTTP v1):

```json
{
  "message": {
    "token": "<device token>",
    "notification": { "title": "Salonvira Support", "body": "You have a new reply" },
    "data": { "kind": "support_chat", "sessionId": "…", "messageId": "…" },
    "android": { "collapse_key": "support_chat", "priority": "HIGH" }
  }
}
```

APNs:

```json
{
  "aps": { "alert": { "title": "Salonvira Support", "body": "You have a new reply" }, "thread-id": "support_chat", "sound": "default" },
  "kind": "support_chat",
  "sessionId": "…"
}
```

For `support.ticket.replied`, use `"kind": "support_ticket", "ticketId": "…"`.

**On tap**, deep-link into the app (for example `salonvira://support/chat`). The app then asks your backend for a **fresh** link (§2): `target: "chat"` for a chat push, `target: "ticket:<ticketId>"` for a ticket push. Never put a session link in the push itself. It would expire before most taps, and it is a sign-in credential sitting in a notification store.

---

## 5. Sessions, cookies and sign-out [#5-sessions-cookies-and-sign-out]

| Thing | Value |
|---|---|
| Minted link | single-use, ≤ 15 min, spent atomically: a second open of the same url is refused |
| Portal session cookie | `pulse_support_session`, `HttpOnly; Secure; SameSite=Lax; Path=/`, **no `Domain`**, so it belongs to your portal host only |
| Idle expiry | 30 days, sliding (each request extends it) |
| Absolute expiry | 90 days from sign-in, whatever the activity |
| Ends early when | the customer is blocked, their project access is revoked, or `POST /v1/support/customers/:id/sessions/revoke` is called. The next request or poll sees it. |

**When your user signs out of the app**, also end the support session. Clearing the WebView's cookie jar alone leaves the server-side session valid until it expires.

1. Load `https://<your-portal-host>/logout?embed=1` in the same WebView, so it carries the same cookie jar.
2. The page revokes the session on the server, which also clears the cookie and drops any live connection, then navigates to **`/logout/done`**.
3. When your navigation callback sees `/logout/done`, close the WebView, and clear its cookie jar too.

If the revoke fails (the device is offline, say), the page stays on `/logout`, says so, and offers a retry. It never shows "signed out" while the session is still live.

**Loading the page doesn't sign anyone out by itself.** The page's own script sends the sign-out as a same-origin `POST`, and it does that on load only when the browser reports the navigation as the app's own (`Sec-Fetch-Site: none`, which is what `loadUrl` / `load(URLRequest)` sends) or as coming from the portal itself (`same-origin`). If another site sends the browser to `/logout`, the page shows a **Sign out** button and revokes nothing until the user presses it. The API also refuses a sign-out `POST` from any other origin. In practice:

- Load `/logout` **directly** in the WebView. Don't reach it through a redirect from your own domain, because the browser then reports the navigation as cross-site and the user has to press the button.
- WebViews too old to send `Sec-Fetch-Site` (Android System WebView before 76, iOS before 16.4) also get the button, so the flow still works with one tap.

---

## 6. What the chat page does on its own [#6-what-the-chat-page-does-on-its-own]

- **Replies arrive over HTTPS, not a socket.** A WebView is suspended whenever the app goes to the background, and a socket dies with it. The page re-reads the conversation when it opens, whenever it returns to the foreground or comes back online, and every 4 s while it is visible. It never polls in the background or while offline.
- **Messages typed offline** wait in the page and go out when the network returns. Each keeps its id and timestamp, so a retry lands exactly once.
- **What it says.** "You're next." / "N people are ahead of you." come from the server's own count. "We're closed right now. Leave a message and we'll reply by Thu 1:00 PM." comes from your project's hours and SLA. "This chat is now request #1042." appears when an agent turns the chat into a request.
- **What it does not show:** an agent-typing indicator. That signal only exists on the web widget's socket, and the page will not invent one.
- **Arabic.** When the customer's saved locale (or the project default) is Arabic, the whole page is in Arabic and right-to-left, including plurals and times.
- **Rate limits** (per customer): 60 chat opens an hour, 120 transcript reads a minute, and 10 file uploads an hour (shared with request attachments).
- **"Request a callback" is not drawn inside the embedded page** (`embed=1`). Inside the web widget that key
  belongs to the Slip, and two keys for one request is a duplicate. In a native app, offer it from your own UI:
  your backend calls `POST /v1/support/callbacks` with the customer id and the number. The response carries
  `promisedBy` (the time to show), and `support.callback.completed|failed|cancelled` webhooks tell you how it
  ended. See [callbacks.md](/support/callbacks).

---

## 7. Security checklist [#7-security-checklist]

- [ ] The Gauge API key lives only on your backend, scoped to `support:rw` + `support-sessions:rw`, and pinned to your support project (`projectIds`).
- [ ] Your backend mints a link only for the user your app has authenticated. A link signs that person in.
- [ ] A link is minted per open, never cached, never logged, never sent in a push.
- [ ] The WebView allows only your portal host and has no JavaScript bridge (`addJavascriptInterface` / `JavascriptChannel`) exposed to it.
- [ ] Third-party cookies are off. HTTPS only.
- [ ] Webhooks are signature-checked, held to a 5-minute window, and deduped on envelope `id`.
- [ ] Sign-out loads `/logout` in the WebView before clearing its jar.


# Native Help & Support screens (/support/native-screens)

{/* GENERATED from docs/support/native-screens.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

How a native app (iOS, Android, Flutter, React Native) builds its Help & Support screens on Gauge. The rule
for every section: **Gauge is the source of truth.** Hours, staffing and who answers are configured in the
Gauge console. Your app reads them through your backend and stores none of it.

Your backend holds the API key (`pulse_k_live_…`). The app talks to your backend, and your backend talks to
`/v1/support`. Never put the key in the app binary.


## Status banner and help-centre search (status lane) [#status-banner-and-help-centre-search-status-lane]

### The status banner [#the-status-banner]

```js
import { GaugeSupport } from '@gauge/support';
const gauge = new GaugeSupport({ apiKey: process.env.GAUGE_KEY });

// GET /support/status in YOUR backend, proxied to the app:
const s = await gauge.projects.status(PROJECT_ID, { integration: 'customer' });
```

```python
from gauge_support import GaugeSupport
gauge = GaugeSupport(os.environ["GAUGE_KEY"])
s = gauge.projects.status(PROJECT_ID, integration="customer")
```

How to render it (every value comes from Gauge, so show nothing you didn't get):

| Show | From |
|---|---|
| "Our assistant answers" / "Our team answers" / "Assistant, with the team as backup" | `answering`: `ai_only` / `people_only` / `ai_with_people` |
| "Team online" dot | `teamOnline`, and `availableCount.chat` or `.call` for a count |
| "Open today 09:00–18:00" | `hours.todayRanges[].startLocal`–`endLocal` (in `hours.timezone`). Empty = closed today. |
| "Opens Sunday 09:00" | `hours.nextOpenAt` when `hours.openNow` is false |
| "Usually replies in about 4 min" | `typicalFirstReply.seconds`. **When it is `null`, show nothing.** The reason is `"not enough data"`. |
| Chat / Call / Ticket buttons | `channels.chat.available`, `.call`, `.ticket`. Disable or hide a channel and use `reason` for the copy (`outside_business_hours`, `no_agents_online`, `queue_closed`, `not_offered`, …). |

When `hours.configured` is `false`, nothing is configured in Gauge, so don't print opening hours.

Freshness: Gauge caches the answer for at most **10 s**. Poll while the screen is visible, every 30–60 s
is plenty. The limit is 600 calls/min per API key, so cache in your backend if many users open the screen at once.

### Help-centre search and article [#help-centre-search-and-article]

```js
const { results } = await gauge.projects.searchArticles(PROJECT_ID, query, { locale: 'ar', integration: 'customer' });
// results[i].highlights.title = [[start, end], …]: UTF-16 offsets into results[i].title
const article = await gauge.projects.getArticle(PROJECT_ID, results[0].slug, { locale: 'ar', integration: 'customer' });
// article.bodyHtml is sanitised. Render it in a WebView or an HTML text view. article.related lists more reading.
```

```python
hits = gauge.projects.search_articles(PROJECT_ID, query, locale="ar", integration="customer")
article = gauge.projects.get_article(PROJECT_ID, hits["results"][0]["slug"], locale="ar", integration="customer")
```

- Results match the web portal exactly: the same search, the same published, public articles.
- Pass the **integration** your user belongs to (`customer`, `salon`). A shelf limited to `salon` appears only
  for `integration: 'salon'`. Shared articles appear for everyone.
- Highlights are offsets, not HTML. Apply bold or a tint with `NSAttributedString` / `SpannableString` /
  `TextSpan` on the exact ranges. Swift's `NSString` and Kotlin both index in UTF-16, the same as the offsets.
- Arabic works without extra code. Gauge folds alef forms, ta marbuta and diacritics on both sides.
- `getArticle` takes the id or the slug. A draft, an internal article or another integration's article is a 404.
- Limits: search 120/min, reads 600/min per API key. A 429 means back off.

Reference: [api-s1.md §6](/support/api-s1#6-native-help--support-screens-live-status-and-the-help-centre).

## Requests, threads and unread [#requests-threads-and-unread]

Your backend acts **as the signed-in user**, named by `externalRef` (your user id, derived server-side from
your session, never from the app's request body). Gauge refuses anything that is not that user's: another
customer's ticket, chat or message is a 404, exactly like an id that does not exist.

### "My requests" list [#my-requests-list]

```js
const page = await gauge.projects.listTickets(PROJECT_ID, { externalRef: user.id, statusGroup: 'open' });
// page.rows[i]: subject, statusGroup, lastReply.preview, lastActivityAt, sla.state, context, unread
```

```python
page = gauge.projects.list_tickets(PROJECT_ID, external_ref=user.id, status_group="open")
```

| Show | From |
|---|---|
| Tabs Open / Waiting for you / Resolved | `statusGroup`: `open` / `waiting_on_customer` / `resolved` (filter with `statusGroup=`) |
| Last message line | `lastReply.preview` (≤140 chars, never an internal note), `lastReply.authorType` (`agent`/`ai` = "from the team") |
| Time | `lastActivityAt` |
| Dot / count on the row | `unread` |
| "About booking BK-1042" | `context` (`null` when the request is not about a record) |

### Opening a request from a record ("Get help") [#opening-a-request-from-a-record-get-help]

```js
await gauge.projects.createTicket(PROJECT_ID, {
  subject, body, requesterExternalRef: user.id,
  integration: 'customer',                    // or 'salon' in the salon app
  context: { type: 'booking', id: booking.id } // booking | transaction | invoice | voucher | payout
});
```

**Check that the user owns or can see that record before you send it.** Gauge stores your id as-is, shows it to
agents ("About: Booking BK-1042") and returns it on the list and the thread, but never looks it up.

### The thread [#the-thread]

```js
const t = await gauge.projects.getThread(PROJECT_ID, ticketId, user.id);
// t.messages: customer-visible only, oldest first; t.attachments[i].downloadState; t.readOnly
await gauge.projects.reply(PROJECT_ID, ticketId, user.id, text);
await gauge.projects.uploadAttachment(PROJECT_ID, ticketId, user.id, { filename, contentType, contentBase64 });
```

- The reply is the portal's reply: written as that customer, it reopens a waiting or resolved request and
  never emails the customer.
- `readOnly: true` (blocked, deactivated, no access): hide the composer. Writes answer 403 `customer_read_only`.
- `download.url` is short-lived. Fetch it when the user taps, never cache it. `scanning` = not openable yet.

### Unread badge [#unread-badge]

```js
const { total } = await gauge.projects.unread(PROJECT_ID, user.id); // header bell
await gauge.projects.markRead(PROJECT_ID, user.id, { scope: 'ticket', ticketId }); // when the thread is shown
// { scope: 'chat', chatId } after showing a chat, { scope: 'all' } for "mark all read"
```

```python
gauge.projects.unread(PROJECT_ID, user.id)["total"]
gauge.projects.mark_read(PROJECT_ID, user.id, scope="ticket", ticket_id=ticket_id)
```

- Unread counts only the team's messages (agent, AI) after the user's read position, over their requests and
  their chats. Their own messages and internal notes never count.
- The read position is shared with the web portal. Opening the request there clears it in the app too.
- Marks only move forward. Pass `throughMessageId` (the last message you showed) if new messages may have
  arrived while the screen was loading. Without it the whole thread is marked read.
- Instead of polling, subscribe to the **`support.customer.unread_changed`** webhook (ids + counts, `cause:
  read | team_message`) and push `payload.total` to the user's devices. Keep the highest `payload.version`.

Reference: [api-s1.md §7](/support/api-s1#7-native-help--support-screens-requests-threads-and-unread).


# Quick start: API only (your backend talks to Gauge) (/support/quickstart-api)

{/* GENERATED from docs/support/quickstart-api.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
export GAUGE=https://app.gauge.chat/backend
export KEY=pulse_k_test_...        # a test key reaches the sandbox only
export APP=<your App id>
```

## 1. Provision a user and grant Integrations [#1-provision-a-user-and-grant-integrations]

```bash
curl -sS -X PUT "$GAUGE/v1/support/customers/by-ref/u_1029" \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d "{\"email\":\"layla@example.com\",\"projectIds\":[\"$APP\"],\"integrationKeys\":{\"$APP\":[\"customer\"]}}"
```

`integrationKeys` is authoritative for each App you name. On an App with several integrations an
empty list means the default integration only.

## 2. Mint a sign-in link onto one Integration [#2-mint-a-sign-in-link-onto-one-integration]

```bash
curl -sS -X POST "$GAUGE/v1/support/sessions" \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d "{\"projectId\":\"$APP\",\"externalRef\":\"u_1029\",\"integration\":\"customer\"}"
# → 201 {"url":"https://…","expiresAt":"…"}
```

| Answer | Meaning |
|---|---|
| `201` | Redirect the browser (or WebView) to `url`. Single use, mint per open |
| `403 integration_not_granted` | Grant the key in step 1 first |
| `404 unknown_integration` | The App has no integration with that key |

## 3. Revoke [#3-revoke]

Send the user again without the key: `"integrationKeys":{"<appId>":[]}`. Their live chat on it ends
at their next message, and tokens minted before the change stop working.

## Signed tokens from your backend [#signed-tokens-from-your-backend]

If your own frontend opens the widget, mint a token instead of a link; see
[integration-token.md](/support/integration-token).


# Quick start: chat in your website or web app (signed-in users) (/support/quickstart-web-app)

{/* GENERATED from docs/support/quickstart-web-app.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

You need: your **App id**, your **identity secret** and the **Integration key** (Console → Apps →
your App → Install), plus Node ≥ 18 or Python ≥ 3.9. Using Next.js, Django, Laravel, Rails or Go?
Each has a full page, webhook included: [quickstarts/](/support/quickstarts).

## 1. Your server: an endpoint that returns a token [#1-your-server-an-endpoint-that-returns-a-token]

Node / Express:

```js snippet=mint
import { mintIntegrationToken } from '@gauge/support';

// GET /gauge-token: your session middleware has already set req.user
export async function gaugeToken(req, res) {
  const token = await mintIntegrationToken(process.env.GAUGE_IDENTITY_SECRET, {
    appId: process.env.GAUGE_APP_ID,
    userId: req.user.id,
    integration: 'customer',
    name: req.user.name,
    email: req.user.email,
  });
  res.json({ token });
}
```

Python / Flask:

```python snippet=mint
import os
from flask import jsonify, g
from gauge_support import mint_integration_token

def gauge_token():  # GET /gauge-token, behind your login
    token = mint_integration_token(
        os.environ["GAUGE_IDENTITY_SECRET"],
        app_id=os.environ["GAUGE_APP_ID"],
        user_id=g.user.id,
        integration="customer",
    )
    return jsonify(token=token)
```

## 2. Your page: the widget [#2-your-page-the-widget]

**List your site first.** Every site the widget runs on must be listed in the App's allowed websites
(**Apps → your App → Install → Allowed sites**), as `scheme://host[:port]`, for example
`https://app.example.com` or `http://localhost:3000`. If it is not listed, the browser blocks the widget:
Gauge sends no CORS headers to that page, so the chat cannot open or send. Matching ignores case and is
exact on scheme, host and port. A port, `http` instead of `https`, or a subdomain each count as a
separate site. List one origin for every port you develop on. Changes apply within about a minute.

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<your App’s chat connection id>',
      supportMode: true,
      integration: 'customer',
      // Called on every open, so the token is always fresh (they live 10 minutes at most).
      getToken: function () {
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.

Logged-out visitors: leave out `getToken`. They chat anonymously when the integration allows it.

### Sign-out and shared browsers (single-page apps: required) [#sign-out-and-shared-browsers-single-page-apps-required]

Call `PulseWebchat.logout()` from your own sign-out, **before** you clear your session. It ends the
user's live chat, expires the widget's visitor cookie and removes the widget from the page. Then call
`init(...)` again for whoever comes next (signed in, or anonymous without `getToken`):

```js
async function signOut() {
  await window.PulseWebchat.logout();   // with the npm SDK: `await reset()` from '@gauge/support/browser'
  await fetch('/logout', { method: 'POST', credentials: 'include' });
  window.PulseWebchat.init({ apiUrl: 'https://app.gauge.chat/backend', connectionId: '<id>', supportMode: true });
}
```

The server also protects you if you forget: a chat resumes only for the same person (token `sub` or
hash `externalId`) at the same identity level. Anyone else on that browser, including an anonymous
visitor after a signed-in one, gets a new chat and a new cookie, and the previous chat ends.
`logout()` is still the right call, because it ends the chat at sign-out rather than when the next
person happens to open the widget.

When the same person comes back to a chat that is still open, the widget reopens that same
conversation, with its history and whoever was already handling it.

### Their chats: the home view [#their-chats-the-home-view]

A visitor who has chatted before lands on a **home view** when the panel opens: your greeting, a
**Start new chat** key, and their chats, newest first. Each row shows who handled it (the agent's
photo or initials, the assistant's mark for an AI chat, or a team mark while it waits), the topic or
the visitor's first line, the last message, the time, the state (**Open**, **Waiting**, **Closed**) and
how many replies they have not read. A visitor with no chats goes straight into a new chat with your
greeting and starter topics.

- **Closed chats are read-only.** Opening one shows its history, a line saying when and why it closed,
  and **Start new chat** in place of the message box. A new chat is a new conversation; the old one
  stays closed (your team can still reopen it from the console).
- **One open chat at a time.** While the visitor has an open chat, the home key reads **Continue chat**
  and takes them back into it.
- **Unread.** When an agent or the assistant replies, the floating launcher shows the visitor's total
  unread count, each row shows its own, and embedded mode reports the total in `onStateChange`.
  Opening a chat marks it read, and a reply that arrives while the visitor is looking at it never counts.
- **Where it opens.** `openTo: 'home'` (default) shows the list; `openTo: 'last-open'` goes straight
  back into the visitor's open chat when they have one. Your App's **Appearance → When the widget
  opens** sets the same choice from the console; the `init` option wins over it.

Only the visitor's own chats are listed: a signed-in user sees theirs from any device, and an
anonymous visitor sees the chats from this browser only.

### Embedded in your own panel [#embedded-in-your-own-panel]

If your app already has a chat drawer with its own header and close button, render the conversation
inside it instead of the floating launcher:

```html
<aside id="help-drawer" hidden>
  <header><strong id="help-title">Support</strong> <span id="help-badge"></span>
    <button id="help-close" aria-label="Close">×</button></header>
  <div id="help-chat" style="height: 520px"></div>
</aside>
<script>
  const chat = window.PulseWebchat.init({
    apiUrl: 'https://app.gauge.chat/backend',
    connectionId: '<your App’s chat connection id>',
    supportMode: true,
    getToken: () => fetch('/gauge-token', { credentials: 'include' }).then((r) => r.json()).then((j) => j.token),
    mode: 'embedded',
    mount: document.getElementById('help-chat'),
    theme: { accent: '#1f5fbf', onAccent: '#ffffff', radius: 8 }, // #1f5fbf on white: 6.1:1
    onStateChange: (s) => {
      document.getElementById('help-title').textContent =
        s.agentName ? s.agentName : s.status === 'offline' ? 'Support (offline)' : 'Support';
      // `unread` is the visitor's unread replies across all their chats; `view` is 'home' or 'thread'.
      document.getElementById('help-badge').textContent = s.unread > 0 ? String(s.unread) : '';
    },
  });
  // Tell the widget when your drawer is shown or hidden, so `unread` counts the right replies.
  function openHelp() { document.getElementById('help-drawer').hidden = false; chat.open(); }
  function closeHelp() { document.getElementById('help-drawer').hidden = true; chat.close(); }
  document.getElementById('help-close').onclick = closeHelp;
</script>
```

The mount must have a height (the widget fills 100% of it and scrolls the conversation inside).

### Option shapes [#option-shapes]

```ts
PulseWebchat.init(options: WebchatInitOptions): WebchatController | null

interface WebchatInitOptions extends WebchatConfig {   // apiUrl, connectionId, supportMode, getToken, …
  mode?: 'floating' | 'embedded';   // default 'floating' (launcher + panel), unchanged
  mount?: HTMLElement;              // required for 'embedded': an empty element you own
  theme?: WebchatTheme;
  onStateChange?: (state: WebchatState) => void;
  onClose?: () => void;             // floating only: the visitor closed the panel
  openTo?: 'home' | 'last-open';    // default 'home'; wins over the App's Appearance setting
}
interface WebchatTheme {
  accent?: string; onAccent?: string; surface?: string; ink?: string; muted?: string; // hex, rgb() or hsl()
  radius?: number;      // px, clamped to 0–24
  fontFamily?: string;  // letters, digits, spaces, commas, quotes, hyphens; omit to inherit your font
}
interface WebchatState {
  status: 'connecting' | 'ready' | 'queued' | 'offline' | 'ended' | 'error';
  unread: number;        // the visitor's unread agent/AI replies across all their chats, less the chat on screen
  view?: 'home' | 'thread'; // the chat list, or a conversation
  agentName?: string;    // once the server has sent one
}
interface WebchatController {
  readonly mode: 'floating' | 'embedded';
  open(): void;     // floating: open the panel. embedded: your drawer is showing (clears unread)
  close(): void;    // floating: close the panel. embedded: your drawer is hidden (replies count as unread)
  destroy(): void;  // unmount, remove listeners, close the socket. Safe to call twice.
}
```

`mode: 'embedded'` without an `HTMLElement` `mount` logs one `PulseWebchat:` console error, renders
nothing and returns `null`.

### Theme rules [#theme-rules]

- Colours must be hex (`#rgb`, `#rrggbb`), `rgb()` or `hsl()`, with no alpha. Names, `var()`, other
  functions and anything else are ignored with a console warning.
- Three pairs must each reach **4.5:1** (WCAG AA): `onAccent` on `accent`, `ink` on `surface`, and
  `muted` on `surface`. A missing side is measured against Gauge's default (white `onAccent`, white
  `surface`, near-black `ink`). If a pair fails, both of its colours fall back to the defaults and one
  console warning names the pair and the measured ratio.
- The keyboard focus ring is never themed. It stays Gauge's indigo, because it is an accessibility
  floor and not a brand colour.

### Lifecycle [#lifecycle]

`init` once per mount. Call `controller.destroy()` when your panel unmounts (React `useEffect`
cleanup, route change, sign-out). It closes the socket and removes every listener, so a later `init`
starts clean. For sign-out, `PulseWebchat.logout()` (above) still ends the chat on the server.

In embedded mode the widget renders no header, close button or launcher. Your drawer owns those. It
does render the home view (the visitor's chats), the status line, the conversation, quick replies and
the composer, with a back key from a chat to the list. When a signed-in
visitor writes while nobody is online, the status line reads "No one's online right now. We'll reply
here and by notification." and the composer stays open. Anonymous visitors still get the email form.

## 3. Check it [#3-check-it]

Open your page signed in and send a message. If the browser console shows a CORS error on
`/support/chat/session`, your page's origin is not in the App's allowed websites (section 2). In the console the conversation shows your user's
name and **Verified**. If it doesn't, paste the token from `/gauge-token` into **Developers → Support
→ Token checker**: it names the rule that failed. See [integration-token.md](/support/integration-token)
for every code.

## Two kinds of users on one App [#two-kinds-of-users-on-one-app]

Mint with `integration: 'salon'` for your partners and `'customer'` for everyone else, and grant
each user their keys with customer sync (`integrationKeys`). Each integration can have its own
assistant, team and hours.

## Topics: starter buttons, the AI and requests [#topics-starter-buttons-the-ai-and-requests]

Add topics under **Apps → your App → Topics** (up to 10). Each has a name, a description the AI reads, an
**Answered by** (who handles it), an **AI behaviour** and up to 3 **details to collect**:

- Up to 4 topics per integration appear as **starter buttons** under the widget's greeting. Nothing to change in
  your page: the widget draws them.
- A typed first message is labelled by the AI (cheapest model; skipped with no AI credit; low confidence stays
  "Other"). A starter tap or an agent's choice is never overwritten.
- **AI behaviour**: *Answer* (default), *Answer + offer a person* (a "Talk to a person" quick reply), *Hand to a
  person* (no AI answer, straight to the topic's team), *Open a request* (the AI collects the details, asks the
  customer to confirm, then opens a ticket and gives the reference).
- **Details**: a detail with *Fill from app attribute* `context_id` is filled from the token you mint (add
  `attrs: { context_type: 'booking', context_id: 'BK-1042' }`), so the AI never asks for it.
- Quick replies (≤3 buttons) show under the AI's latest message; a tap sends its words.

Native screens use the same list: `GET /v1/support/projects/:id/topics` (see `api-s1.md` §7.2a).


# Quick start: chat in your mobile app (WebView) (/support/quickstart-webview)

{/* GENERATED from docs/support/quickstart-webview.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

**Flutter:** the `gauge_support_webview` package is the whole
app side in one widget (permissions, uploads, safe areas, sign-out), with a full example app and backend.
**React Native, iOS, Android:** copy-paste screens in [webview-recipes.md](/support/webview-recipes). The
background (cookies, push, sign-out rules) is in [mobile.md](/support/mobile). This page covers the Integration part.

## 1. Your backend: mint a link [#1-your-backend-mint-a-link]

```js
import { GaugeSupport } from '@gauge/support';

const gauge = new GaugeSupport({ apiKey: process.env.GAUGE_API_KEY });

export async function supportLink(user) {
  const { url } = await gauge.sessions.mint({
    projectId: process.env.GAUGE_APP_ID,
    externalRef: user.id,
    email: user.email,
    integration: 'salon', // lands on /chat?integration=salon
  });
  return url; // single use, short-lived: mint per open
}
```

```python
import os
from gauge_support import GaugeSupport

gauge = GaugeSupport(api_key=os.environ["GAUGE_API_KEY"])

def support_link(user):
    link = gauge.sessions.mint({
        "projectId": os.environ["GAUGE_APP_ID"],
        "externalRef": user.id,
        "email": user.email,
        "integration": "salon",
    })
    return link["url"]
```

Answers: `201` with the URL · `403 integration_not_granted` if the user isn't granted `salon` (grant
it with customer sync `integrationKeys`) · `404 unknown_integration` if the App has no such key.

## 2. Your app: open it [#2-your-app-open-it]

```dart
final url = await api.supportLink(); // your backend, step 1
controller.loadRequest(Uri.parse(url));
```

The WebView signs in, then opens `/chat?integration=salon`. Gauge checks the grant again there, so an
edited URL cannot reach an integration the user doesn't have.

## Notes [#notes]

- One live chat per user per App in this release. Opening a second integration while a chat is live
  continues that chat.
- Revoking a key ends the user's live chat on it at their next message.


# Gauge Support quick start (/support/quickstart)

{/* GENERATED from docs/support/quickstart.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

The same flow is in the console at **Developers → Support** (`/developers/support`). There, every
snippet is already filled with your base URL and project id, and each step has a **Check** that
verifies it against your workspace. This page mirrors it.

| You need | Where |
|---|---|
| A support project | Support → Settings → Projects |
| Your API base URL | Developers → Support (production: `https://app.gauge.chat/backend`) |
| Node ≥18 **or** Python ≥3.9 **or** curl | — |

SDKs: `npm install @gauge/support` (zero dependencies, ESM + CJS, Node ≥18 and edge runtimes) and
`pip install gauge-support` (`GaugeSupport` / `AsyncGaugeSupport` over `httpx`, plus the identity
hash and webhook helpers; Python ≥3.9). Both expose the same resources (`projects`, `customers`,
`tickets`, `sessions`) with the same retry and Idempotency-Key rules.

## Try it free first: the sandbox [#try-it-free-first-the-sandbox]

Every workspace has one **sandbox** project, created the first time you open **Developers →
Support** or make a request with a test key. Pick **Sandbox · test keys only** in the project
picker and click **Create test key**: you get a `pulse_k_test_` key that reaches the sandbox and
nothing else. Run every step below against it.

- It's free: it never counts toward your plan's projects, conversations, usage or analytics.
- Nothing leaves the building: emails are recorded but never sent, there is no SMS, voice or AI
  spend, and webhooks arrive with `livemode: false`.
- A test key on a live project, or a live key on the sandbox, is **403** with `reason`
  `test_key_live_project` / `live_key_sandbox_project`. Sandbox customers are invisible to live
  keys, and live customers to test keys, so the two never mix.
- **Reset sandbox** (on the sandbox panel, typed confirmation) deletes its customers, tickets,
  chats and articles. The project id, your test keys and your widget embed keep working.

Find the sandbox's id with `gauge.projects.list()` (the row with `isSandbox: true`; a test key
sees only that one). When you are ready, switch the picker to your real project and create a live
key there.

---

## Step 1 · Create a project-pinned key (2 min) [#step-1--create-a-project-pinned-key-2-min]

In **Developers → Support**, choose the project and click **Create support key**. You get a
**live** key that can reach only that project. Every other project, and any customer reachable
only through one, answers **404**. Choose:

- **Sign customers in** (`support-sessions:rw`): needed for portal sign-in links (step 3b).
- **Erase customers (GDPR)** (`support-erase:rw`): leave it off unless your backend runs erasure.

`support:rw` is always included. `*:rw` never implies the two capability scopes. Store the key as
`GAUGE_API_KEY` in your server's secret manager. It is shown once.

> **Test keys** (`pulse_k_test_`) are for the sandbox: on the sandbox project the button reads
> **Create test key**, and that key works there and nowhere else. Live keys never reach the sandbox.

```bash
curl -s $BASE/v1/support/projects/$PROJECT_ID -H "Authorization: Bearer $GAUGE_API_KEY"
```

```ts
import { GaugeSupport } from '@gauge/support';
export const gauge = new GaugeSupport({ apiKey: process.env.GAUGE_API_KEY!, baseUrl: BASE });
await gauge.projects.get(PROJECT_ID);
```

```python
import os
from gauge_support import GaugeSupport
gauge = GaugeSupport(os.environ["GAUGE_API_KEY"], base_url=BASE)   # or AsyncGaugeSupport
gauge.projects.get(PROJECT_ID)
```

Python mirrors every call below in snake_case with the API's camelCase bodies, e.g.
`gauge.customers.upsert_by_ref(str(user.id), {"email": ..., "projectIds": [PROJECT_ID]})`,
`gauge.customers.sync(batch, idempotency_key=derive_idempotency_key("nightly", day, i))`, and
`for c in gauge.customers.list_updated_since(since): ...` then `pager.high_watermark`.

**Check** passes when a live key pinned to this project has made a request (on the sandbox: when a
test key has). A workspace-wide key works but shows a warning, because a leak would expose every
project.

## Step 2 · Provision and sync your users (4 min) [#step-2--provision-and-sync-your-users-4-min]

Address every user by **your own stable user id** (`externalRef`), never by email. The full rules
are in [customer-sync.md](/support/customer-sync).

**On sign-up or change: upsert one user.**

```ts
await gauge.customers.upsertByRef(user.id, {
  email: user.email, name: user.name, locale: 'ar',
  projectIds: [PROJECT_ID],          // authoritative within your key's projects
  metadata: { plan: user.plan },     // shown to agents; no secrets or regulated data
});
// → { outcome: 'created' | 'updated' | 'unchanged', customer }
```

**Batch: up to 500 per call.** Each item stands alone; check every `error`.

```ts
import { deriveIdempotencyKey } from '@gauge/support';
const run = await gauge.customers.sync(batch, { idempotencyKey: await deriveIdempotencyKey('nightly', day, i) });
```

The same `Idempotency-Key` with the same body replays the first answer, including the same
`runId`. The same key with a different body is a 409.

**Nightly reconcile.**

```ts
const pager = gauge.customers.listUpdatedSince(new Date(Date.parse(W) - 5 * 60_000));
for await (const c of pager) await repair(c);
await saveWatermark(pager.highWatermark);   // exactly as returned; subtract the 5 min at READ time
```

Deactivate or block many users with `gauge.customers.setStatus('deactivated', { externalRefs })`.
`deactivated` makes the user read-only; `blocked` locks them out and drops live sessions.

**Check** passes when at least one customer holds active access to the project.

## Step 3a · Embed the widget (4 min) [#step-3a--embed-the-widget-4-min]

**Once per project**, provision a chat line, turn chat on, require your server's hash and allow
your origin. Then reveal the chat secret **once** and store it as `GAUGE_CHAT_SECRET`:

```ts
const p = await gauge.projects.get(PROJECT_ID);
await gauge.projects.update(PROJECT_ID, {
  version: p.version, identityMode: 'hmac_verified', chatEnabled: true,
  chatConnection: { mode: 'provision' }, chatAllowedOrigins: ['https://app.example.com'],
});
const { secret } = await gauge.projects.revealChatSecret(PROJECT_ID);   // a second reveal is 409
```

**Per page view, on your server:** sign the identity (v2: the user id and the time, so a leaked
hash expires after 10 minutes).

```ts
import { signIdentity } from '@gauge/support';
const identity = await signIdentity(process.env.GAUGE_CHAT_SECRET!, user.id);
// { externalId, identityHash, identityTs }  — identityTs is epoch SECONDS
```
```python
from gauge_support import sign_identity
identity = sign_identity(os.environ["GAUGE_CHAT_SECRET"], str(user.id))
```
```bash
TS=$(date +%s)
printf '%s:%s' "$USER_ID" "$TS" | openssl dgst -sha256 -hmac "$GAUGE_CHAT_SECRET" | sed 's/^.* //'
```

**On the page:** pin the live release with its integrity hash. The console fills in `version`
and `integrity` from `https://widget.gauge.chat/v1/manifest.json` (`files['widget.js']`).

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<project chatConnectionId>',
      visitorId: '{{ user.id }}',
      identityHash: '{{ identity.identityHash }}',
      identityTs: {{ identity.identityTs }},
      supportMode: true,
    });
  });
</script>
```

Or from a bundler: `import { loadWidget } from '@gauge/support/browser'` and call
`loadWidget({ version, integrity, apiUrl, connectionId, visitorId, identityHash, identityTs, supportMode: true })`.
It refuses to load a pinned version without a valid `sha384-` integrity, and an `identityTs` that
is not whole epoch seconds.

Your page's CSP needs `script-src https://widget.gauge.chat` and
`connect-src https://app.gauge.chat wss://app.gauge.chat` (details in
widget-hosting.md §4).

> **identityHash v2 is the default.** The widget sends the hash in the `x-pulse-identity` header and
> `externalId` + `identityTs` in the `POST /support/chat/session` body; the server accepts the
> timestamp within ±10 minutes. Because the hash is signed at page render, a page left open longer
> than that should re-render (or call `PulseWebchat.init` again) before the visitor opens chat. Once
> every page sends `identityTs`, turn on the project's `chatIdentityTsRequired`
> (`gauge.projects.update(id, { version, chatIdentityTsRequired: true })`) so a v1 hash, which never
> expires, is refused. v1 (`identityHash(secret, userId)`, no `identityTs`) keeps working until
> then. Signing by hand? v2 is `hex(HMAC-SHA256(secret, "v2\n" + userId + "\n" + identityTs))`,
> deliberately not `userId:identityTs`, so no v1 hash can ever pass as v2.

**Check** passes when the manifest is reachable and the project has chat on, a chat line, and
`hmac_verified` identity.

## Step 3b · Or sign users into the portal or a WebView [#step-3b--or-sign-users-into-the-portal-or-a-webview]

Mint a **single-use** link per open (≤15 minutes; needs `support-sessions:rw`) and redirect to it.
Never cache or share it.

```ts
const { url } = await gauge.sessions.mint({ projectId: PROJECT_ID, externalRef: user.id, email: user.email, ttlSeconds: 300 });
return Response.redirect(url, 302);
```

The project needs a usable portal address. A new project is given a platform address derived
from the deployment's portal template (`<key>.support.gauge.chat` on Gauge), and a custom domain
counts once verified under Support → Settings → Domains. With no usable address the mint answers
`404 "No session link is available"`, the same answer as an unknown user, by design. If that
happens, check the project's Domains page first.

## Step 4 · Receive and verify webhooks (4 min) [#step-4--receive-and-verify-webhooks-4-min]

Add an endpoint in **Developers → Webhooks** subscribed to `support.customer.*` (and
`support.ticket.*` if you want tickets) and store its signing secret as `GAUGE_WEBHOOK_SECRET`.
Your receiver must:

1. **Verify the signature on the raw body.** `x-pulse-signature` is
   `sha256=<hex HMAC-SHA256(secret, `$\{x-pulse-timestamp\}.$\{rawBody\}`)>`. During a rotation on our
   side it carries two comma-separated values, and any match passes.
2. **Reject anything more than 5 minutes from your clock.** `x-pulse-timestamp` is epoch
   **milliseconds**.
3. **Dedupe on the body's `id`.** It is stable across retries and manual resends.
   **Drop `livemode: false`** in production: it marks events about the sandbox project.
4. **Answer 2xx within 10 s** and do the work asynchronously. Failed deliveries retry at
   30 s · 5 m · 1 h · 6 h.

```ts
// Next.js route handler (Node or Edge)
import { verifyWebhook } from '@gauge/support';
export async function POST(req: Request) {
  const r = await verifyWebhook([process.env.GAUGE_WEBHOOK_SECRET!], await req.text(), req.headers);
  if (!r.valid) return new Response(r.reason, { status: 400 });
  if (await seen(r.event.id)) return new Response(null, { status: 200 });
  await queue.add(r.event);
  return new Response(null, { status: 200 });
}
```

```python
# FastAPI (Django and Flask recipes: packages/sdk-python/README.md)
from gauge_support import verify_webhook
@app.post("/gauge/webhooks")
async def gauge_webhook(request: Request):
    r = verify_webhook([os.environ["GAUGE_WEBHOOK_SECRET"]], await request.body(), request.headers)
    if not r.valid:
        raise HTTPException(400, r.reason)
    if not seen(r.event["id"]):
        enqueue(r.event)
    return {"ok": True}
```

Hold both secrets in the list while **you** rotate. Comparison is constant-time, and every
secret × signature pair is checked.

**Check** passes when an enabled endpoint hears support customer events and its last delivery
succeeded. Use **Send test event** on the endpoint page to trigger one.

---

## Errors you will meet [#errors-you-will-meet]

| HTTP | `code` / `reason` | Meaning |
|---|---|---|
| 401 | `unauthorized` | key missing, unknown, revoked or expired |
| 403 | `forbidden` / `test_key_live_project` | a `pulse_k_test_` key naming a live project (test keys reach only the sandbox) |
| 403 | `forbidden` / `live_key_sandbox_project` | a live key naming the sandbox project |
| 403 | `forbidden` | the key lacks the scope or capability (`support-sessions:rw`, `support-erase:rw`) |
| 403 | `customer_inactive` | ticket for a blocked or deactivated customer |
| 404 | `not_found` | absent, another tenant's, or outside your key's projects (indistinguishable on purpose) |
| 409 | `conflict` | stale `version`, or an Idempotency-Key reused with a different body |
| 422 | `email_required` · `email_in_use` · `email_unavailable` | see [customer-sync.md](/support/customer-sync) §2 |
| 429 | `rate_limited` | honour `Retry-After` (the SDK does) |

Both SDKs raise a typed class per status (Python: `GaugeValidationError` … `GaugeConnectionError`
with `.status`, `.code`, `.reason`). The Node SDK raises (`GaugeValidationError`, `GaugeAuthenticationError`,
`GaugePermissionError`, `GaugeNotFoundError`, `GaugeConflictError`, `GaugeRateLimitError`,
`GaugeServerError`, `GaugeConnectionError`) carrying `status`, `code` and `reason`. It retries
429, 5xx and network errors only where a repeat cannot double a write.

## Verified end to end [#verified-end-to-end]

On 2026-10-14 this flow ran against a local stack twice. First with a live pinned key (30
assertions, `dx-e2e/transcript.txt`). Then with a **test key against the sandbox** (41 assertions,
`dx-e2e/transcript-sandbox.txt`), using both SDKs: the sandbox is created on first visit; steps 1–4
pass with the test key in Node and in the Python client; identity v2 opens a widget session while
v1 and an 11-minute-old v2 hash are refused; every webhook arrives with `livemode: false`; the
ticket emails are recorded `sent` / `sandbox` and never handed to the transport; a test key on a
live project and a live key on the sandbox are both 403; and Reset sandbox deletes the test data
while the project, its id and its chat line survive. The transcripts are kept with the
support-embed programme notes.


# Quick start: Django (/support/quickstarts/django)

{/* GENERATED from docs/support/quickstarts/django.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
pip install gauge-support
export GAUGE_APP_ID=<app id> GAUGE_IDENTITY_SECRET=<identity secret> GAUGE_WEBHOOK_SECRET=<whsec_…>
```

## 1 and 3. Two views: `support/views.py` [#1-and-3-two-views-supportviewspy]

```python snippet=django
import logging
import os

from django.contrib.auth.decorators import login_required
from django.http import HttpResponse, HttpResponseBadRequest, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_GET, require_POST

from gauge_support import mint_integration_token, verify_webhook

log = logging.getLogger(__name__)
_handled = set()  # use your database in production: ids repeat on retries and resends


@require_GET
@login_required
def gauge_token(request):
    token = mint_integration_token(
        os.environ["GAUGE_IDENTITY_SECRET"],
        app_id=os.environ["GAUGE_APP_ID"],
        user_id=str(request.user.pk),
        integration="customer",
        email=request.user.email or None,
    )
    response = JsonResponse({"token": token})
    response["Cache-Control"] = "no-store"
    return response


@csrf_exempt  # Gauge signs the request instead; the signature is the CSRF defence here
@require_POST
def gauge_webhook(request):
    result = verify_webhook(os.environ["GAUGE_WEBHOOK_SECRET"], request.body, request.headers)
    if not result.valid:
        return HttpResponseBadRequest(result.reason)
    event = result.event
    if event["id"] not in _handled:
        _handled.add(event["id"])
        log.info("gauge %s %s", event["event"], event["id"])
    return HttpResponse(status=200)
```

`request.body` is the raw bytes, which is what the signature covers. `urls.py`:

```python
from django.urls import path
from support import views

urlpatterns = [
    path("gauge-token", views.gauge_token),
    path("gauge/webhooks", views.gauge_webhook),
]
```

## 2. The widget (your page) [#2-the-widget-your-page]

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<chat connection id>',
      supportMode: true,
      integration: 'customer',
      getToken: function () { // called on every open, so the token is always fresh
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.
Signed-out visitors: leave out `getToken`; they chat anonymously where the Integration allows it.
**Check my site** (Developers → Support) fetches your page and tells you if the snippet, its
integrity and the connection id are right.

## 4. Check it [#4-check-it]

1. Sign in to your site as a test user (in the sandbox: **Seed test customers**, then sign in as
   `test_customer_1`), open the widget and send "hello". In the console the conversation shows the
   user's name and **Verified**. Not verified? Paste the JSON from `/gauge-token` into
   **Developers → Support → Token checker**: it names the rule that failed.
2. **Developers → Webhooks → your endpoint → Send test event**, pick `support.chat.message_created`:
   the result says *Delivered · 200* and your log shows the event id. Change one byte of the secret
   in your env and send again: your handler answers 400 `bad_signature`.

Server was down? **Replay failed** on the same page resends everything that did not land.


# Quick start: Express (/support/quickstarts/express)

{/* GENERATED from docs/support/quickstarts/express.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
npm install express @gauge/support
export GAUGE_APP_ID=<app id> GAUGE_IDENTITY_SECRET=<identity secret> GAUGE_WEBHOOK_SECRET=<whsec_…>
```

## 1. Token endpoint [#1-token-endpoint]

Your session middleware has already put the user on `req.user`.

```js snippet=mint
import { mintIntegrationToken } from '@gauge/support';

export async function gaugeToken(req, res) {
  const token = await mintIntegrationToken(process.env.GAUGE_IDENTITY_SECRET, {
    appId: process.env.GAUGE_APP_ID,
    userId: String(req.user.id),
    integration: 'customer',
    name: req.user.name,
    email: req.user.email,
  });
  res.set('cache-control', 'no-store').json({ token });
}
```

## 2. The widget (your page) [#2-the-widget-your-page]

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<chat connection id>',
      supportMode: true,
      integration: 'customer',
      getToken: function () { // called on every open, so the token is always fresh
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.
Signed-out visitors: leave out `getToken`; they chat anonymously where the Integration allows it.
**Check my site** (Developers → Support) fetches your page and tells you if the snippet, its
integrity and the connection id are right.

## 3. Webhook [#3-webhook]

The signature covers the **raw bytes**, so this route takes `express.raw`, not `express.json`.

```js snippet=webhook
import { verifyWebhook } from '@gauge/support';

const handled = new Set(); // use your database in production: ids repeat on retries and resends

export async function gaugeWebhook(req, res) {
  const result = await verifyWebhook(process.env.GAUGE_WEBHOOK_SECRET, req.body, req.headers);
  if (!result.valid) return res.status(400).send(result.reason);
  const event = result.event;
  if (handled.has(event.id)) return res.sendStatus(200);
  handled.add(event.id);
  console.info('gauge', event.event, event.id, event.livemode ? 'live' : 'sandbox');
  // event.event is the type, event.payload the ids: e.g. push the user on support.chat.message_created
  res.sendStatus(200);
}
```

Wire both:

```js
import express from 'express';
import { gaugeToken } from './gauge-token.js';
import { gaugeWebhook } from './gauge-webhook.js';

const app = express();
app.get('/gauge-token', requireLogin, gaugeToken);                                  // your auth
app.post('/gauge/webhooks', express.raw({ type: 'application/json' }), gaugeWebhook);
app.listen(3000);
```

## 4. Check it [#4-check-it]

1. Sign in to your site as a test user (in the sandbox: **Seed test customers**, then sign in as
   `test_customer_1`), open the widget and send "hello". In the console the conversation shows the
   user's name and **Verified**. Not verified? Paste the JSON from `/gauge-token` into
   **Developers → Support → Token checker**: it names the rule that failed.
2. **Developers → Webhooks → your endpoint → Send test event**, pick `support.chat.message_created`:
   the result says *Delivered · 200* and your log shows the event id. Change one byte of the secret
   in your env and send again: your handler answers 400 `bad_signature`.

Server was down? **Replay failed** on the same page resends everything that did not land.


# Quick start: Go (`net/http`) (/support/quickstarts/go)

{/* GENERATED from docs/support/quickstarts/go.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
go get github.com/gauge-chat/pulse/packages/sdk-go
export GAUGE_APP_ID=<app id> GAUGE_IDENTITY_SECRET=<identity secret> GAUGE_WEBHOOK_SECRET=<whsec_…>
```

## 1 and 3. Two handlers [#1-and-3-two-handlers]

`userFrom(r)` is your auth: the signed-in user from your session middleware, or nil.

```go snippet=go
package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"
	"sync"

	gaugesupport "github.com/gauge-chat/pulse/packages/sdk-go"
)

func gaugeToken(w http.ResponseWriter, r *http.Request) {
	user := userFrom(r)
	if user == nil {
		http.Error(w, "sign in first", http.StatusUnauthorized)
		return
	}
	token, err := gaugesupport.MintToken(os.Getenv("GAUGE_IDENTITY_SECRET"), gaugesupport.MintInput{
		AppID:       os.Getenv("GAUGE_APP_ID"),
		UserID:      user.ID,
		Integration: "customer",
		Email:       user.Email,
	})
	if err != nil {
		http.Error(w, "could not mint", http.StatusInternalServerError)
		return
	}
	w.Header().Set("Cache-Control", "no-store")
	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(map[string]string{"token": token})
}

var handled sync.Map // use your database in production: ids repeat on retries and resends

// gaugeWebhook takes options only so tests can fix the clock; production passes none.
func gaugeWebhook(opts ...gaugesupport.WebhookOption) http.HandlerFunc {
	secrets := []string{os.Getenv("GAUGE_WEBHOOK_SECRET")}
	return func(w http.ResponseWriter, r *http.Request) {
		v, err := gaugesupport.VerifyWebhookRequest(r, secrets, opts...)
		if err != nil || !v.Valid {
			http.Error(w, v.Reason, http.StatusBadRequest)
			return
		}
		if v.Event != nil {
			if _, seen := handled.LoadOrStore(v.Event.ID, true); !seen {
				log.Printf("gauge %s %s", v.Event.Event, v.Event.ID)
			}
		}
		w.WriteHeader(http.StatusOK)
	}
}
```

```go
func main() {
	http.HandleFunc("GET /gauge-token", gaugeToken)
	http.HandleFunc("POST /gauge/webhooks", gaugeWebhook())
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

(`"GET /path"` patterns need Go 1.22; on 1.21 use plain paths and check `r.Method`.)

## 2. The widget (your page) [#2-the-widget-your-page]

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<chat connection id>',
      supportMode: true,
      integration: 'customer',
      getToken: function () { // called on every open, so the token is always fresh
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.
Signed-out visitors: leave out `getToken`; they chat anonymously where the Integration allows it.
**Check my site** (Developers → Support) fetches your page and tells you if the snippet, its
integrity and the connection id are right.

## 4. Check it [#4-check-it]

1. Sign in to your site as a test user (in the sandbox: **Seed test customers**, then sign in as
   `test_customer_1`), open the widget and send "hello". In the console the conversation shows the
   user's name and **Verified**. Not verified? Paste the JSON from `/gauge-token` into
   **Developers → Support → Token checker**: it names the rule that failed.
2. **Developers → Webhooks → your endpoint → Send test event**, pick `support.chat.message_created`:
   the result says *Delivered · 200* and your log shows the event id. Change one byte of the secret
   in your env and send again: your handler answers 400 `bad_signature`.

Server was down? **Replay failed** on the same page resends everything that did not land.


# Quick starts by stack (/support/quickstarts)

{/* GENERATED from docs/support/quickstarts/README.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

| Stack | Page | Server helper |
|---|---|---|
| Next.js (App Router) | [nextjs.md](/support/quickstarts/nextjs) | `@gauge/support` (npm) |
| Express | [express.md](/support/quickstarts/express) | `@gauge/support` (npm) |
| Django | [django.md](/support/quickstarts/django) | `gauge-support` (PyPI) |
| Laravel | [laravel.md](/support/quickstarts/laravel) | `gauge/support` (Composer) |
| Rails | [rails.md](/support/quickstarts/rails) | `gauge_support` (gem) |
| Go (`net/http`) | [go.md](/support/quickstarts/go) | `github.com/gauge-chat/pulse/packages/sdk-go` |

Mobile app instead? Flutter package and
[React Native, iOS and Android recipes](/support/webview-recipes). API only? [quickstart-api.md](/support/quickstart-api).

## Every page follows the same four steps [#every-page-follows-the-same-four-steps]

1. **Token endpoint.** `GET /gauge-token` on your server, behind your own login, returns
   `{ "token": "…" }`: a signed integration token for the signed-in user (HS256, ≤ 10 minutes). The
   identity secret stays on your server.
2. **Widget.** One script tag and `PulseWebchat.init({ …, getToken })`. The widget fetches a fresh
   token on every open.
3. **Webhook.** `POST /gauge/webhooks` verifies `x-pulse-signature` over the **raw** body, refuses
   anything more than 5 minutes old, and dedupes on the event `id`.
4. **Check it.** Send a chat message as a signed-in user: the conversation shows **Verified** in the
   console. Then **Developers → Webhooks → your endpoint → Send test event**: it lands signed, with a
   valid example payload for the event you picked, and your handler answers 200.

## What you need from the console [#what-you-need-from-the-console]

| Value | Where | Kept |
|---|---|---|
| App id | Apps → your App → Install | anywhere |
| Identity secret | Apps → your App → Install → Identity secret | server env only |
| Integration key | Apps → your App → Integrations (`customer`, `salon`, …) | anywhere |
| Chat connection id | Apps → your App → Install (it is in the widget snippet) | anywhere |
| Webhook signing secret | Developers → Webhooks → Add endpoint (shown once) | server env only |

Start in the **sandbox**: Developers → Support → pick *Sandbox*, then **Seed test customers** for
users you can sign in as on each Integration. Nothing there is billed or leaves Gauge.

## These snippets are tested [#these-snippets-are-tested]

Every block marked `snippet=…` on these pages is extracted and run in CI against its SDK
(`packages/sdk-*` test suites): the token it mints must verify, and its webhook handler must accept
the signed test deliveries in `packages/sdk-testvectors/webhook-test-event.json` (generated from the
Gauge server's own test sender) and refuse a tampered one. A page that drifts from its SDK turns a
suite red.


# Quick start: Laravel (/support/quickstarts/laravel)

{/* GENERATED from docs/support/quickstarts/laravel.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
composer require gauge/support
# .env
GAUGE_APP_ID=<app id>
GAUGE_IDENTITY_SECRET=<identity secret>
GAUGE_WEBHOOK_SECRET=<whsec_…>
```

## 1 and 3. One controller: `app/Http/Controllers/GaugeController.php` [#1-and-3-one-controller-apphttpcontrollersgaugecontrollerphp]

```php snippet=laravel
<?php

namespace App\Http\Controllers;

use Gauge\Support\Gauge;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

class GaugeController extends Controller
{
    public function token(Request $request)
    {
        $user = $request->user();
        $token = Gauge::mintToken(env('GAUGE_IDENTITY_SECRET'), env('GAUGE_APP_ID'), (string) $user->id, 'customer', [
            'name' => $user->name,
            'email' => $user->email,
        ]);
        return response()->json(['token' => $token])->header('Cache-Control', 'no-store');
    }

    public function webhook(Request $request)
    {
        $result = Gauge::verifyWebhook(env('GAUGE_WEBHOOK_SECRET'), $request->getContent(), $request->headers->all());
        if (!$result->valid) {
            return response($result->reason, 400);
        }
        $event = $result->event;
        // add() is false when the id is already there: retries and resends repeat it.
        if (Cache::add('gauge-event:' . $event['id'], true, now()->addDay())) {
            Log::info('gauge', ['event' => $event['event'], 'id' => $event['id']]);
        }
        return response('', 200);
    }
}
```

In production read the values through `config/services.php` rather than `env()` (config caching).
`routes/web.php`:

```php
use App\Http\Controllers\GaugeController;

Route::get('/gauge-token', [GaugeController::class, 'token'])->middleware('auth');
Route::post('/gauge/webhooks', [GaugeController::class, 'webhook'])
    ->withoutMiddleware([\Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class]);
```

## 2. The widget (your page) [#2-the-widget-your-page]

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<chat connection id>',
      supportMode: true,
      integration: 'customer',
      getToken: function () { // called on every open, so the token is always fresh
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.
Signed-out visitors: leave out `getToken`; they chat anonymously where the Integration allows it.
**Check my site** (Developers → Support) fetches your page and tells you if the snippet, its
integrity and the connection id are right.

## 4. Check it [#4-check-it]

1. Sign in to your site as a test user (in the sandbox: **Seed test customers**, then sign in as
   `test_customer_1`), open the widget and send "hello". In the console the conversation shows the
   user's name and **Verified**. Not verified? Paste the JSON from `/gauge-token` into
   **Developers → Support → Token checker**: it names the rule that failed.
2. **Developers → Webhooks → your endpoint → Send test event**, pick `support.chat.message_created`:
   the result says *Delivered · 200* and your log shows the event id. Change one byte of the secret
   in your env and send again: your handler answers 400 `bad_signature`.

Server was down? **Replay failed** on the same page resends everything that did not land.


# Quick start: Next.js (App Router) (/support/quickstarts/nextjs)

{/* GENERATED from docs/support/quickstarts/nextjs.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
npm install @gauge/support
# .env.local (server only: no NEXT_PUBLIC_ prefix, so none of these reach the browser)
GAUGE_APP_ID=<app id>
GAUGE_IDENTITY_SECRET=<identity secret>
GAUGE_WEBHOOK_SECRET=<whsec_…>
```

## 1. Token endpoint: `app/gauge-token/route.js` [#1-token-endpoint-appgauge-tokenroutejs]

`currentUser()` is your auth (NextAuth's `auth()`, Clerk's `currentUser()`, your session read).

```js snippet=next-mint
import { mintIntegrationToken } from '@gauge/support';
import { currentUser } from '@/lib/auth';

export const dynamic = 'force-dynamic';

export async function GET() {
  const user = await currentUser();
  if (!user) return Response.json({ error: 'sign in first' }, { status: 401 });
  const token = await mintIntegrationToken(process.env.GAUGE_IDENTITY_SECRET, {
    appId: process.env.GAUGE_APP_ID,
    userId: String(user.id),
    integration: 'customer',
    name: user.name,
    email: user.email,
  });
  return Response.json({ token }, { headers: { 'cache-control': 'no-store' } });
}
```

## 2. The widget (your page) [#2-the-widget-your-page]

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<chat connection id>',
      supportMode: true,
      integration: 'customer',
      getToken: function () { // called on every open, so the token is always fresh
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.
Signed-out visitors: leave out `getToken`; they chat anonymously where the Integration allows it.
**Check my site** (Developers → Support) fetches your page and tells you if the snippet, its
integrity and the connection id are right.

In a React tree, load it once from your root layout with `next/script` (`strategy="afterInteractive"`)
and call `PulseWebchat.init` in its `onLoad`.

## 3. Webhook: `app/gauge/webhooks/route.js` [#3-webhook-appgaugewebhooksroutejs]

Read the body with `request.text()`: the signature covers the exact bytes, so never `request.json()` first.

```js snippet=next-webhook
import { verifyWebhook } from '@gauge/support';

const handled = new Set(); // use your database in production: ids repeat on retries and resends

export async function POST(request) {
  const raw = await request.text();
  const result = await verifyWebhook(process.env.GAUGE_WEBHOOK_SECRET, raw, request.headers);
  if (!result.valid) return new Response(result.reason, { status: 400 });
  const event = result.event;
  if (!handled.has(event.id)) {
    handled.add(event.id);
    console.info('gauge', event.event, event.id, event.livemode ? 'live' : 'sandbox');
  }
  return new Response(null, { status: 200 });
}
```

## 4. Check it [#4-check-it]

1. Sign in to your site as a test user (in the sandbox: **Seed test customers**, then sign in as
   `test_customer_1`), open the widget and send "hello". In the console the conversation shows the
   user's name and **Verified**. Not verified? Paste the JSON from `/gauge-token` into
   **Developers → Support → Token checker**: it names the rule that failed.
2. **Developers → Webhooks → your endpoint → Send test event**, pick `support.chat.message_created`:
   the result says *Delivered · 200* and your log shows the event id. Change one byte of the secret
   in your env and send again: your handler answers 400 `bad_signature`.

Server was down? **Replay failed** on the same page resends everything that did not land.


# Quick start: Rails (/support/quickstarts/rails)

{/* GENERATED from docs/support/quickstarts/rails.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

```bash
bundle add gauge_support
export GAUGE_APP_ID=<app id> GAUGE_IDENTITY_SECRET=<identity secret> GAUGE_WEBHOOK_SECRET=<whsec_…>
```

## 1 and 3. One controller: `app/controllers/gauge_controller.rb` [#1-and-3-one-controller-appcontrollersgauge_controllerrb]

`current_user` is your auth (Devise or your own).

```ruby snippet=rails
class GaugeController < ApplicationController
  skip_forgery_protection only: :webhook # Gauge signs the request instead
  before_action :authenticate_user!, only: :token

  def token
    token = GaugeSupport.mint_token(
      ENV.fetch("GAUGE_IDENTITY_SECRET"),
      app_id: ENV.fetch("GAUGE_APP_ID"),
      user_id: current_user.id.to_s,
      integration: "customer",
      email: current_user.email
    )
    response.headers["Cache-Control"] = "no-store"
    render json: { token: token }
  end

  def webhook
    result = GaugeSupport.verify_webhook(ENV.fetch("GAUGE_WEBHOOK_SECRET"), request.raw_post, request.headers)
    return render(plain: result.reason, status: :bad_request) unless result.valid?

    event = result.event
    # write returns false when the id is already there (unless_exist): retries and resends repeat it.
    if Rails.cache.write("gauge-event:#{event["id"]}", true, unless_exist: true, expires_in: 1.day)
      Rails.logger.info("gauge #{event["event"]} #{event["id"]}")
    end
    head :ok
  end
end
```

`config/routes.rb`:

```ruby
get "/gauge-token", to: "gauge#token"
post "/gauge/webhooks", to: "gauge#webhook"
```

## 2. The widget (your page) [#2-the-widget-your-page]

```html
<script src="https://widget.gauge.chat/v1/<version>/widget.js"
  integrity="sha384-<integrity>" crossorigin="anonymous" async></script>
<script>
  window.addEventListener('load', function () {
    window.PulseWebchat.init({
      apiUrl: 'https://app.gauge.chat/backend',
      connectionId: '<chat connection id>',
      supportMode: true,
      integration: 'customer',
      getToken: function () { // called on every open, so the token is always fresh
        return fetch('/gauge-token', { credentials: 'include' })
          .then(function (r) { return r.json(); })
          .then(function (j) { return j.token; });
      },
    });
  });
</script>
```

CSP: `script-src https://widget.gauge.chat` and `connect-src https://app.gauge.chat wss://app.gauge.chat`.
Signed-out visitors: leave out `getToken`; they chat anonymously where the Integration allows it.
**Check my site** (Developers → Support) fetches your page and tells you if the snippet, its
integrity and the connection id are right.

## 4. Check it [#4-check-it]

1. Sign in to your site as a test user (in the sandbox: **Seed test customers**, then sign in as
   `test_customer_1`), open the widget and send "hello". In the console the conversation shows the
   user's name and **Verified**. Not verified? Paste the JSON from `/gauge-token` into
   **Developers → Support → Token checker**: it names the rule that failed.
2. **Developers → Webhooks → your endpoint → Send test event**, pick `support.chat.message_created`:
   the result says *Delivered · 200* and your log shows the event id. Change one byte of the secret
   in your env and send again: your handler answers 400 `bad_signature`.

Server was down? **Replay failed** on the same page resends everything that did not land.


# WebView recipes: React Native, iOS and Android (/support/webview-recipes)

{/* GENERATED from docs/support/webview-recipes.md by apps/docs/scripts/sync-support-docs.mjs. Edit the source, then run `pnpm support:sync`. */}

1. asks **your backend** for a fresh single-use link on every open (`POST /v1/support/sessions`,
   `target: "chat"`; any [quick start](/support/quickstarts) has the endpoint), and adds `embed=1`;
2. keeps navigation on your portal host and opens everything else in the system browser;
3. grants the microphone (in-app calls) and camera only to your portal host;
4. routes `<input type="file">` to the native picker and keeps the composer above the keyboard;
5. signs out by loading `/logout?embed=1` in the same WebView and closing on `/logout/done`.

No Gauge key or secret is in any of them. Background and the reasons behind each rule:
[mobile.md](/support/mobile).

Replace `https://api.yourapp.com/support/chat-link` with your own endpoint, and send your own auth.

---

## React Native (`react-native-webview` ≥ 13) [#react-native-react-native-webview--13]

```tsx
// SupportChat.tsx
import React, { useCallback, useEffect, useRef, useState } from 'react';
import { ActivityIndicator, Linking, PermissionsAndroid, Platform, Pressable, Text, View } from 'react-native';
import { SafeAreaView } from 'react-native-safe-area-context';
import WebView, { type WebViewNavigation } from 'react-native-webview';
import type { ShouldStartLoadRequest } from 'react-native-webview/lib/WebViewTypes';

async function fetchChatLink(appToken: string): Promise<string> {
  const res = await fetch('https://api.yourapp.com/support/chat-link', {
    headers: { authorization: `Bearer ${appToken}` },
  });
  if (!res.ok) throw new Error(`chat link: ${res.status}`);
  const { url } = (await res.json()) as { url: string };
  const link = new URL(url);
  if (link.protocol !== 'https:') throw new Error('chat link must be https');
  return url + (link.search ? '&' : '?') + 'embed=1'; // appended as text: the token stays byte-exact
}

export function SupportChat({ appToken, onSignedOut, signOutRequested }: {
  appToken: string;
  onSignedOut: () => void;
  /** Flip to true when the user signs out of your app while this screen is open. */
  signOutRequested?: boolean;
}) {
  const [link, setLink] = useState<string | null>(null);
  const [error, setError] = useState(false);
  const web = useRef<WebView>(null);
  const portalHost = link ? new URL(link).host : null;

  const open = useCallback(async () => {
    setError(false);
    setLink(null);
    try {
      if (Platform.OS === 'android') {
        // In-app calls need the microphone; the page asks only when the customer presses Call.
        await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.RECORD_AUDIO);
      }
      setLink(await fetchChatLink(appToken)); // fresh on every open: a link is single-use
    } catch {
      setError(true);
    }
  }, [appToken]);

  useEffect(() => { void open(); }, [open]);

  useEffect(() => {
    if (signOutRequested && portalHost) {
      web.current?.injectJavaScript(`location.assign('https://${portalHost}/logout?embed=1'); true;`);
    }
  }, [signOutRequested, portalHost]);

  const onShouldStart = (req: ShouldStartLoadRequest) => {
    const url = new URL(req.url);
    if (url.protocol === 'https:' && url.host === portalHost) return true;
    if (url.protocol === 'https:' || url.protocol === 'mailto:' || url.protocol === 'tel:') {
      if (req.isTopFrame) void Linking.openURL(req.url);
    }
    return false; // javascript:, intent:, file:, http: never load in the chat
  };

  const onNav = (nav: WebViewNavigation) => {
    if (portalHost && new URL(nav.url).host === portalHost && new URL(nav.url).pathname === '/logout/done') {
      onSignedOut();
    }
  };

  if (error) {
    return (
      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center', gap: 12 }}>
        <Text>Support chat didn't open.</Text>
        <Pressable onPress={open}><Text style={{ fontWeight: '600' }}>Try again</Text></Pressable>
      </View>
    );
  }
  if (!link) return <ActivityIndicator style={{ flex: 1 }} />;

  return (
    <SafeAreaView style={{ flex: 1 }} edges={['bottom', 'left', 'right']}>
      <WebView
        ref={web}
        source={{ uri: link }}
        originWhitelist={['https://*']}
        onShouldStartLoadWithRequest={onShouldStart}
        onNavigationStateChange={onNav}
        javaScriptEnabled
        domStorageEnabled
        thirdPartyCookiesEnabled={false}
        sharedCookiesEnabled={false}
        setSupportMultipleWindows={false}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserGesture={false}
        mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"
        allowFileAccess={false}
        onError={() => setError(true)}
      />
    </SafeAreaView>
  );
}
```

- Android manifest: `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`, `CAMERA` (if the picker offers it), and
  `android:windowSoftInputMode="adjustResize"`. Don't wrap the WebView in a `KeyboardAvoidingView`.
- iOS `Info.plist`: `NSMicrophoneUsageDescription`, `NSCameraUsageDescription`, `NSPhotoLibraryUsageDescription`.
- `react-native-webview` grants the page's microphone request on Android only when your app holds
  `RECORD_AUDIO`; `grantIfSameHostElsePrompt` does the same on iOS 15+.
- File inputs open the native picker on both platforms.

---

## iOS (`WKWebView`, Swift, iOS 15+) [#ios-wkwebview-swift-ios-15]

```swift
// SupportChatViewController.swift
import UIKit
import WebKit

final class SupportChatViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
    /// YOUR backend: returns { "url": "https://<portal>/auth/handoff?token=…" } for the signed-in user.
    var fetchChatLink: () async throws -> URL = { throw URLError(.userAuthenticationRequired) }
    var onSignedOut: () -> Void = {}

    private var webView: WKWebView!
    private var portalHost: String?

    override func viewDidLoad() {
        super.viewDidLoad()
        title = "Support"
        let config = WKWebViewConfiguration()
        config.websiteDataStore = .default()             // keeps the chat session across launches
        config.allowsInlineMediaPlayback = true          // the agent's call audio plays in place
        config.mediaTypesRequiringUserActionForPlayback = []
        webView = WKWebView(frame: .zero, configuration: config)
        webView.navigationDelegate = self
        webView.uiDelegate = self
        webView.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(webView)
        NSLayoutConstraint.activate([            // inside the safe area: nothing under the home indicator
            webView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            webView.bottomAnchor.constraint(equalTo: view.keyboardLayoutGuide.topAnchor),
            webView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            webView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
        ])
        open()
    }

    func open() {
        Task { @MainActor in
            do {
                let minted = try await fetchChatLink()   // fresh on every open: a link is single-use
                guard minted.scheme == "https", let host = minted.host else { throw URLError(.badURL) }
                portalHost = host
                var text = minted.absoluteString       // appended as text: the token stays byte-exact
                text += (minted.query == nil ? "?" : "&") + "embed=1"
                webView.load(URLRequest(url: URL(string: text)!))
            } catch {
                showRetry()
            }
        }
    }

    /// Call when the user signs out of your app with this screen open.
    func signOut() {
        guard let host = portalHost else { return }
        webView.load(URLRequest(url: URL(string: "https://\(host)/logout?embed=1")!))
    }

    // Navigation: your portal host only; the rest goes to the system.
    func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
        guard let url = action.request.url else { return decisionHandler(.cancel) }
        if url.scheme == "https", url.host == portalHost {
            if url.path == "/logout/done" { finishSignOut() }
            return decisionHandler(.allow)
        }
        if ["https", "mailto", "tel"].contains(url.scheme ?? ""), action.targetFrame?.isMainFrame != false {
            UIApplication.shared.open(url)
        }
        decisionHandler(.cancel)
    }

    // target=_blank links: never a second WebView.
    func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
                 for action: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
        if let url = action.request.url { UIApplication.shared.open(url) }
        return nil
    }

    // Microphone (in-app calls) and camera: your portal host only.
    func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin,
                 initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType,
                 decisionHandler: @escaping (WKPermissionDecision) -> Void) {
        decisionHandler(origin.protocol == "https" && origin.host == portalHost ? .grant : .deny)
    }

    func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) {
        showRetry()
    }

    private func finishSignOut() {
        WKWebsiteDataStore.default().removeData(ofTypes: WKWebsiteDataStore.allWebsiteDataTypes(),
                                                modifiedSince: .distantPast) { [weak self] in
            self?.onSignedOut()
        }
    }

    private func showRetry() {
        let alert = UIAlertController(title: "Support chat didn't open",
                                      message: "Check your connection and try again.", preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "Try again", style: .default) { [weak self] _ in self?.open() })
        present(alert, animated: true)
    }
}
```

`Info.plist`: `NSMicrophoneUsageDescription`, `NSCameraUsageDescription`, `NSPhotoLibraryUsageDescription`.
`<input type="file">` presents the system picker by itself. No `WKScriptMessageHandler` is added:
the page needs no bridge into your app.

---

## Android (`WebView`, Kotlin) [#android-webview-kotlin]

```kotlin
// SupportChatActivity.kt
import android.Manifest
import android.annotation.SuppressLint
import android.content.Intent
import android.net.Uri
import android.os.Bundle
import android.webkit.*
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AlertDialog
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch

class SupportChatActivity : AppCompatActivity() {
    private lateinit var web: WebView
    private var portalHost: String? = null
    private var fileCallback: ValueCallback<Array<Uri>>? = null

    private val pickFile = registerForActivityResult(ActivityResultContracts.GetContent()) { uri ->
        fileCallback?.onReceiveValue(if (uri == null) emptyArray() else arrayOf(uri))
        fileCallback = null
    }
    private val askMic = registerForActivityResult(ActivityResultContracts.RequestPermission()) { open() }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        web = WebView(this)
        setContentView(web) // manifest: android:windowSoftInputMode="adjustResize"
        with(web.settings) {
            javaScriptEnabled = true
            domStorageEnabled = true
            mediaPlaybackRequiresUserGesture = false
            allowFileAccess = false
            allowContentAccess = true          // the picker hands back content:// URIs
            setSupportMultipleWindows(false)
        }
        CookieManager.getInstance().setAcceptThirdPartyCookies(web, false)
        web.webViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
                val url = request.url
                if (url.scheme == "https" && url.host == portalHost) {
                    if (url.path == "/logout/done") finishSignOut()
                    return false
                }
                if (request.isForMainFrame && url.scheme in setOf("https", "mailto", "tel")) {
                    startActivity(Intent(Intent.ACTION_VIEW, url))
                }
                return true // javascript:, intent:, file:, http: never load in the chat
            }

            override fun onReceivedError(view: WebView, request: WebResourceRequest, error: WebResourceError) {
                if (request.isForMainFrame) showRetry()
            }
        }
        web.webChromeClient = object : WebChromeClient() {
            // Microphone (in-app calls) and camera: your portal host only, nothing else.
            override fun onPermissionRequest(request: PermissionRequest) {
                val allowed = setOf(PermissionRequest.RESOURCE_AUDIO_CAPTURE, PermissionRequest.RESOURCE_VIDEO_CAPTURE)
                val fromPortal = request.origin.scheme == "https" && request.origin.host == portalHost
                if (fromPortal && request.resources.all { it in allowed }) request.grant(request.resources)
                else request.deny()
            }

            override fun onShowFileChooser(view: WebView, callback: ValueCallback<Array<Uri>>,
                                           params: FileChooserParams): Boolean {
                fileCallback?.onReceiveValue(null)
                fileCallback = callback
                pickFile.launch(params.acceptTypes.firstOrNull { it.isNotBlank() } ?: "*/*")
                return true
            }
        }
        askMic.launch(Manifest.permission.RECORD_AUDIO) // the page asks only when the customer presses Call
    }

    private fun open() = lifecycleScope.launch {
        try {
            val minted = Uri.parse(fetchChatLink())  // YOUR backend; fresh on every open
            require(minted.scheme == "https" && minted.host != null)
            portalHost = minted.host
            val text = minted.toString()            // appended as text: the token stays byte-exact
            web.loadUrl(text + (if (minted.query == null) "?" else "&") + "embed=1")
        } catch (e: Exception) {
            showRetry()
        }
    }

    /** Call when the user signs out of your app with this screen open. */
    fun signOut() {
        portalHost?.let { web.loadUrl("https://$it/logout?embed=1") }
    }

    private fun finishSignOut() {
        CookieManager.getInstance().removeAllCookies(null)
        WebStorage.getInstance().deleteAllData()
        finish()
    }

    private fun showRetry() {
        AlertDialog.Builder(this)
            .setTitle("Support chat didn't open")
            .setMessage("Check your connection and try again.")
            .setPositiveButton("Try again") { _, _ -> open() }
            .show()
    }

    /** YOUR backend call (OkHttp, Ktor, Retrofit…): GET /support/chat-link with your app's auth → "url". */
    private suspend fun fetchChatLink(): String = TODO("call your backend")
}
```

Manifest: `INTERNET`, `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`, `CAMERA` (if the picker should offer it),
and `android:windowSoftInputMode="adjustResize"` on the activity. No `addJavascriptInterface`: the
page needs no bridge into your app. Edge-to-edge apps: pad the WebView by the system-bar insets
(`ViewCompat.setOnApplyWindowInsetsListener`) so the composer never sits under the navigation bar.

---

## Check it [#check-it]

Open the screen as a test user, send a message, and confirm in the console that the conversation
shows your user's name. Then sign out: the screen should close on `/logout/done`, and opening it
again should mint a new link (one link never opens twice).


# Delivery, retries and ordering (/webhooks/delivery)

## Success and failure [#success-and-failure]

A delivery **succeeds** when your endpoint answers any `2xx` status within **10 seconds**. Everything
else is a failure and is retried:

- any other status, including `3xx`: Gauge never follows redirects, because the URL you registered
  is the one that was checked;
- no answer within 10 seconds;
- a connection, DNS or TLS error.

Each endpoint's delivery log in **Developers → Webhooks** shows every attempt, with the status or
the reason it failed ("Timed out after 10 s", "HTTP 503") and an excerpt of your response.

## Retries [#retries]

A failed delivery is retried on this schedule, then marked **dead**:

| Attempt | When |
| --- | --- |
| 1 | Immediately |
| 2 | 30 seconds after attempt 1 failed |
| 3 | 5 minutes later |
| 4 | 1 hour later |
| 5 | 6 hours later |
| | Then dead: no more automatic attempts |

So an event survives a little over seven hours of downtime on its own. For a longer outage,
[replay](/webhooks/testing-and-replay#replay-failed-deliveries) the dead deliveries once you are back.

## Endpoints that keep failing are switched off [#endpoints-that-keep-failing-are-switched-off]

An endpoint whose deliveries have **all** failed for **3 days** in a row (no success since its first
failure) is disabled automatically: it gets `enabled: false` and
`disabledReason: "consecutive_failures"`, and the member who owns it is told in the app and by
email. One successful delivery at any point resets the count.

While it is off, nothing is delivered to it. Fix the receiver, then switch it back on in the
console or with `PATCH /v2/webhook-endpoints/{id}` `{ "enabled": true }` (which clears
`disabledReason`), and [replay](/webhooks/testing-and-replay) what you missed: events are kept for
30 days.

## Headers [#headers]

Every delivery is a `POST` with `Content-Type: application/json` and:

| Header | |
| --- | --- |
| `Gauge-Signature` | `t=<epoch ms>,v1=<hex>`. See [Verify signatures](/webhooks/verify-signatures). |
| `Gauge-Event-Id` | The event id, the same as the body's `id`. Dedupe on it. |
| `Gauge-Event-Type` | The event name, e.g. `message.received`. |
| `Gauge-Delivery-Attempt` | `1` on the first try, then `2`, `3`, … across retries and redeliveries. |
| `Gauge-Webhook-Id` | The endpoint's id. |
| `x-pulse-signature`, `x-pulse-timestamp`, `x-pulse-event` | Legacy copies of the signature, `t` and event name, for receivers written before API v2. |

## Size [#size]

A body is at most **64 KB**. A longer message's `text` is cut, with `truncated: true` and a
`fetchUrl` to read it in full; see [Large messages](/webhooks/events#large-messages).

## Deduplicate on the event id [#deduplicate-on-the-event-id]

The same event can reach you **more than once**: a retry after your server processed the event but
timed out answering, a manual resend, or a replay. Every copy carries the **same `id`**.

Record the ids you have processed and skip any you have seen. Keep them for at least a few days,
longer than the retry schedule.

```sql
-- One way: a unique key, and treat a conflict as "already handled".
CREATE TABLE gauge_events_seen (id text PRIMARY KEY, received_at timestamptz NOT NULL DEFAULT now());
INSERT INTO gauge_events_seen (id) VALUES ($1) ON CONFLICT (id) DO NOTHING RETURNING id;
-- No row returned → a duplicate. Answer 2xx and do nothing.
```

## Ordering [#ordering]

**Deliveries are not guaranteed to arrive in the order the events happened.** Events are sent in
parallel, and a failed delivery is retried later while newer ones go through.

- Use `occurredAt` to order events about the same thing, and ignore an update older than what you
  already have.
- For anything where the latest state matters, treat the event as a signal and **fetch the current
  state** from the API by `entityId`.

## Answer fast [#answer-fast]

Your endpoint has 10 seconds, and Gauge waits for each answer. Verify the signature, store the
event (or put it on a queue), answer `2xx`, then do the slow work. An endpoint that does its work
inline risks timeouts, and every timeout becomes a retry.

## Security [#security]

- Use an `https` URL: deliveries carry your customers' data. Only addresses on the public internet
  are accepted; private, loopback and link-local addresses (and cloud metadata endpoints) are
  refused, both when you save the endpoint and again when Gauge connects.
- Verify the [signature](/webhooks/verify-signatures) on every delivery.
- Keep the signing secret on your server, and rotate it if it may have leaked.


# Event catalogue (/webhooks/events)

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 [#messaging-events]

<Status is="live" />

Delivered 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](/reference): ids first, then a minimal
snapshot. Every event's full schema is listed under **Webhooks** there.

### Who receives them [#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 [#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](/webhooks/inbound-messages). |
| `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 [#messagereceived]

`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 [#messagesent]

`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 [#messagestatus_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 [#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 [#conversationcreated]

`conversation` (snapshot: `id`, `status`, `connection`, `contactId`, `assigneeId`, `teamId`,
`topicId`, `app`, `createdAt`), `contact`, `initiatedBy` (`contact` or `business`).

#### conversation.updated [#conversationupdated]

`conversation` (the snapshot after the change) and `changes`: `["status"]` or `["assignment"]`.
Tag, priority and read changes do not raise it.

### Contacts [#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 [#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 <Status is="soon" />: `sms.received`, `sms.status_updated`,
`call.completed`, `call.recording_ready`, `voicemail.received`.

## Support events [#support-events]

<Status is="live" />

Delivered today, for the [Support API](/support): 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`](/reference/webhooks/webhook_support_callback_cancelled), [`completed`](/reference/webhooks/webhook_support_callback_completed), [`failed`](/reference/webhooks/webhook_support_callback_failed), [`requested`](/reference/webhooks/webhook_support_callback_requested), [`scheduled`](/reference/webhooks/webhook_support_callback_scheduled) |
| Chat (`support.chat.*`) | [`answered`](/reference/webhooks/webhook_support_chat_answered), [`ended`](/reference/webhooks/webhook_support_chat_ended), [`handoff_to_ticket`](/reference/webhooks/webhook_support_chat_handoff_to_ticket), [`message_created`](/reference/webhooks/webhook_support_chat_message_created), [`offered`](/reference/webhooks/webhook_support_chat_offered), [`ownership_changed`](/reference/webhooks/webhook_support_chat_ownership_changed), [`queued`](/reference/webhooks/webhook_support_chat_queued), [`session_started`](/reference/webhooks/webhook_support_chat_session_started), [`unclaimed`](/reference/webhooks/webhook_support_chat_unclaimed) |
| Customers (`support.customer.*`) | [`access_granted`](/reference/webhooks/webhook_support_customer_access_granted), [`access_revoked`](/reference/webhooks/webhook_support_customer_access_revoked), [`blocked`](/reference/webhooks/webhook_support_customer_blocked), [`created`](/reference/webhooks/webhook_support_customer_created), [`deactivated`](/reference/webhooks/webhook_support_customer_deactivated), [`unblocked`](/reference/webhooks/webhook_support_customer_unblocked), [`unread_changed`](/reference/webhooks/webhook_support_customer_unread_changed), [`updated`](/reference/webhooks/webhook_support_customer_updated), [`verified`](/reference/webhooks/webhook_support_customer_verified) |
| Knowledge base (`support.kb.*`) | [`article_published`](/reference/webhooks/webhook_support_kb_article_published), [`article_unpublished`](/reference/webhooks/webhook_support_kb_article_unpublished), [`deflected`](/reference/webhooks/webhook_support_kb_deflected) |
| Meetings (`support.meeting.*`) | [`cancelled`](/reference/webhooks/webhook_support_meeting_cancelled), [`created`](/reference/webhooks/webhook_support_meeting_created), [`ended`](/reference/webhooks/webhook_support_meeting_ended), [`participant_joined`](/reference/webhooks/webhook_support_meeting_participant_joined), [`started`](/reference/webhooks/webhook_support_meeting_started) |
| Apps (projects) (`support.project.*`) | [`branding_updated`](/reference/webhooks/webhook_support_project_branding_updated), [`created`](/reference/webhooks/webhook_support_project_created), [`updated`](/reference/webhooks/webhook_support_project_updated) |
| Sign-in links (`support.session_link.*`) | [`created`](/reference/webhooks/webhook_support_session_link_created), [`redeemed`](/reference/webhooks/webhook_support_session_link_redeemed), [`revoked`](/reference/webhooks/webhook_support_session_link_revoked) |
| Tickets (`support.ticket.*`) | [`assigned`](/reference/webhooks/webhook_support_ticket_assigned), [`created`](/reference/webhooks/webhook_support_ticket_created), [`escalated`](/reference/webhooks/webhook_support_ticket_escalated), [`escalation_acknowledged`](/reference/webhooks/webhook_support_ticket_escalation_acknowledged), [`merged`](/reference/webhooks/webhook_support_ticket_merged), [`replied`](/reference/webhooks/webhook_support_ticket_replied), [`sla_breached`](/reference/webhooks/webhook_support_ticket_sla_breached), [`split`](/reference/webhooks/webhook_support_ticket_split), [`status_changed`](/reference/webhooks/webhook_support_ticket_status_changed), [`tier_changed`](/reference/webhooks/webhook_support_ticket_tier_changed), [`updated`](/reference/webhooks/webhook_support_ticket_updated) |
| Support calls (`support.voice.*`) | [`abandoned`](/reference/webhooks/webhook_support_voice_abandoned), [`answered`](/reference/webhooks/webhook_support_voice_answered), [`ended`](/reference/webhooks/webhook_support_voice_ended), [`queued`](/reference/webhooks/webhook_support_voice_queued) |

## Payloads [#payloads]

Every event shares the [envelope](/webhooks#what-a-delivery-looks-like); `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 [#the-test-event]

`webhook.test` is sent only when you choose **Send test event**. It carries `"test": true`.
See [Testing and replay](/webhooks/testing-and-replay).


# Forward inbound messages (/webhooks/inbound-messages)

<Status is="live" />

The most common integration: every time a customer writes to you on any connected channel, your
own system hears about it. Route it to the right team, log it in your CRM, trigger a workflow, or
hand it to your own bot.

## 1. Subscribe [#1-subscribe]

Create an endpoint in **Developers → Webhooks**, or with
[`POST /v2/webhook-endpoints`](/webhooks#manage-endpoints-from-code), subscribed to
`message.received`. Add `message.status_updated` too if you send messages and want to know when
they are delivered.

The endpoint receives the conversations **its owner** can see: create it as (or with a key of) a
member who sees every conversation if you want them all. Over the API, the key also needs
`messages:read` to subscribe to message events.

## 2. Receive [#2-receive]

```json
{
  "id": "evt_6b1c4e3d8a5f0c9b2d4e6f81",
  "event": "message.received",
  "livemode": true,
  "workspaceId": "a3b5c7d9-1e2f-4a6b-8c0d-2e4f6a8b0c1d",
  "entity": "message",
  "entityId": "7d2e9f4a-6b1c-4e3d-8a5f-0c9b2d4e6f81",
  "occurredAt": "2026-10-21T10:02:37.118Z",
  "payload": {
    "messageId": "7d2e9f4a-6b1c-4e3d-8a5f-0c9b2d4e6f81",
    "conversationId": "c41e7b2a-5d6f-4e8a-9b1c-3d5e7f9a1b2c",
    "connection": { "id": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f", "channel": "whatsapp", "kind": "whatsapp_cloud" },
    "contact": {
      "id": "e8f1a3c5-7b9d-4f2a-8c4e-6a8b0d2f4a6c",
      "name": "Layla Haddad",
      "identities": [{ "channel": "whatsapp_cloud", "externalId": "447700900123" }]
    },
    "kind": "image",
    "text": "Hi, can I move my appointment to Thursday? Here is my booking.",
    "media": [
      {
        "index": 0,
        "url": "/v2/messages/7d2e9f4a-6b1c-4e3d-8a5f-0c9b2d4e6f81/attachments/0",
        "mediaId": null,
        "contentType": "image/jpeg",
        "size": 183402,
        "filename": null,
        "available": true
      }
    ],
    "reply": null,
    "quotedMessageId": null,
    "app": null,
    "receivedAt": "2026-10-21T10:02:37.118Z"
  }
}
```

The payload is a **snapshot** with the ids you need, the text, and the customer's handles. For the
full contact or the conversation history, call the API with those ids.

**Files.** To fetch an attachment, `GET` its `url` with a key that has `messages:read`
(`https://app.gauge.chat/backend` + `url`). The answer's `download.url` is a signed link valid for
5 minutes: fetch the bytes from it right away rather than storing it. `available: false` means
Gauge holds no copy (`url` answers `404`). See
[Download a message's file](/messaging/messages#download-a-messages-file).

**Long messages.** A body over 64 KB arrives with `text` cut to 4,096 characters,
`"truncated": true` and `"fetchUrl": "/v2/messages/{id}"`. Fetch the full message from there.

## 3. Handle it safely [#3-handle-it-safely]

```js title="inbound.js"
import express from 'express';
import { verifyGaugeSignature } from './verify-gauge-signature.js';
import { seenBefore, enqueue } from './store.js';

const app = express();

app.post('/gauge/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  // 1. Is it from Gauge? Check the raw bytes.
  if (!verifyGaugeSignature(req.headers, req.body, process.env.GAUGE_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body);

  // 2. Already handled? Retries and replays reuse the event id.
  if (await seenBefore(event.id)) return res.sendStatus(204);

  // 3. Hand it off and answer at once. Gauge waits at most 10 seconds.
  await enqueue(event);
  res.sendStatus(204);
});

app.listen(3000);
```

Then, in your worker:

- **Skip test events** (`event.test === true`) and, in production, sandbox events
  (`event.livemode === false`).
- **Order by `occurredAt`** within a conversation: deliveries can arrive out of order.
- **Do not reply from inside the webhook handler.** Reply from your worker with
  [`POST /v2/messages`](/messaging/messages) and an `Idempotency-Key` derived from the inbound
  event (`reply-to-${event.id}`), so a retried event never produces a second reply.

## Avoid loops [#avoid-loops]

`message.received` fires for messages **from customers**. Your own replies, including those sent
through the API, raise `message.sent`, not `message.received`, so a bot that answers every
`message.received` does not answer itself.

## What arrives, per channel [#what-arrives-per-channel]

| Channel | Arrives as `message.received` |
| --- | --- |
| WhatsApp Cloud API, WhatsApp Web | Yes: text, media, locations, contacts, and button or list replies (`reply`) |
| Email | Yes: one event per inbound email |
| Web chat | Yes: each visitor message |
| Instagram, Messenger | Yes: direct messages |
| SMS | Later: `sms.received`, with SMS over the API |


# Webhooks (/webhooks)

<Status is="live" />

Instead of polling, give Gauge a URL. When something happens in your workspace (a ticket is
created, a chat is answered, a customer message arrives) Gauge sends a signed `POST` to
that URL within seconds, and keeps retrying if your server is down.

## Set up an endpoint [#set-up-an-endpoint]

1. Open **Developers → Webhooks** in the console and choose **Add endpoint**.
2. Enter an **HTTPS** URL on your server.
3. Choose the **events** to subscribe to: an exact name (`support.ticket.created`), a family
   (`support.ticket.*`), or `*` for every public event.
4. Copy the **signing secret**. It is shown once; Gauge stores it to sign, and you store it to
   verify.
5. Choose **Send test event** and check that your endpoint answers `2xx`.

You can pause an endpoint, change its URL or events, and rotate its secret at any time from the
same screen.

## Manage endpoints from code [#manage-endpoints-from-code]

The same endpoints, over the API (live keys only; a key pinned to an App manages only that App's
endpoints):

| Endpoint | Scope | |
| --- | --- | --- |
| `GET /v2/webhook-endpoints` | `webhooks:read` | List endpoints |
| `POST /v2/webhook-endpoints` | `webhooks:write` | Create one. The answer carries the signing `secret`, **once** |
| `GET /v2/webhook-endpoints/{id}` | `webhooks:read` | One endpoint, with its last delivery and 24 h success rate |
| `PATCH /v2/webhook-endpoints/{id}` | `webhooks:write` | Change `url`, `events`, `connectionIds`, `projectId`, `apiVersion`, `enabled` |
| `DELETE /v2/webhook-endpoints/{id}` | `webhooks:write` | Delete it |
| `POST /v2/webhook-endpoints/{id}/rotate-secret` | `webhooks:write` | New secret, once; `overlapHours` `24` (default) or `0` |
| `POST /v2/webhook-endpoints/{id}/test` | `webhooks:write` | Send a signed sample of an `event` (default `webhook.test`) |
| `GET /v2/webhook-endpoints/{id}/deliveries` | `webhooks:read` | Its delivery log |
| `GET /v2/events`, `GET /v2/events/{id}` | `events:read` | The last 30 days of events, with the exact body delivered |
| `POST /v2/events/{id}/redeliver` | `webhooks:write` | Send an event again |

```bash
curl https://app.gauge.chat/backend/v2/webhook-endpoints \
  -H "Authorization: Bearer $GAUGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-endpoint-orders" \
  -d '{ "url": "https://example.com/gauge/webhooks", "events": ["message.received", "message.status_updated"] }'
```

Subscribing to message or conversation events needs the key to also hold `messages:read` /
`conversations:read`, and contact events `contacts:read`; otherwise `403 insufficient_scope`. An
endpoint created with a key belongs to the key's member and receives what that member can see.
New endpoints are created on the current API version (`2026-10-21`).

## What a delivery looks like [#what-a-delivery-looks-like]

```http
POST /gauge/webhooks HTTP/1.1
Content-Type: application/json
Gauge-Signature: t=1792578071424,v1=5f2b8c0e9d4a7b1c3e6f8a2d4b9c7e1f0a3d5b8c2e4f6a9b1d3c5e7f9a2b4c6d
Gauge-Event-Id: 48213907
Gauge-Event-Type: support.ticket.created
Gauge-Delivery-Attempt: 1
Gauge-Webhook-Id: 4c2a6e8f-0b1d-4f3a-9c5e-7a9b1d3f5a7c
x-pulse-event: support.ticket.created
x-pulse-timestamp: 1792578071424
x-pulse-signature: sha256=5f2b8c0e9d4a7b1c3e6f8a2d4b9c7e1f0a3d5b8c2e4f6a9b1d3c5e7f9a2b4c6d
```

```json
{
  "id": "48213907",
  "event": "support.ticket.created",
  "livemode": true,
  "workspaceId": "a3b5c7d9-1e2f-4a6b-8c0d-2e4f6a8b0c1d",
  "entity": "support_ticket",
  "entityId": "5e7c9a1b-3d5f-4b7d-9f1a-3c5e7a9b1d3f",
  "occurredAt": "2026-10-21T09:41:11.424Z",
  "payload": { "…": "the event's own fields, see the catalogue" }
}
```

| Field | |
| --- | --- |
| `id` | The event id: `evt_…` for message, conversation and contact events, a number for support events. **The same on every retry and every manual resend.** Deduplicate on it. |
| `event` | The event name, also in the `Gauge-Event-Type` header. |
| `livemode` | `false` when the event is about sandbox data (a test App), else `true`. |
| `workspaceId` | Your workspace. |
| `entity`, `entityId` | What the event is about. |
| `occurredAt` | When it happened (ISO 8601, UTC). |
| `payload` | The event's fields, defined per event in the [catalogue](/webhooks/events). |

Payloads carry ids and the facts of the event, never secrets or internal routing data. Fetch the
full resource from the API when you need more.

## Your endpoint's job [#your-endpoints-job]

1. **Verify the signature** against the raw body. [How](/webhooks/verify-signatures).
2. **Answer `2xx` quickly**, within 10 seconds, before doing slow work. Anything else (an error, a
   redirect, a timeout) counts as a failure and is retried.
3. **Deduplicate on `id`**, because a delivery can arrive more than once.
4. **Do not rely on order.** [Why](/webhooks/delivery#ordering).


# Testing and replay (/webhooks/testing-and-replay)

## Send a test event [#send-a-test-event]

On an endpoint in **Developers → Webhooks**, choose **Send test event** and pick an event type.

- The test is a real delivery: same envelope, same headers, signed with the endpoint's real secret.
  If your verification passes on it, it will pass on real events.
- Its `payload` is a valid example of the event you picked, so your real handler runs on it end to
  end. Pick nothing and you get the neutral `webhook.test` ping.
- It is marked `"test": true`, on the envelope and in the payload, so your handler can recognise it
  and skip side effects.
- The result (status, latency, your response) appears at once in the delivery log.

## Local development [#local-development]

Your laptop is not on the public internet, so Gauge cannot reach `localhost`. Use a tunnel that
gives you a public HTTPS URL for a local port (for example `cloudflared tunnel --url http://localhost:3000`
or `ngrok http 3000`) and register that URL as a separate endpoint. Delete it when you are done.

Use a [test key](/authentication#environments) and a sandbox App while developing: events about
sandbox data arrive with `"livemode": false`.

## Resend one delivery [#resend-one-delivery]

Open any delivery in the log and choose **Resend**. Gauge sends it again as a new delivery, with
the **same event `id`**, so your deduplication still works.

## Replay failed deliveries [#replay-failed-deliveries]

After an outage, replay everything that did not land: on the endpoint, choose **Replay failed** and
pick a start time.

- Every delivery that failed or went dead since then is sent again, newest first, as new
  deliveries with their original event ids.
- At most **100** deliveries per replay, and the start time can be up to **7 days** back. If more
  than 100 qualify, the result says so: run it again for the rest.
- Deliveries already resent are skipped.
- A workspace can run **20 replays an hour**, shared with `POST /v2/events/{id}/redeliver`.

## From code: the event log [#from-code-the-event-log]

Every event delivered to an endpoint on API version `2026-10-21` or later is kept for **30 days**,
with the exact body that was (or would be) delivered.

- `GET /v2/events` (scope `events:read`) lists them, newest first, filtered by `type` (an exact
  name or `family.*`), `since` (ISO time) and `conversationId`. Message and conversation events are
  listed only for conversations the key's member can see.
- `GET /v2/events/{id}` returns one, as `{ id, type, conversationId, createdAt, data }`, where
  `data` is the envelope.
- `POST /v2/events/{id}/redeliver` (scope `webhooks:write`, with an `Idempotency-Key`) sends it again,
  as a new delivery with the same event `id`, to every endpoint that received it, or to one with
  `{ "endpointId": "…" }`. The answer is `{ "redelivered": 1, "deliveries": [{ "id", "endpointId" }] }`.

Redelivery spends the **same budget as Replay in the console: 20 an hour per workspace**. Over it,
`429 rate_limited` with reason `webhook_replay_limit`.

`POST /v2/webhook-endpoints/{id}/test` sends a test event from code, exactly like **Send test event**.


# Verify signatures (/webhooks/verify-signatures)

Anyone can POST to your endpoint. The signature proves a delivery came from Gauge, unmodified, and
recently. **Verify every delivery before acting on it.**

## The scheme [#the-scheme]

Gauge signs the string `<t>.<raw body>` with **HMAC-SHA256**, keyed with your endpoint's signing
secret, where `t` is the send time in **epoch milliseconds**. Every delivery to every endpoint
carries the signature twice, the same HMAC in two formats:

| Header | Value |
| --- | --- |
| `Gauge-Signature` | `t=<epoch ms>,v1=<hex>`: the timestamp and the signature in one header. Verify this one. |
| `x-pulse-signature` | Legacy: `sha256=<hex>`. Kept for receivers written before API v2. |
| `x-pulse-timestamp` | Legacy: `t`, epoch milliseconds. |

A delivery also carries `Gauge-Event-Id`, `Gauge-Event-Type`, `Gauge-Delivery-Attempt` and
`Gauge-Webhook-Id` (see [Delivery](/webhooks/delivery#headers)). The snippets below accept either
signature format, so code written against the legacy pair keeps working.

**During a secret rotation**, a delivery carries **two** signatures, one per secret, new first
(`t=…,v1=<new>,v1=<old>`, and `sha256=<new>,sha256=<old>`). Accept the delivery if **any** of them
verifies.

## The rules [#the-rules]

1. **Use the raw body**, the exact bytes received. Parsing the JSON and re-serialising it changes
   the bytes and breaks the signature. In Express, use `express.raw()` on the webhook route; in
   Django, `request.body`; in Laravel, `$request->getContent()`.
2. **Use the timestamp string exactly as sent** in the signed string.
3. **Compare in constant time** (`timingSafeEqual`, `hmac.compare_digest`, `hash_equals`), never
   with `==`.
4. **Reject old deliveries:** more than **5 minutes** from your clock. This stops a captured
   delivery from being replayed later. Keep your server's clock in sync (NTP).
5. Answer `400` to a delivery that fails verification, and do not process it.

## Node [#node]

```js title="verify-gauge-signature.js"
import crypto from 'node:crypto';

const TOLERANCE_MS = 5 * 60 * 1000;

/**
 * @param {Record<string, string | string[] | undefined>} headers  lower-cased (Node does this)
 * @param {Buffer} rawBody  the exact bytes received
 * @param {string} secret   the endpoint's signing secret
 */
export function verifyGaugeSignature(headers, rawBody, secret, now = Date.now()) {
  const header = (name) => [headers[name]].flat()[0] ?? '';
  let timestamp = '';
  let signatures = [];

  if (header('gauge-signature')) {
    for (const part of header('gauge-signature').split(',')) {
      const [key, value = ''] = part.trim().split('=', 2);
      if (key === 't') timestamp = value;
      else if (key === 'v1') signatures.push(value);
    }
  } else {
    timestamp = header('x-pulse-timestamp');
    signatures = header('x-pulse-signature')
      .split(',')
      .map((s) => s.trim().replace(/^sha256=/, ''))
      .filter(Boolean);
  }
  if (!/^\d+$/.test(timestamp) || signatures.length === 0) return false;

  // `t` is epoch milliseconds.
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_MS) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();
  return signatures.some((sig) => {
    const given = Buffer.from(sig, 'hex');
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}
```

Use it with the raw body:

```js
app.post('/gauge/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyGaugeSignature(req.headers, req.body, process.env.GAUGE_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(204);
  // …handle `event` after answering
});
```

## Python [#python]

```python title="verify_gauge_signature.py"
import hashlib
import hmac
import time

TOLERANCE_MS = 5 * 60 * 1000


def verify_gauge_signature(headers, raw_body: bytes, secret: str, now_ms=None) -> bool:
    h = {k.lower(): v for k, v in headers.items()}
    timestamp, signatures = "", []

    if h.get("gauge-signature"):
        for part in h["gauge-signature"].split(","):
            key, _, value = part.strip().partition("=")
            if key == "t":
                timestamp = value
            elif key == "v1":
                signatures.append(value)
    else:
        timestamp = h.get("x-pulse-timestamp", "")
        signatures = [
            s.strip()[len("sha256="):] if s.strip().startswith("sha256=") else s.strip()
            for s in h.get("x-pulse-signature", "").split(",")
            if s.strip()
        ]
    if not timestamp.isdigit() or not signatures:
        return False

    # `t` is epoch milliseconds.
    now_ms = int(time.time() * 1000) if now_ms is None else now_ms
    if abs(now_ms - int(timestamp)) > TOLERANCE_MS:
        return False

    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, sig) for sig in signatures)
```

In Django: `verify_gauge_signature(request.headers, request.body, settings.GAUGE_WEBHOOK_SECRET)`.
In Flask: `verify_gauge_signature(request.headers, request.get_data(), secret)`.

## PHP [#php]

```php title="verify_gauge_signature.php"
<?php

function verify_gauge_signature(array $headers, string $rawBody, string $secret, ?int $nowMs = null): bool
{
    $h = array_change_key_case($headers, CASE_LOWER);
    $timestamp = '';
    $signatures = [];

    if (!empty($h['gauge-signature'])) {
        foreach (explode(',', $h['gauge-signature']) as $part) {
            [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
            if ($key === 't') {
                $timestamp = $value;
            } elseif ($key === 'v1') {
                $signatures[] = $value;
            }
        }
    } else {
        $timestamp = $h['x-pulse-timestamp'] ?? '';
        foreach (explode(',', $h['x-pulse-signature'] ?? '') as $sig) {
            $sig = trim($sig);
            if ($sig !== '') {
                $signatures[] = preg_replace('/^sha256=/', '', $sig);
            }
        }
    }
    if (!ctype_digit($timestamp) || $signatures === []) {
        return false;
    }

    // `t` is epoch milliseconds.
    $nowMs = $nowMs ?? (int) floor(microtime(true) * 1000);
    if (abs($nowMs - (int) $timestamp) > 300000) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    foreach ($signatures as $sig) {
        if (hash_equals($expected, $sig)) {
            return true;
        }
    }
    return false;
}

// Plain PHP:
// verify_gauge_signature(getallheaders(), file_get_contents('php://input'), getenv('GAUGE_WEBHOOK_SECRET'));
```

In Laravel, headers come as arrays and the raw body from `getContent()`:

```php
$headers = array_map(fn ($values) => $values[0] ?? '', $request->headers->all());
$ok = verify_gauge_signature($headers, $request->getContent(), config('services.gauge.webhook_secret'));
```

## Test it [#test-it]

Choose **Send test event** on the endpoint in the console. It is signed with the endpoint's real
secret, so a test that passes verification proves your code.

For a unit test, use this fixed vector (the same one Gauge's own signer is tested against):

| | |
| --- | --- |
| Secret | `whsec_test_vector_secret_do_not_use` |
| Previous secret (rotation) | `whsec_previous_vector_secret` |
| `t` / `x-pulse-timestamp` | `1761048000000` |
| Raw body | `{"id":"evt_0f1e2d3c4b5a69788796a5b4","event":"message.received","payload":{"text":"Hi"}}` |
| `Gauge-Signature` | `t=1761048000000,v1=4b725ffac75eac0450b0c605e5f6bd7955b2702a6fe001cd4425610107bfb218` |
| `x-pulse-signature` | `sha256=4b725ffac75eac0450b0c605e5f6bd7955b2702a6fe001cd4425610107bfb218` |
| `Gauge-Signature` during a rotation | `t=1761048000000,v1=4b725ffac75eac0450b0c605e5f6bd7955b2702a6fe001cd4425610107bfb218,v1=c4f9d9e4b3742521417ca7956cf37cb8415c92fa3afaeaf32809151df16ba49c` |

Pass `now = 1761048000000` (Node), `now_ms=1761048000000` (Python) or `$nowMs = 1761048000000` (PHP)
so the 5-minute check passes for the old timestamp. The rotation header verifies under **either**
secret. You can reproduce the signature with
`printf '%s' '1761048000000.{"id":"evt_0f1e2d3c4b5a69788796a5b4","event":"message.received","payload":{"text":"Hi"}}' | openssl dgst -sha256 -hmac whsec_test_vector_secret_do_not_use`.

## Rotating the secret [#rotating-the-secret]

Rotate from the endpoint in the console, or with
`POST /v2/webhook-endpoints/{id}/rotate-secret` (`{ "overlapHours": 24 }` or `0`; the new secret is in
the answer, once). Choose a **24-hour overlap** for a planned rotation: for a
day, every delivery is signed with both secrets, so you can deploy the new secret without dropping
a delivery. Choose **no overlap** if the secret leaked: the old one stops signing at once.


# Who this key is (/reference/account/getMe)

The key, the member it acts as, the workspace and plan, its scopes, environment and the rate-limit budget left. Any valid key may call it.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List connections (/reference/connections/listConnections)

Connected channels, newest first, each with what it can send over the API right now (this workspace’s rollout flags resolved). WhatsApp Web connections carry a `warning` about account bans.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a connection (/reference/connections/getConnection)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List contacts (/reference/contacts/listContacts)

The workspace’s contacts (the same list the console shows), filtered and sorted.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Create a contact (/reference/contacts/createContact)

At least a name, an email or a phone. An email another contact holds is a 409 naming the owner.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Create or update a contact by channel identity (/reference/contacts/upsertContactByIdentity)

Updates the contact holding `{channel}/{externalId}`, or creates one with that identity (201). Safe to repeat.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a contact (/reference/contacts/getContact)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Update a contact (/reference/contacts/updateContact)

`customFields` are validated against Settings → Customer fields (types, options, required).



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Erase a contact (GDPR) (/reference/contacts/eraseContact)

IRREVERSIBLE: erases the contact’s personal data, identities and message contents. Needs a key whose member may erase contacts (Owner or Admin). `?reason=` is recorded in the audit log.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List a contact’s identities (/reference/contacts/listContactIdentities)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Add an identity (/reference/contacts/addContactIdentity)

Phones are normalized to E.164 (send `country` for a national number). A handle another contact holds is a 409.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Remove an identity (/reference/contacts/removeContactIdentity)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Tag a contact (/reference/contacts/addContactTags)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Untag a contact (/reference/contacts/removeContactTag)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Merge a contact into this one (/reference/contacts/mergeContact)

Folds `sourceId` into the path contact (identities, conversations, deals, notes, tags…). Undoable from the console for 7 days.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List conversations (/reference/conversations/listConversations)

Only what this key’s member may see (their own / team scope, unassigned pull queue, collaborations).



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a conversation (/reference/conversations/getConversation)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Update a conversation (/reference/conversations/updateConversation)

Status (open / snoozed with `snoozedUntil`, or until the customer replies / resolved), assignee, Move to team, topic, tags, priority, and App visitor details (stored with source `api`). Applied in that order; a refusal stops the rest.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Mark read (/reference/conversations/markConversationRead)

Moves this key’s member’s read marker to now.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Add an internal note (/reference/conversations/createConversationNote)

Visible to the team only, never to the customer.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List a conversation’s messages (/reference/conversations/listConversationMessages)

Newest first.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Send a message (/reference/messages/sendMessage)

Text, an approved template, buttons / a list, or a file (`mediaId`) on a connection, to a thread, a contact or a new recipient. 201 when the channel sent it now; 202 with `status: queued` when it is dispatched in the background (watch `message.status_updated`). Outside WhatsApp’s 24-hour window only a template may be sent (422 `unsupported_channel_action`, reason `outside_24h_window`). On WhatsApp Cloud a template sent with `to` or `contactId` starts the conversation (contact and thread created or reused); free text to someone with no conversation is 422 `outside_24h_window`. A template must be approved, in the given language and given exactly its variables (422, reason `template_not_approved` / `template_language_not_found` / `template_variable_mismatch`). WhatsApp Web numbers have warm-up caps (429, reason `whatsapp_web_daily_cap` / `whatsapp_web_minute_cap`) and every response carries `warnings: ["whatsapp_web_unofficial"]`. The Idempotency-Key also de-duplicates the send itself, beyond the 24-hour replay window.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a message (/reference/messages/getMessage)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Download a message’s file (/reference/messages/getMessageAttachment)

A signed download link (valid 5 minutes) for a file on a message — one a customer sent or one you sent. This is the path a webhook’s `media[].url` carries. A message carries one file today (`index` 0). 404 when there is none, or when Gauge holds no copy of it (reason `attachment_not_available`).



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# A message’s delivery history (/reference/messages/getMessageStatusHistory)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Start a file upload (/reference/media/createMedia)

Declare the file; PUT its bytes to `upload.url` with exactly `upload.headers` within 15 minutes; then send it with `mediaId`. Pass `connectionId` to check the channel’s limits up front.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a file (/reference/media/getMedia)

Once uploaded, a signed download link valid for 5 minutes.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List message templates (/reference/templates/listTemplates)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a template (/reference/templates/getTemplate)

With its components and the body variables a send must fill.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List webhook endpoints (/reference/webhooks/listWebhookEndpoints)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Create a webhook endpoint (/reference/webhooks/createWebhookEndpoint)

Starts sending the chosen events to `url`. The response carries the signing `secret` ONCE. The endpoint receives only conversations the key’s member can see. Subscribing to message, conversation or contact events also needs `messages:read`, `conversations:read` or `contacts:read` on the key. For WhatsApp Web connections you are responsible for send volume and the ban risk. Deliveries are at-least-once: dedupe on the event `id` (also in `Gauge-Event-Id`). Order is NOT guaranteed, not even within one conversation — use `occurredAt` and the snapshot in the payload. A non-2xx answer is retried after 30 s, 5 min, 1 h and 6 h. An endpoint failing every delivery for 3 days is switched off and its owner is told.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get a webhook endpoint (/reference/webhooks/getWebhookEndpoint)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Update a webhook endpoint (/reference/webhooks/updateWebhookEndpoint)

Change the URL, events, connection or App filter, version, or turn it on or off. Turning it on clears an automatic switch-off.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Delete a webhook endpoint (/reference/webhooks/deleteWebhookEndpoint)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Rotate the signing secret (/reference/webhooks/rotateWebhookSecret)

Returns the new secret ONCE. With `overlapHours: 24` the old secret keeps signing a second `v1` in `Gauge-Signature` for a day.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Send a test event (/reference/webhooks/testWebhookEndpoint)

Signs and sends a sample of a catalogue event (`test: true`, `livemode: false`) now, and reports what the endpoint answered.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List deliveries (/reference/webhooks/listWebhookDeliveries)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# message.received (/reference/webhooks/webhook_message_received)

A customer sent a message on any channel: text, files, and the button or list row they tapped. Sent only for conversations the endpoint owner can see, on the endpoint’s connections. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# message.sent (/reference/webhooks/webhook_message_sent)

A message was sent to a customer, by a person, Gauge AI, an automation or the API. Sent only for conversations the endpoint owner can see, on the endpoint’s connections. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# message.status_updated (/reference/webhooks/webhook_message_status_updated)

An outgoing message was delivered, read, or failed (with the reason). Sent only for conversations the endpoint owner can see, on the endpoint’s connections. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# conversation.created (/reference/webhooks/webhook_conversation_created)

A new conversation started. Sent only for conversations the endpoint owner can see, on the endpoint’s connections. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# conversation.updated (/reference/webhooks/webhook_conversation_updated)

A conversation was opened, snoozed or resolved, or its assignee, team or topic changed. Sent only for conversations the endpoint owner can see, on the endpoint’s connections. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# contact.created (/reference/webhooks/webhook_contact_created)

A contact was created, by a person or by a first message from someone new. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# contact.updated (/reference/webhooks/webhook_contact_updated)

A contact was renamed, merged, had a handle added or removed, or had fields changed. Endpoints on API version 2026-10-21 or later.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.callback.cancelled (/reference/webhooks/webhook_support_callback_cancelled)

Support callback: cancelled. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.callback.completed (/reference/webhooks/webhook_support_callback_completed)

Support callback: completed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.callback.failed (/reference/webhooks/webhook_support_callback_failed)

Support callback: failed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.callback.requested (/reference/webhooks/webhook_support_callback_requested)

Support callback: requested. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.callback.scheduled (/reference/webhooks/webhook_support_callback_scheduled)

Support callback: scheduled. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.answered (/reference/webhooks/webhook_support_chat_answered)

Support chat: answered. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.ended (/reference/webhooks/webhook_support_chat_ended)

Support chat: ended. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.handoff_to_ticket (/reference/webhooks/webhook_support_chat_handoff_to_ticket)

Support chat: handoff to ticket. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.message_created (/reference/webhooks/webhook_support_chat_message_created)

Support chat: message created. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.offered (/reference/webhooks/webhook_support_chat_offered)

Support chat: offered. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.ownership_changed (/reference/webhooks/webhook_support_chat_ownership_changed)

Support chat: ownership changed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.queued (/reference/webhooks/webhook_support_chat_queued)

Support chat: queued. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.session_started (/reference/webhooks/webhook_support_chat_session_started)

Support chat: session started. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.chat.unclaimed (/reference/webhooks/webhook_support_chat_unclaimed)

Support chat: unclaimed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.access_granted (/reference/webhooks/webhook_support_customer_access_granted)

Support customer: access granted. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.access_revoked (/reference/webhooks/webhook_support_customer_access_revoked)

Support customer: access revoked. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.blocked (/reference/webhooks/webhook_support_customer_blocked)

Support customer: blocked. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.created (/reference/webhooks/webhook_support_customer_created)

Support customer: created. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.deactivated (/reference/webhooks/webhook_support_customer_deactivated)

Support customer: deactivated. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.unblocked (/reference/webhooks/webhook_support_customer_unblocked)

Support customer: unblocked. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.unread_changed (/reference/webhooks/webhook_support_customer_unread_changed)

Support customer: unread changed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.updated (/reference/webhooks/webhook_support_customer_updated)

Support customer: updated. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.customer.verified (/reference/webhooks/webhook_support_customer_verified)

Support customer: verified. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.kb.article_published (/reference/webhooks/webhook_support_kb_article_published)

Support kb: article published. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.kb.article_unpublished (/reference/webhooks/webhook_support_kb_article_unpublished)

Support kb: article unpublished. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.kb.deflected (/reference/webhooks/webhook_support_kb_deflected)

Support kb: deflected. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.meeting.cancelled (/reference/webhooks/webhook_support_meeting_cancelled)

Support meeting: cancelled. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.meeting.created (/reference/webhooks/webhook_support_meeting_created)

Support meeting: created. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.meeting.ended (/reference/webhooks/webhook_support_meeting_ended)

Support meeting: ended. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.meeting.participant_joined (/reference/webhooks/webhook_support_meeting_participant_joined)

Support meeting: participant joined. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.meeting.started (/reference/webhooks/webhook_support_meeting_started)

Support meeting: started. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.project.branding_updated (/reference/webhooks/webhook_support_project_branding_updated)

Support project: branding updated. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.project.created (/reference/webhooks/webhook_support_project_created)

Support project: created. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.project.updated (/reference/webhooks/webhook_support_project_updated)

Support project: updated. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.session_link.created (/reference/webhooks/webhook_support_session_link_created)

Support session link: created. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.session_link.redeemed (/reference/webhooks/webhook_support_session_link_redeemed)

Support session link: redeemed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.session_link.revoked (/reference/webhooks/webhook_support_session_link_revoked)

Support session link: revoked. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.assigned (/reference/webhooks/webhook_support_ticket_assigned)

Support ticket: assigned. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.created (/reference/webhooks/webhook_support_ticket_created)

Support ticket: created. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.escalated (/reference/webhooks/webhook_support_ticket_escalated)

Support ticket: escalated. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.escalation_acknowledged (/reference/webhooks/webhook_support_ticket_escalation_acknowledged)

Support ticket: escalation acknowledged. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.merged (/reference/webhooks/webhook_support_ticket_merged)

Support ticket: merged. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.replied (/reference/webhooks/webhook_support_ticket_replied)

Support ticket: replied. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.sla_breached (/reference/webhooks/webhook_support_ticket_sla_breached)

Support ticket: sla breached. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.split (/reference/webhooks/webhook_support_ticket_split)

Support ticket: split. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.status_changed (/reference/webhooks/webhook_support_ticket_status_changed)

Support ticket: status changed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.tier_changed (/reference/webhooks/webhook_support_ticket_tier_changed)

Support ticket: tier changed. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.ticket.updated (/reference/webhooks/webhook_support_ticket_updated)

Support ticket: updated. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.voice.abandoned (/reference/webhooks/webhook_support_voice_abandoned)

Support voice: abandoned. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.voice.answered (/reference/webhooks/webhook_support_voice_answered)

Support voice: answered. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.voice.ended (/reference/webhooks/webhook_support_voice_ended)

Support voice: ended. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# support.voice.queued (/reference/webhooks/webhook_support_voice_queued)

Support voice: queued. Every endpoint, including those created before API v2.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# List events (/reference/events/listEvents)

The last 30 days. Message and conversation events are listed only for conversations the key’s member can see, and only when the key may read conversations.



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Get an event (/reference/events/getEvent)



Machine-readable: https://docs.gauge.chat/openapi/v2.json

# Redeliver an event (/reference/events/redeliverEvent)

Sends the same body again (same `id`) to the endpoints that received it, or to one. Shares the workspace’s replay budget (20 an hour) with the console.



Machine-readable: https://docs.gauge.chat/openapi/v2.json