Messages

Send a messageCopy Anchor Link

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):

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" }
  }'

201 sent, or 202 queuedCopy Anchor Link

Both answer the same body:

{
  "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 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).

WhatsApp Web connections add "warnings": ["whatsapp_web_unofficial"] to every send: see 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 firstCopy Anchor Link

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:

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.

Read a messageCopy Anchor Link

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 fileCopy Anchor Link

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.

{
  "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" }
}

Delivery historyCopy Anchor Link

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

{
  "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 refusedCopy Anchor Link