# Gauge API - **Get started** - [The Gauge API](/): Send and receive customer messages on WhatsApp, email and web chat, keep contacts in sync, and get every event at your own endpoint. - [Quickstart](/quickstart): Create an API key, check it with your first call, send a WhatsApp message, and receive replies at your own endpoint. - [Authentication and keys](/authentication): Bearer API keys, scopes, live and test environments, App pinning, IP allowlists, expiry, rotation, and what happens when a key's owner leaves. - Conventions - [Conventions](/conventions): The rules every /v2 endpoint follows, so you learn them once. - [Versioning](/conventions/versioning): The /v2 path, the dated Gauge-Version header, and how Gauge tells you before anything changes. - [Errors](/conventions/errors): One error envelope on every public endpoint, a closed list of codes, and what to do about each one. - [Request ids](/conventions/request-ids): Every response carries X-Request-Id. Log it, and quote it when you contact support. - [Idempotency](/conventions/idempotency): Every POST needs an Idempotency-Key. Retry with the same key and the work happens once. - [Pagination](/conventions/pagination): Every list returns the same page shape and walks it with opaque cursors. - [Rate limits](/conventions/rate-limits): Requests per minute per key and per workspace, sized by plan, with RateLimit headers on every response. - [Plans](/conventions/plans): The Gauge API is included on the Growth and Scale plans. - **Build** - Channels - [Channels and capabilities](/channels): What each channel can do over the API, how to read a connection's live capabilities, and WhatsApp's 24-hour window. - [WhatsApp Cloud API](/channels/whatsapp-cloud): Meta's official WhatsApp Business platform. The 24-hour window, templates, media and delivery status. - [WhatsApp Web](/channels/whatsapp-web): A personal or WhatsApp Business app account linked like WhatsApp Web. Allowed over the API, at your own risk of an account ban. - [Email](/channels/email): Send and receive email through a connected inbox, threaded with the customer's other conversations. - [Web chat](/channels/web-chat): The Gauge chat widget on your website or in your app. Visitors start the conversation; you answer it. - [Instagram and Messenger](/channels/instagram-messenger): Direct messages from an Instagram professional account or a Facebook Page. Text replies into conversations customers start. - [SMS](/channels/sms): SMS over the API is coming after a compliance review. - [Voice](/channels/voice): Calls, recordings and voicemail over the API are coming after a compliance review. - Messaging - [Messaging](/messaging): Contacts, conversations, messages, media and templates. The resources behind sending and reading customer messages. - [Messages](/messaging/messages): Send text, media, templates and interactive messages; read a message, its delivery history and its files. - [Conversations](/messaging/conversations): List and open conversations, change their status, assignee, team, topic and tags, mark them read, and add internal notes. - [Contacts](/messaging/contacts): Create, update and look up contacts, upsert them by channel identity to keep Gauge in step with your own system, and erase them. - [Media](/messaging/media): Upload a file to send in a message, and get short-lived links to files. - [Templates](/messaging/templates): List WhatsApp templates and send approved ones, including outside the 24-hour window. - Webhooks - [Webhooks](/webhooks): Gauge POSTs a signed JSON event to your HTTPS endpoint the moment something happens. - [Event catalogue](/webhooks/events): Every event Gauge delivers to webhooks, their payloads, and who receives them. - [Verify signatures](/webhooks/verify-signatures): Check every delivery's HMAC-SHA256 signature against the raw body before you trust it. Node, Python and PHP. - [Delivery, retries and ordering](/webhooks/delivery): When Gauge retries, when it gives up, why you must deduplicate, and why events can arrive out of order. - [Testing and replay](/webhooks/testing-and-replay): Send test events, resend a single delivery, and replay everything that failed while your server was down. - [Forward inbound messages](/webhooks/inbound-messages): Receive every customer message from WhatsApp, email, web chat and Meta channels at your own endpoint, signed and in real time. - **Reference** - API reference - [API reference](/reference): Every /v2 endpoint and webhook event, generated from the API's own OpenAPI document. - Account - [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. - Connections - [Get a connection](/reference/connections/getConnection) - [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. - Contacts - [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. - [Tag a contact](/reference/contacts/addContactTags) - [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. - [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. - [Get a contact](/reference/contacts/getContact) - [List a contact’s identities](/reference/contacts/listContactIdentities) - [List contacts](/reference/contacts/listContacts): The workspace’s contacts (the same list the console shows), filtered and sorted. - [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. - [Remove an identity](/reference/contacts/removeContactIdentity) - [Untag a contact](/reference/contacts/removeContactTag) - [Update a contact](/reference/contacts/updateContact): `customFields` are validated against Settings → Customer fields (types, options, required). - [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. - Conversations - [Add an internal note](/reference/conversations/createConversationNote): Visible to the team only, never to the customer. - [Get a conversation](/reference/conversations/getConversation) - [List a conversation’s messages](/reference/conversations/listConversationMessages): Newest first. - [List conversations](/reference/conversations/listConversations): Only what this key’s member may see (their own / team scope, unassigned pull queue, collaborations). - [Mark read](/reference/conversations/markConversationRead): Moves this key’s member’s read marker to now. - [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. - Events - [Get an event](/reference/events/getEvent) - [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. - [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. - Media - [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. - [Get a file](/reference/media/getMedia): Once uploaded, a signed download link valid for 5 minutes. - Messages - [Get a message](/reference/messages/getMessage) - [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`). - [A message’s delivery history](/reference/messages/getMessageStatusHistory) - [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. - Templates - [Get a template](/reference/templates/getTemplate): With its components and the body variables a send must fill. - [List message templates](/reference/templates/listTemplates) - Webhooks - [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. - [Delete a webhook endpoint](/reference/webhooks/deleteWebhookEndpoint) - [Get a webhook endpoint](/reference/webhooks/getWebhookEndpoint) - [List deliveries](/reference/webhooks/listWebhookDeliveries) - [List webhook endpoints](/reference/webhooks/listWebhookEndpoints) - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [support.callback.cancelled](/reference/webhooks/webhook_support_callback_cancelled): Support callback: cancelled. Every endpoint, including those created before API v2. - [support.callback.completed](/reference/webhooks/webhook_support_callback_completed): Support callback: completed. Every endpoint, including those created before API v2. - [support.callback.failed](/reference/webhooks/webhook_support_callback_failed): Support callback: failed. Every endpoint, including those created before API v2. - [support.callback.requested](/reference/webhooks/webhook_support_callback_requested): Support callback: requested. Every endpoint, including those created before API v2. - [support.callback.scheduled](/reference/webhooks/webhook_support_callback_scheduled): Support callback: scheduled. Every endpoint, including those created before API v2. - [support.chat.answered](/reference/webhooks/webhook_support_chat_answered): Support chat: answered. Every endpoint, including those created before API v2. - [support.chat.ended](/reference/webhooks/webhook_support_chat_ended): Support chat: ended. Every endpoint, including those created before API v2. - [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. - [support.chat.message_created](/reference/webhooks/webhook_support_chat_message_created): Support chat: message created. Every endpoint, including those created before API v2. - [support.chat.offered](/reference/webhooks/webhook_support_chat_offered): Support chat: offered. Every endpoint, including those created before API v2. - [support.chat.ownership_changed](/reference/webhooks/webhook_support_chat_ownership_changed): Support chat: ownership changed. Every endpoint, including those created before API v2. - [support.chat.queued](/reference/webhooks/webhook_support_chat_queued): Support chat: queued. Every endpoint, including those created before API v2. - [support.chat.session_started](/reference/webhooks/webhook_support_chat_session_started): Support chat: session started. Every endpoint, including those created before API v2. - [support.chat.unclaimed](/reference/webhooks/webhook_support_chat_unclaimed): Support chat: unclaimed. Every endpoint, including those created before API v2. - [support.customer.access_granted](/reference/webhooks/webhook_support_customer_access_granted): Support customer: access granted. Every endpoint, including those created before API v2. - [support.customer.access_revoked](/reference/webhooks/webhook_support_customer_access_revoked): Support customer: access revoked. Every endpoint, including those created before API v2. - [support.customer.blocked](/reference/webhooks/webhook_support_customer_blocked): Support customer: blocked. Every endpoint, including those created before API v2. - [support.customer.created](/reference/webhooks/webhook_support_customer_created): Support customer: created. Every endpoint, including those created before API v2. - [support.customer.deactivated](/reference/webhooks/webhook_support_customer_deactivated): Support customer: deactivated. Every endpoint, including those created before API v2. - [support.customer.unblocked](/reference/webhooks/webhook_support_customer_unblocked): Support customer: unblocked. Every endpoint, including those created before API v2. - [support.customer.unread_changed](/reference/webhooks/webhook_support_customer_unread_changed): Support customer: unread changed. Every endpoint, including those created before API v2. - [support.customer.updated](/reference/webhooks/webhook_support_customer_updated): Support customer: updated. Every endpoint, including those created before API v2. - [support.customer.verified](/reference/webhooks/webhook_support_customer_verified): Support customer: verified. Every endpoint, including those created before API v2. - [support.kb.article_published](/reference/webhooks/webhook_support_kb_article_published): Support kb: article published. Every endpoint, including those created before API v2. - [support.kb.article_unpublished](/reference/webhooks/webhook_support_kb_article_unpublished): Support kb: article unpublished. Every endpoint, including those created before API v2. - [support.kb.deflected](/reference/webhooks/webhook_support_kb_deflected): Support kb: deflected. Every endpoint, including those created before API v2. - [support.meeting.cancelled](/reference/webhooks/webhook_support_meeting_cancelled): Support meeting: cancelled. Every endpoint, including those created before API v2. - [support.meeting.created](/reference/webhooks/webhook_support_meeting_created): Support meeting: created. Every endpoint, including those created before API v2. - [support.meeting.ended](/reference/webhooks/webhook_support_meeting_ended): Support meeting: ended. Every endpoint, including those created before API v2. - [support.meeting.participant_joined](/reference/webhooks/webhook_support_meeting_participant_joined): Support meeting: participant joined. Every endpoint, including those created before API v2. - [support.meeting.started](/reference/webhooks/webhook_support_meeting_started): Support meeting: started. Every endpoint, including those created before API v2. - [support.project.branding_updated](/reference/webhooks/webhook_support_project_branding_updated): Support project: branding updated. Every endpoint, including those created before API v2. - [support.project.created](/reference/webhooks/webhook_support_project_created): Support project: created. Every endpoint, including those created before API v2. - [support.project.updated](/reference/webhooks/webhook_support_project_updated): Support project: updated. Every endpoint, including those created before API v2. - [support.session_link.created](/reference/webhooks/webhook_support_session_link_created): Support session link: created. Every endpoint, including those created before API v2. - [support.session_link.redeemed](/reference/webhooks/webhook_support_session_link_redeemed): Support session link: redeemed. Every endpoint, including those created before API v2. - [support.session_link.revoked](/reference/webhooks/webhook_support_session_link_revoked): Support session link: revoked. Every endpoint, including those created before API v2. - [support.ticket.assigned](/reference/webhooks/webhook_support_ticket_assigned): Support ticket: assigned. Every endpoint, including those created before API v2. - [support.ticket.created](/reference/webhooks/webhook_support_ticket_created): Support ticket: created. Every endpoint, including those created before API v2. - [support.ticket.escalated](/reference/webhooks/webhook_support_ticket_escalated): Support ticket: escalated. Every endpoint, including those created before API v2. - [support.ticket.escalation_acknowledged](/reference/webhooks/webhook_support_ticket_escalation_acknowledged): Support ticket: escalation acknowledged. Every endpoint, including those created before API v2. - [support.ticket.merged](/reference/webhooks/webhook_support_ticket_merged): Support ticket: merged. Every endpoint, including those created before API v2. - [support.ticket.replied](/reference/webhooks/webhook_support_ticket_replied): Support ticket: replied. Every endpoint, including those created before API v2. - [support.ticket.sla_breached](/reference/webhooks/webhook_support_ticket_sla_breached): Support ticket: sla breached. Every endpoint, including those created before API v2. - [support.ticket.split](/reference/webhooks/webhook_support_ticket_split): Support ticket: split. Every endpoint, including those created before API v2. - [support.ticket.status_changed](/reference/webhooks/webhook_support_ticket_status_changed): Support ticket: status changed. Every endpoint, including those created before API v2. - [support.ticket.tier_changed](/reference/webhooks/webhook_support_ticket_tier_changed): Support ticket: tier changed. Every endpoint, including those created before API v2. - [support.ticket.updated](/reference/webhooks/webhook_support_ticket_updated): Support ticket: updated. Every endpoint, including those created before API v2. - [support.voice.abandoned](/reference/webhooks/webhook_support_voice_abandoned): Support voice: abandoned. Every endpoint, including those created before API v2. - [support.voice.answered](/reference/webhooks/webhook_support_voice_answered): Support voice: answered. Every endpoint, including those created before API v2. - [support.voice.ended](/reference/webhooks/webhook_support_voice_ended): Support voice: ended. Every endpoint, including those created before API v2. - [support.voice.queued](/reference/webhooks/webhook_support_voice_queued): Support voice: queued. Every endpoint, including those created before API v2. - Support API - [Support API](/support): Put Gauge's live chat, tickets and callbacks inside your own web or mobile app, signed in as your own users. - [Gauge Support quick start](/support/quickstart): Wire your SaaS to Gauge Support in about 15 minutes: provision your users, embed the chat widget (or sign users into the portal), and receive verified webhooks. - [Quick start: chat in your website or web app (signed-in users)](/support/quickstart-web-app): About 15 minutes. You add one endpoint to your server and one snippet to your page. Gauge then knows which user is chatting and which Integration they are on. - [Quick start: chat in your mobile app (WebView)](/support/quickstart-webview): Your backend mints a one-time sign-in link for the signed-in user and the Integration. Your app opens it in a WebView, which lands in that integration's live chat. No secret ever ships in the app. - [Quick start: API only (your backend talks to Gauge)](/support/quickstart-api): No widget and no WebView: your backend provisions users, grants them Integrations and mints sign-in links. Every call uses a server API key (Authorization: Bearer pulse_k_…) with support scope. - Quick starts by stack - [Quick starts by stack](/support/quickstarts): Each page takes a signed-in user on your site to a verified Gauge chat in about 15 minutes, and wires the webhook back to your server. Pick your stack: - [Quick start: Next.js (App Router)](/support/quickstarts/nextjs): Next.js 14+ with route handlers. About 15 minutes to a verified chat message. - [Quick start: Express](/support/quickstarts/express): Node ≥ 18. About 15 minutes from npm install to a verified chat message. - [Quick start: Django](/support/quickstarts/django): Django 4.2+, Python ≥ 3.9. About 15 minutes to a verified chat message. - [Quick start: Laravel](/support/quickstarts/laravel): Laravel 10+, PHP ≥ 8.1. About 15 minutes to a verified chat message. - [Quick start: Rails](/support/quickstarts/rails): Rails 7+, Ruby ≥ 3.0. About 15 minutes to a verified chat message. - [Quick start: Go (`net/http`)](/support/quickstarts/go): Go ≥ 1.21, standard library only. About 15 minutes to a verified chat message. - [Signed integration tokens](/support/integration-token): 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.… - [Keeping your users in sync with Gauge Support](/support/customer-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… - [Support callbacks: "Request a callback"](/support/callbacks): 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… - [Native Help & Support screens](/support/native-screens): 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… - [Support in a native app: live chat in a WebView, and push on reply](/support/mobile): This page is for a tenant whose product is a native app: Salonvira's two Flutter apps are the first. It covers two jobs. - [WebView recipes: React Native, iOS and Android](/support/webview-recipes): Copy-paste screens that open the Gauge support chat in your app. Each one does the same five things as the Flutter package (gauge_support_webview): - [Support embed S1: the API core](/support/api-s1): 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,… - **Resources** - [Use Gauge with AI tools](/ai-tools): Give your AI assistant the Gauge docs, in the formats it reads best. - [Changelog](/changelog): What changed in the Gauge API, newest first. Additive changes, new endpoints, and anything you need to act on. - [Status and help](/status): How to tell whether a problem is yours or ours, and how to reach Gauge support with what they need. - [Glossary](/glossary): One name per concept. The words these docs and the API use, and what each means.