Messages

Entry points and idempotency

POST /messages/send and POST /messages/send-template are the most common entry points — they resolve or create the right thread from a channel + recipient pair automatically and generate the idempotency key themselves (they do not accept a client-supplied body idempotency_key). Client-key idempotency is available on the direct POST /messages and on POST /messages/{message}/forward: pass an idempotency_key (up to 100 chars) and a retried request with the same key returns the same message instead of creating a duplicate.

Separately, POST /messages/send and POST /messages/send-template accept an optional Idempotency-Key HTTP header (up to 128 chars) — a middleware-level mechanism unrelated to the body idempotency_key parameter above. A retried request with the same header value (scoped by key + endpoint + user) within 24 hours does not re-send the message and instead returns the cached response from the first request; reusing the key with a different request body returns 422. The header is optional — omitting it leaves the endpoints' behavior unchanged; it exists to protect clients with automatic network retries (e.g. the mobile app after a dropped connection).

Contact blocking

When the recipient is a blocked contact (blocked_at set; blocked via POST /contacts/{contact}/block, see the "Contacts" group), an outbound message is refused before it is created: POST /messages/send, the direct POST /messages, and POST /messages/{message}/forward all return 422 {"message": "This contact is blocked; the message was not sent.", "error_code": "contact_blocked"}. The check runs against the target thread's conversation_id (resolved automatically for /messages/send and /forward) rather than the recipient directly.

Listing and pagination

GET /messages filters by conversation_id/thread_id/channel_id/direction/message_type (for the canonical list of message_type values, see the message.type field of the message.created event in the webhook events reference) and paginates either page-by-page (page/perPage) or by cursor — pass before_message_id to walk older messages (the scroll-up direction of a chat history) or after_message_id for newer ones; the legacy aliases before_id/after_id, limit (=perPage) and order (=sortDir) are also accepted, sortBy is one of id|timestamp|created_at|updated_at (default timestamp) and in cursor mode the response keeps the {items, pagination} shape but returns total/lastPage as null (the COUNT is skipped).

GET /messages also supports a text filter search (the same ILIKE over message_content/external_message_id/external_thread_id) and its official alias q (since 2026-08-20): if only q is sent, its value is copied into search; if both are sent, the explicit search wins. Before that date an unrecognized q here was silently dropped — the request looked like it worked but found nothing; prefer the explicit search name for new integrations.

Search (`GET /messages/search`)

