API reference v1

Needs no scope. A channel-bound key sees only its channel.

Needs no scope. A channel the key cannot see is 404.

Needs the messages:read scope. A message outside the key's channels, or past retention, is 404.

Needs the messages:read scope. Messages of the key's channels, newest first unless order=asc. Filter by channel_id, conversation_id, contact_id and direction; an id the key cannot see is 404. The cursor carries the order; repeat the filters and the time filters on every page.

Needs the messages:send scope; an inline consent also needs consents:write. At most 20 requests per second per key. The Idempotency-Key header is required and stays unique per channel for good: the same key with the same body returns 200 with the current state of the first message and Idempotent-Replayed: true, the same key with another body gets 409 idempotency_key_reused. Use a new UUID or ULID per logical send; a refused send keeps no key, so it can be retried with the same key once the condition changed.

Address the recipient by contact_id (recommended), by phone (E.164, WhatsApp only; a contact of the channel that owns the phone, otherwise a new unverified contact) or by an identity that already exists on the channel. UPPU picks Meta's address itself. Session content (text, interactive, reaction, location) needs the 24-hour window; an approved template does not. The window is counted like Meta counts it: from Meta's timestamp of the person's last message (its sent_at, never later than its received_at), not from the moment the message reached UPPU. Meta can deliver old messages late; such a message arrives with the window already closed (service_window.open false in message.received) and a session message then gets 422 window_closed: on WhatsApp send a template. Template rules: MARKETING needs a recorded marketing consent, UTILITY a recorded utility consent or a message from the person on this number after the latest withdrawal, AUTHENTICATION is never sent. A policy refusal writes nothing but a ledger row; a validation error writes nothing. Media (image, video, audio, document) is sent by media_id (POST /media) or by an https link that UPPU downloads, stores and uploads to Meta before sending; contacts and stickers come in v1.1.

A send to a contact without an open conversation is recorded in a new, already resolved conversation; the reply of the person opens a conversation as usual. Statuses follow as message.status webhooks (accepted, sent, delivered, read, failed) with your client_reference. Do not resend on unknown.

Needs the messages:send scope. Only inbound WhatsApp messages (422 not_inbound; web chat has no read receipts). The 24-hour window applies. Returns 202 the first time and 200 with the current state on a repeat. Send an empty body or {}.

Needs the contacts:read scope. Personal data never goes into a URL: the phone or identity is in the body. Give the channel and exactly one of phone (E.164, WhatsApp channels) or identity. A contact that is not found on the channel is 404. This is a read: it also works for read-only companies.

Needs the templates:read scope. Templates belong to the WhatsApp Business account of a channel; channel_ids lists the key's channels that can use a template. Deleted templates are left out unless status asks for them. sendable tells whether POST /messages accepts the template today; send_example is a ready content object built from the template's own example values.

Needs the templates:read scope. A template outside the key's channels is 404.

Needs the events:read scope; at most 2 requests per second per key. Returns the same event ids and the same bodies that the webhooks deliver, oldest first, for 7 days after an event was created. Pass the next_cursor of the previous page as after. An event is listed about 10 seconds after it was recorded, once every transaction that may still write an earlier id has finished, so a cursor never skips an event. A channel-bound key sees only the events of its channel; events without a channel (template.updated) need an all-channels key. Test events are never listed.

Needs the media:write scope; at most 2 requests per second and 1 GB per day per key. A multipart/form-data body with exactly two fields: channel_id (a WhatsApp, Messenger or Instagram channel the key can use; a web chat channel, and an Instagram channel while UPPU's Instagram outbound media is off, gets 422 content_not_supported_on_channel; the channel's capabilities.content_types show whether media can be sent) and file. At most 25 MB; the type is read from the content and must be one the channel's type can send, otherwise 415 unsupported_media_type (Meta's lists are not verified). An MP4 container that reads as video is audio when the file part is declared audio/mp4, and video otherwise.

• WhatsApp: image/jpeg, image/png up to 5 MB; video/mp4, video/3gpp, audio/aac, audio/amr, audio/mpeg, audio/mp4, audio/ogg up to 16 MB; PDF, plain text and Office documents up to 25 MB.
• Messenger: image/jpeg, image/png, image/gif up to 8 MB; video/mp4; audio/aac, audio/mpeg, audio/mp4, audio/wav; PDF, plain text and Office documents; all up to 25 MB.
• Instagram (when outbound media is on): image/jpeg, image/png up to 8 MB; video/mp4, video/quicktime, video/webm; audio/aac, audio/mp4, audio/wav; up to 25 MB. No documents.

A company stores at most 20 GB (413 media_too_large, details.reason tenant_quota).

The upload can be sent for 7 days (reusable_until) as content.{image|video|audio|document}.media_id; the file is kept 90 days after the last send that used it. An optional Idempotency-Key (company scope): the same key with the same file returns 200 with the first upload and Idempotent-Replayed: true, another request with the same key gets 409 idempotency_key_reused.

Needs the media:read scope. Inbound files (the media.id of a message.received image, video, audio, document or sticker), your uploads and the files UPPU fetched from your links. A file of a channel the key cannot see is 404. state is pending while UPPU downloads the file, ready once it is stored, failed with failure_reason, expired after retention (inbound 90 days; an upload 90 days after its last send). Messenger and Instagram: every media attachment of a message is its own file (content.{type}.media and content.{type}.attachments), whatever attachment comes before it, as is the preview of a shared post or a reel sent without a media attachment (content.unsupported.media). Instagram stories (a story reply's story, a story mention) are never downloaded: Meta does not allow storing story content. Meta's attachment links are short-lived: UPPU downloads them at once and retries temporary errors within the link's 24 hours. If a temporary error lasts so long that the next retry would fall outside those 24 hours, the file ends as failed with download_failed (about 16 hours of continuous outage with today's schedule). An expired link (Meta answers 403, 404 or 410, or the download could not start within 24 hours) ends as failed with provider_expired.

Needs the media:read scope; at most 10 requests per second and 2 GB per hour per key. Returns the bytes with Content-Type, Content-Length, ETag ("<sha256>"), Content-Disposition: attachment, X-Content-Type-Options: nosniff and Cache-Control: private, no-store; Range requests work (one range per request). The hourly byte budget is charged with the bytes a single range asks for; a request without Range, with several ranges or with If-Range is charged the whole file. While the file is still downloading the answer is 409 media_not_ready with Retry-After: 2 at once; the request is not held. A failed file is 422 media_unavailable (details.reason), a file past retention 410 media_expired. There are no signed URLs.