GET /messages/search — the required q (string, 2 to 255 chars) searches message text (ILIKE over message_content). conversation_id is optional (since 2026-08-20): given, the search runs inside that one conversation (a conversation from another company, or a non-existent one, is 404); omitted, the search runs company-wide, scoped to the channels the user can access, and every result then carries its own conversation_id — this is how you find a conversation that otherwise is not visible in any list. Results are sorted newest first (created_at desc). Pagination is page/perPage (5–100, default 20). The response is { "data": { items[], pagination{page,perPage,total,lastPage}, total_matches } }, where each items[] is {message_id, conversation_id, thread_id, created_at, snippet, query, contact_name, channel_id, channel_type}; the last three fields (since 2026-08-20) are contact_name (the thread's contact readable name, string or null), channel_id, and channel_type (the channel type key, e.g. whatsapp/telegram, or null) — added so a company-wide hit can be rendered as a standalone row without an extra contact/channel lookup. snippet (since 2026-08-22) is a text window centered on the MATCH itself (case-insensitive, up to ~240 chars, with ... at whichever edge is truncated), not the first characters of the message — before that date the snippet always started at the beginning of the message, so a match late in a long message could be invisible; when there is no textual match (e.g. the hit came from another field, or the message is media with no caption), the previous behavior applies (the first ~240 chars). The field's format is unchanged — only its content improved. The route carries a heavier rate limit (throttle:api-token-heavy, 120 requests/min both for programmatic tokens and — since 2026-08-22 — for regular session-authenticated web-client users; session clients previously had no limit at all here).

Quoted replies

To send a quoted reply, use the direct POST /messages with quoted_message_id (the internal id of the quoted message) or quoted_external_message_id — /messages/send does not accept it.

Ad attribution (referral)

The message object (GET /messages, /messages/{message}, /messages/{message}/around) carries a referral field — the same ad-attribution data as the message.created webhook (its data.referral object), just without the event envelope. null for regular messages; populated on the first message of a conversation started from an ad, only for the whatsapp/whatsapp_business (Click-to-WhatsApp) and instagram_business (click-to-Direct ads) channels. The field set depends on the channel: WhatsApp supplies source_url, ctwa_clid, body, media_type; Instagram supplies post_id and ref. Common to both: source_type, source_id, headline, image_url, video_url. See the webhook events reference (message.created event) for the full per-field description.

Attachments

Attachments are sent in two steps: first upload the file through POST /uploads (up to 64 MB — image, video, audio, document), then reference the returned media_id/storage_path when creating the message or via POST /messages/{message}/attachments; the source is validated and must belong to your company, otherwise a flat 422 {error_code: attachment_source_invalid} is returned (re-upload).

Inbound attachments first carry the provider's runtime/CDN url, which can expire within hours (e.g. Instagram) — call POST /messages/{message}/attachments/{attachment}/fetch to pull the bytes into local storage, after which the attachment exposes a stable signed url and GET .../attachments/{attachment}/media streams those bytes.

fetch also works for Instagram-channel (meta_instagram) attachments — ig_post/ig_reel/story attachments are resolved through the Graph API/CDN the same way the webhook handler does when the message first arrives. For attachments that have no downloadable media at all (type is template, ephemeral, or unsupported_type — a generic-template card, a self-destructing attachment, or an unrecognized one), fetch immediately returns 422 {message: "...", error_code: "attachment_not_fetchable"} instead of eventually surfacing a 502 — calling fetch on these types is pointless, they never get a storage_path.

thumbnail_url (since 2026-08-24) is now populated automatically for locally-stored image attachments, except image/svg+xml (not rasterizable, and not served inline for security reasons) — it is the same signed .../media route with a w=640 query param, returning a webp derivative instead of the original. The field used to be almost always null; a provider-supplied thumbnail_url (e.g. from Instagram's lookaside CDN), when already present, takes priority and is not overridden. On GET .../attachments/{attachment}/media, the w param only accepts 256 or 640 (a closed whitelist) — any other value, or no w at all, returns the original as before; w is ignored for non-images. As of the same date, MIME types unsafe to render inline (svg, html, xml, txt, etc.) are served as Content-Type: application/octet-stream with Content-Disposition: attachment instead of inline — a guard against XSS via a message with an attacker-declared mime_type on the session-cookie origin. The route carries a throttle:signed-media rate limit (2000 requests/minute per IP).

Editing and deleting

Editing (PATCH) and deletion (DELETE) are bounded by channel windows: gate the edit and revoke-for-everyone controls on the pre-computed per-message can_edit_until / can_revoke_until fields instead of re-deriving per-channel rules — each is an ISO-8601 deadline while the action is allowed, or null when it is not (inbound, already-deleted, non-text for edit, a channel that does not support the action such as whatsapp_business for revoke, or an expired window).

DELETE soft-deletes by default (nulls the text); mode=revoke also revokes it for the recipient where the channel supports provider-side deletion (delete_scope='provider': QR-based WhatsApp, Telegram, Instagram) — WhatsApp Cloud (whatsapp_business) cannot revoke and returns 422. Send mode in the JSON body rather than the query string: some proxies drop query params on DELETE and would silently downgrade a revoke to a local delete.

Reactions

POST /messages/{message}/reactions takes {reaction: "<emoji>"} (required, up to 32 chars) and reacts on behalf of the company (the author defaults to the authenticated user; explicit author_user_id/author_contact_account_id take priority and are validated against the company) — a channel allows one outbound reaction per message, so a new call replaces the previous one. DELETE /messages/{message}/reactions removes the company's outbound reaction from a message — no reaction id is needed (a channel carries at most one), and the call is idempotent (200 even when there is nothing to remove). Both actions broadcast the message.reaction.updated webhook (action: "added" / "removed").

Forwarding

POST /messages/{message}/forward performs a copy-send: it creates a new outbound message with the same content and attachments, either into an existing thread (target_thread_id) or cross-channel by contact (target_contact_account_id, optionally with an explicit target_channel_id); on refusal it returns 422 with an error_code from the set message_deleted, message_not_forwardable, channel_not_textable, content_type_unsupported, wa_window_closed, channel_incompatible, channel_not_connected, no_compatible_channel, channel_required, contact_blocked (the recipient is blocked — see "Contact blocking" above).

Voice notes

Voice notes are uploaded through a dedicated path POST /uploads/voice: it accepts a recorded audio or video file (multipart file field, up to 32 MB, mimetypes webm/ogg/mp4/mpeg/wav/aac/m4a) and transcodes it to voice-OGG (Opus), returning a flat object with media_id/storage_path in the same shape as POST /uploads — reference that media_id when sending and the recipient sees a proper voice note (ptt) rather than a plain audio file; a transcoding failure returns 422.

Sending a sticker

A sticker from the company's library (see the "Stickers" group) is sent as a regular attachment, but via attachments[].sticker_id instead of attachments[].media_id — reference the sticker's id from GET /v1/sticker-packs. Each attachments[] row must carry exactly one of the two fields — both at once, or neither, returns 422. You do not need to set attachments[].type for a sticker — it is set automatically (sticker); POST /v1/messages/send and the direct POST /v1/messages accept sticker_id the same way.

Liking an Instagram comment

POST /messages/{message}/like likes a comment: it works only for Instagram Business comment threads (thread.is_group + a channel of type instagram_business) and requires the message to have an external id, otherwise 422; on success it returns a flat { "message": "Comment liked." }.