API reference

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. The API never masks text; a message older than the short retention of the special-category data protection may already be masked in storage (see the Message schema).

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. The API never masks text; a message older than the short retention of the special-category data protection may already be masked in storage (see the Message schema).

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. Telegram has no reply window: a bot can write to a person who wrote to it first (their telegram identity exists) until they block it (422 recipient_unreachable); Telegram reports only sent (no delivered or read; see capabilities.delivery_statuses). Session content (text, interactive, reaction, location) needs the 24-hour window on WhatsApp, Messenger and Instagram; 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. On Messenger and Instagram the person's reaction counts like a message (added within v1; removing a reaction does not). 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 (on Telegram the file travels inside the send call itself). Added within v1: stickers (by media_id only) and contact cards on WhatsApp and Telegram (see StickerContent and ContactsContent); other channels get 422 content_not_supported_on_channel. Show the person that an answer is coming with POST /conversations/{id}/typing.

E-mail channels (added within v1): text and media (image, video, audio, document; the file travels as an attachment of the e-mail). Address the person by contact_id or by their email identity (the address they wrote from; they must have written to the channel first); a phone gets 422 recipient_invalid. There is no reply window. UPPU sends from the channel's sending address, DKIM-signed with the key of its verified domain, as a reply in an e-mail thread of the person (subject "Re: ...", In-Reply-To and References): by default the conversation's last received e-mail, or the received e-mail you name in context.message_id (a person can have several threads in one open conversation; another kind of message gets 422 reply_target_invalid with details.reason not_an_email). Without a sending address or a verified domain the send gets 409 channel_unavailable (details.reason no_sender or sender_unverified; email_off while UPPU's e-mail channel is switched off). E-mail reports only sent (UPPU's mail server took the message) and failed (it could not, or the recipient's server bounced it: error.code recipient_unreachable).

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.

Optional ttl (added within v1, accepted once UPPU switches it on, until then 422 validation_failed with code unknown_field): the message's time to live, whole seconds from 10 to 86400 (24 hours). If UPPU has not handed the message to the provider by created_at + ttl (it waited in the queue, for the rate limit, for a retry, or the channel could not send), UPPU stops trying: status expired, error.code ttl_expired, a message.status event with status expired; nothing reaches Meta or Telegram. If an earlier attempt reached the provider and it answered with an error (for example its rate limit or a temporary error), the ttl only ends UPPU's retries: status failed with that error (for example provider_rate_limited or provider_unavailable), as when the retries run out without a ttl. The check runs before every attempt and every minute, so expired usually follows the deadline within about a minute; when thousands of messages run out at once it can take a few minutes longer, but nothing is sent after the deadline. A message handed over before the deadline is sent and never recalled (Meta's own retry period for an undelivered message is separate and set on the template, not per message). Without ttl nothing changes. On web chat a message is delivered when it is written, so ttl has no effect there. ttl is part of the body: the same Idempotency-Key with another ttl gets 409 idempotency_key_reused.

Needs the messages:send scope. Only a WhatsApp message the contact sent. Read receipts exist only on WhatsApp: a message on any other channel (web chat, Messenger, Instagram, Telegram) is 422 content_not_supported_on_channel with details.type read_receipt and details.channel_type. On a WhatsApp channel, any other target is 422 not_inbound with details.reason: outbound (sent by the business), reaction (WhatsApp has no read receipt for reactions), system_notice (a WhatsApp notice such as a number change), not_a_message (an event stored as an unsupported message, such as request_welcome), unsupported_message (a message Meta delivered with its own unsupported type, content.unsupported.provider_type unsupported; Meta does not accept a read receipt for it) or no_provider_id. These never reach Meta. not_inbound is final and not retryable: a repeat gets the same answer and nothing is queued. A client that marks every received message as read should treat it as nothing to mark and accept reason values it does not know; the values listed never change. 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 contacts:read scope. The same object as POST /contacts/lookup: the identities on the key's channels (superseded ones with current false), the reply window per WhatsApp, Messenger and Instagram channel and the current consent per channel type and purpose. A contact without an identity or a conversation on the key's channels is 404: a channel-bound key sees only the contacts of its channel.

Needs the contacts:read scope. The contact's consent ledger, newest record first unless order=asc: every grant and withdrawal, also the automatic ones (the person's STOP message, Meta's marketing opt-out) and the ones the company recorded in the UPPU panel or imported from a file. Records are never changed; the current state per channel type and purpose is the record with the latest collected_at (a withdrawal wins a tie), which the contact's consents summary shows. A record added later can be older than the current one: the newest record (and the latest contact.consent_changed event) is not always the current state. created_after and created_before filter on recorded_at. A contact the key cannot see is 404.

Needs the consents:write scope. Adds a record to the contact's consent ledger (records are never changed): a grant or a withdrawal of the marketing or utility purpose, on a WhatsApp channel (another channel type gets 422 content_not_supported_on_channel). Address the person by contact_id (the contact needs an identity on the channel), by phone (E.164; the channel's contact with that phone, otherwise a new unverified contact) or by an identity that already exists on the channel. source_text (the exact text the person agreed to) and source_ref (your reference to the evidence, no personal data) are required. collected_at is when the person gave or withdrew the consent: now if left out, never in the future. A grant without collected_at gets 422 validation_failed (collected_at) while the latest record is a withdrawal: send the time the new consent was collected. Template sends read the record with the latest collected_at (a withdrawal wins a tie). Every new record emits contact.consent_changed; the event reports the record that was written, not the current state (a grant older than a newer withdrawal is recorded and sent as granted while the withdrawal stays in effect): read the current state from the contact's consents summary (GET /contacts/{id}). An optional Idempotency-Key (company scope): the same key with the same consent (contact, purpose, state, source_text and source_ref) returns 200 with the first record and Idempotent-Replayed: true, another consent with the same key gets 409 idempotency_key_reused. Without a key every request adds a record.

Needs the messages:read scope. Conversations of the key's channels, newest first unless order=asc. Filter by contact_id, channel_id and status (open or resolved); an id the key cannot see is 404. created_after and created_before filter on opened_at. The cursor carries the order; repeat the filters and the time filters on every page. A conversation resolved or reopened between two pages keeps the cursor valid: the next page continues after it, so you can resolve the conversations of a page before asking for the next one.

Needs the messages:read scope. A conversation outside the key's channels, or past retention, is 404. The assignee is never shown, only whether the conversation is assigned. service_window is the contact's current 24-hour reply window on the conversation's channel (null on web chat, Telegram and e-mail).

Needs the conversations:write scope. Send an empty body or {}. Resolves an open conversation the way the team inbox does (the same audit record, with your key as the actor); a conversation that is already resolved stays as it is. Both answer 200 with the current conversation, so a retry is safe. The person's next message opens a new conversation. Endpoints subscribed to conversation.updated get it with change resolved (added within v1). A read-only company gets 403 tenant_read_only.

Needs the conversations:write scope; added within v1. On a channel your system (handling api) or UPPU Bot (handling bot) answers, gives the conversation to the team: held_by becomes team, handed_over_at is set, handover_reason is api, and the conversation joins the team inbox's normal views (Unassigned, waiting for a reply). The team gets UPPU's usual handover help: the channel's automatic assignment when it is on, and an e-mail when no one replies within 10 minutes. On a bot channel UPPU Bot stops at once and sends nothing more in the conversation. Nothing is sent to the person; send your own message with POST /messages if you want to. Send an empty body, {} or {reason, note}: reason is a short code of your own (at most 64 characters: letters, digits, dot, underscore, colon, hyphen; no personal data), note a text for the team (at most 1000 characters). Both appear only in the team inbox, next to the handover; the API and the webhooks never return them. A conversation that is already with the team stays as it is, and nothing is written again. Both answer 200 with the current conversation, so a retry is safe. Endpoints subscribed to conversation.updated get change handed_over once. An inbox channel gets 422 handling_not_supported (details.handling), and so does a company whose plan has no messaging panel (details.reason not_in_plan: there is no team to hand over to); a resolved conversation gets 409 not_held. A read-only company gets 403 tenant_read_only.

Needs the conversations:write scope; added within v1. Send an empty body or {}. Gives a conversation the team holds back to the automation of its channel: on an api channel to your system (held_by api, the conversation leaves the team's views for the inbox's API view), on a bot channel to UPPU Bot (held_by bot, the way "Return to bot" in the inbox does: UPPU Bot answers only the person's next message, never the older ones). handed_over_at and handover_reason become null and the assignment is removed. A conversation the automation already holds stays as it is, and nothing is written again. Both answer 200 with the current conversation, so a retry is safe. Endpoints subscribed to conversation.updated get change released (api channel) or returned_to_bot (bot channel), after unassigned when someone was assigned. On a bot channel UPPU Bot must be able to take the conversation, otherwise 409 bot_not_ready with details.reason bot_unavailable (UPPU Bot is off on the channel or for the company), bot_busy (it is still finishing its turn from before the handover; retry in a few seconds) or reply_first (the person's last message has no reply yet, from the team or your system; reply first). An inbox channel gets 422 handling_not_supported, a resolved conversation 409 not_handed_over, a read-only company 403 tenant_read_only.

Needs the messages:send scope; added within v1. Shows "typing…" to the contact of the conversation while your system prepares an answer. Send an empty body or {}; no Idempotency-Key. A typing indicator is not a message: nothing is stored, nothing is billed and no webhook event follows; it ends when your message arrives or after a short time set by the network (WhatsApp 25 seconds, Telegram 5 seconds), and cannot be switched off early. Call it again for a longer answer. GET /channels tells you where it works (capabilities.typing_indicator): WhatsApp, Messenger and Telegram; any other channel (web chat, Instagram) gets 422 content_not_supported_on_channel with details.type typing_indicator and details.channel_type.

On WhatsApp the indicator travels with Meta's mark-as-read call: it marks the newest message the contact sent in this conversation (and the earlier ones) as read, the same target rules as POST /messages/{id}/read; message_id in the answer names that message. Without such a message from the last 30 days the answer is 422 not_inbound with details.reason no_inbound_message. The rules of a send apply: the 24-hour window on WhatsApp and Messenger (422 window_closed), a paused or unavailable channel (409), a shadow channel (403 shadow_mode), a blocked contact (422 contact_blocked) and, on Telegram, a person who blocked the bot (422 recipient_unreachable). At most one indicator per conversation every few seconds (429 rate_limited with details.scope conversation and Retry-After) and a per-key limit of its own. The answer is 202 with state queued; the outcome is not reported. A read-only company gets 403 tenant_read_only.

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:write scope (added within v1). No preset includes it and existing keys do not have it: the owner adds it to a key on the developer page on purpose. Creates the template in the WhatsApp Business account of the channel with the rules of the panel's template page: name of lowercase letters, digits and underscores; language tr or en; category UTILITY or MARKETING; an optional text header with at most one variable; the body with numbered ({{1}}, {{2}} ...) or named ({{first_name}}) variables and an example for each; an optional footer; buttons: up to 3 quick replies, 2 URL buttons (a variable only as {{1}} at the end of the address, with an example of that end) and 1 phone number, the quick replies next to each other. A header with an image, a video or a document (added within v1) takes a sample file: the media_id of an upload of the same channel made with POST /media, {"type": "image", "image": {"media_id": "..."}}; a JPEG or PNG image up to 5 MB, an MP4 video up to 16 MB, a PDF document up to 25 MB (otherwise 422 validation_failed with code mime_not_allowed, or 413 media_too_large); an upload of another channel, an expired one or one past its reuse period gets 422 media_unavailable (details.reason). UPPU uploads the sample to Meta with Meta's Resumable Upload before it creates the template; Meta's refusal of the sample is 422 validation_failed with field header.<type>.media_id, code sample_refused and Meta's code in provider_error, and no template is created. The upload and the create run within the time of the request (about 26 seconds): when the upload leaves no time for the create, the answer is 503 provider_unavailable with details.reason unreachable and nothing is created (retry, or use a smaller sample). A retry after unconfirmed with the same Idempotency-Key and template gets the template Meta created even when the sample's upload is no longer usable. A header with a location cannot be created here (422 validation_failed, field header.type, code not_supported). A field that breaks a rule gets 422 validation_failed with the field's path (header.text, body.examples.1, buttons.0.url) and code invalid. The answer is 201 with the template, usually status PENDING: Meta reviews it, mostly within 24 hours, and template.updated reports the result. The same name and language again, or a name whose every language was deleted within 30 days, gets 422 validation_failed with field name (code exists or name_blocked); Meta allows 100 new templates per hour for a WhatsApp account (429 rate_limited, details.reason templates_per_hour, with Retry-After). Meta's refusal of the template is 422 validation_failed with field template, code meta_refused and Meta's code in provider_error. The call to Meta runs inside the request: one template create or delete at a time per company (429 rate_limited with details.reason concurrent_writes otherwise) and at most 10 per minute per company. When Meta's own rate limit is reached (for example templates created outside UPPU) the answer is 429 rate_limited with details.reason provider_rate_limited, Retry-After and Meta's code in provider_error. When Meta cannot be reached the answer is 503 provider_unavailable with details.reason unreachable (nothing was created); when Meta does not answer in time or answers with a temporary error, unconfirmed (the template may have been created). A retry with the same Idempotency-Key and template is safe: UPPU looks at Meta again and answers 200 with the template and Idempotent-Replayed: true when the earlier request created it, creates it when it did not, and answers unconfirmed again when Meta still cannot be read. Without a key, read GET /templates?name=&language= after a minute before you retry. A channel that is not WhatsApp gets 422 content_not_supported_on_channel (details.type template); a key bound to one channel that names another channel 403 channel_not_allowed; a channel without a usable WhatsApp connection 409 channel_unavailable (details.reason; credentials also when Meta refuses the account's access token, with Meta's code in provider_error); a number in shadow mode 403 shadow_mode. An optional Idempotency-Key (company scope): the same key with the same template answers 200 with the template as it is now and Idempotent-Replayed: true; another template with the same key gets 409 idempotency_key_reused. A read-only company gets 403 tenant_read_only.

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

Needs the templates:write scope (added within v1; in no preset). Deletes this template, in this language only: UPPU sends Meta the template's id together with its name, so the other languages of the name stay. Delete every language one by one to remove a name; once every language of a name is deleted, Meta lets you use the name again only after 30 days (a create with it gets 422 validation_failed, field name, code name_blocked). The template stays readable with status DELETED. Answers 200 with {object, id, name, language, deleted}; a template that is already deleted answers the same without calling Meta. Send an empty body or {}. Meta's refusal is 422 validation_failed with field template, code meta_refused and Meta's code in provider_error; Meta's rate limit (429 provider_rate_limited), 503 provider_unavailable (unconfirmed: the template may have been deleted), 409 channel_unavailable, 403 shadow_mode and the limits are those of creating. A template outside the key's channels is 404. A read-only company gets 403 tenant_read_only.

Needs the reports:read scope (added within v1; in no preset, existing keys do not have it). The figures of the panel's Reports page, counted every night: conversations the contacts opened and those that reached the team, the ones left unanswered on their day, the team's replies, first response and resolution times, resolutions and reopenings, the open conversations at the end of the period, SLA targets met and missed, topics and tags; for the whole company also per channel, agent and group. Counts only: no contact, conversation or message. The period is days=7, 30 or 90 finished days (30 by default) or from and to (calendar days in the company's time zone, at most 90 days); it ends on the last day the nightly count has finished (period.to and period.counted_through; period.pending is true while yesterday is still being counted), so a to in the future or not counted yet is moved back. Any other value of the period gets 422 validation_failed (for example a period longer than 90 days, field from, code max). One of channel_id, member_id or group_id narrows the scope; an id the key cannot see is 404. A key bound to one channel reads only its channel (member_id and group_id get 403 channel_not_allowed). A channel UPPU stopped for the API gets 403 api_disabled, and its counts are one row with hidden true among the per-channel rows; the totals and the agent and group rows count every channel of the company. Durations are given per bucket (1m, 5m, 15m, 30m, 1h, 4h, 8h, 24h, 72h and over for first responses; 15m, 1h, 4h, 8h, 24h, 72h, 7d and over for resolutions: at most that long); median and p90 name the bucket in which half and nine tenths of the samples fall. The report's tier (tier, features) is that of the panel: with basic, agents, groups, SLA, topics and tags are null. Reports are part of the messaging panel: a company whose plan does not include it gets 403 api_disabled with details.resource reports and details.reason not_in_plan. At most 2 requests per second per key, together with GET /reports/daily.

Needs the reports:read scope. The figures of each day of the period and scope (the period, the scope and the rules of GET /reports/summary), newest day first unless order=asc; a day without figures has zeros, and counted says whether the nightly count has finished that day. open and open_unassigned are the open conversations at the end of the day. Pass next_cursor as cursor for the next page and repeat the period and the scope on every page.

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 and, added within v1, account.service_stop_scheduled and account.service_resumed) 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 two fields: channel_id (a WhatsApp, Messenger, Instagram, Telegram or, added within v1, web chat channel the key can use; 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; added within v1, an optional third field kind (see Stickers below). Any other field gets 422 validation_failed with code unknown_field. 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. The lists below are UPPU's: for WhatsApp and Instagram they stay within the types and sizes in Meta's documentation, which gives Messenger's sizes but no list of Messenger types. 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. UPPU checks the type and the size only. WhatsApp also requires 8-bit RGB or RGBA images, H.264 video with AAC audio (at most one audio stream) and OGG audio in Opus, mono; it can refuse a file that breaks these rules when the message is sent (message.status failed, for example with media_rejected).
• 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.
• Telegram (added within v1): image/jpeg, image/png, image/webp up to 10 MB (Telegram's photo limit); video/mp4; audio/mpeg, audio/mp4, audio/aac, audio/ogg (sent as a voice note); PDF, plain text and Office documents; all up to 25 MB (UPPU's cap, below Telegram's 50 MB).
• Web chat (added within v1): image/jpeg, image/png, image/webp, image/gif up to 10 MB; video/mp4, video/webm, video/quicktime; audio/mpeg, audio/mp4, audio/aac, audio/ogg, audio/wav; PDF, plain text, Office and OpenDocument documents; all up to 25 MB. UPPU removes an image's metadata (EXIF with the location, XMP, comments) without re-encoding it and keeps its orientation; size and sha256 are those of the stored file. The visitor gets the file in the chat widget through a short-lived link.
• Stickers (added within v1): send the field kind with the value sticker to upload a sticker for content.sticker.media_id on WhatsApp and Telegram; another channel gets 422 content_not_supported_on_channel with details.type sticker, another value of kind 422 validation_failed (code in). The file must be a WebP of exactly 512×512 pixels, static up to 100 KB or animated up to 500 KB (WhatsApp's sizes; Telegram: static only). The upload's kind is sticker and the rules are checked here, in this order: another type gets 415 unsupported_media_type; then 422 validation_failed for the file with code sticker_unreadable when UPPU cannot read the WebP header, code sticker_animated_not_allowed for an animated file on a channel that sends static stickers only (whatever its size), 413 media_too_large for a file over the limit of its own kind, static or animated as read from the header (details.kind sticker, max_bytes of that limit, animated; a static file over 500 KB gets the static 100 KB), and code sticker_dimensions for other dimensions. Without kind an upload is checked as before: on WhatsApp a WebP gets 415 unsupported_media_type; on Telegram a WebP is a photo (kind image) that can also be sent as a sticker, with the sticker rules checked in the same order when it is sent.

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|sticker}.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. Telegram (added within v1): every file of an inbound message (photo, video, video note, animation, voice note, audio, document, sticker) is downloaded by UPPU with the bot's token; neither Telegram's file id nor its file address is ever exposed. A file over 20 MB (Telegram's bot download limit) ends as failed with too_large; a file Telegram does not know any more ends with provider_refused. Temporary errors (Telegram unreachable, 5xx, 429, a rejected bot token until it is renewed) are retried in ten steps from 30 seconds to 24 hours (about 52 hours with today's schedule), then once a day; the last attempt is made when about an hour or less of the 7 days after receipt remains, even when earlier attempts were delayed (usually the shortened step exactly an hour before; only a file whose first attempt falls within that last hour is retried within it, on the common schedule while the next step fits), so a token renewed before the last attempt still brings the file, at most a day later. If the last attempt fails too, the file ends as failed with download_failed or no_token; a file UPPU could not try at all within those 7 days ends with download_failed. Web chat (added within v1): a file the visitor sends from the chat widget is stored as it arrives (ready at once; failed with quota_exceeded when the company's storage is full, the message is still written). The types and sizes are those of POST /media for web chat; an image's metadata is removed in the same way.

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. To hand a file over without your key, create a short-lived signed link (POST /media/{id}/link; added within v1).

Needs the media:read scope (added within v1). Returns a short-lived signed address that downloads the file without your API key, for example to hand a file to a browser or to another system of yours. Send an empty body or {}. The link works until expires_at (a few minutes; 5 today) and for at most max_uses requests, Range requests included. Only the expiry revokes a link: it cannot be cancelled. It is signed for this file of this company only and opens no other file, but anyone who has it can download the file until it expires: share it like the file itself. The file must be ready: 409 media_not_ready while it downloads, 422 media_unavailable when it failed, 410 media_expired after retention. Issuing a link counts as one request against the per-second limit of GET /media/{id}/content and needs room for one download of the whole file in the key's hourly byte budget (otherwise 429 rate_limited with details.reason bytes); it charges no bytes. Every download through the link then counts against the hourly byte budget of this key, as GET /media/{id}/content does. A read-only company can issue links too (it is a read).

No API key (added within v1): the query string of the url that POST /media/{id}/link returned authorizes the request; use that url as it is. Returns the bytes with the headers of GET /media/{id}/content (Content-Disposition: attachment, X-Content-Type-Options: nosniff; one Range per request). A link that is not valid, or a link for another file, company or key, answers 404 not_found with details {"resource": "media_link", "reason": "invalid"}; an expired link the same with reason expired. A link used more than max_uses times answers 429 rate_limited with details.reason link_uses until it expires. Every download counts against the hourly byte budget of the key that issued the link (the budget of GET /media/{id}/content; a Range request with the bytes it asks for); when it is used up the answer is 429 rate_limited with details.reason bytes and Retry-After, and the refused request does not use up the link. A file that is no longer available answers 410 media_expired or 422 media_unavailable; 403 api_disabled when the company's plan no longer includes the API or UPPU stopped the channel. Browsers can open the link; no CORS headers are sent.

Needs the webhooks:manage scope (added within v1). No preset includes it and existing keys do not have it: the owner adds it to a key on the developer page on purpose. The company's webhook endpoints, the same ones the panel's Webhooks page shows, newest first unless order=asc. A key bound to one channel sees only the endpoints whose channel filter is that channel. The full address and the signing secret are never listed: url is masked (scheme, host and /...) and secret is null.

Needs the webhooks:manage scope. The rules of the panel's Webhooks page: https on port 443 only and a public host whose every address is public; a refused address gets 422 validation_failed with field url and the reason as its code (for example not_https, port_not_allowed, credentials_in_url, dns_unresolved, private, loopback or datacentre). events: at least one type a webhook endpoint can subscribe to; left out, the types that are on by default (message.received, message.status, contact.identity_changed, contact.erased, channel.status_changed, contact.reachability_changed). channel_id: null for every channel; left out, every channel, or the key's own channel for a key bound to one channel (which gets 403 channel_not_allowed for null or another channel). ordering best_effort (default) or strict; max_in_flight 1 to 32 (default 8); weekly_test (default false). A company has at most 5 endpoints: one more gets 409 plan_limit_reached with details resource webhook_endpoint, max and used. The new endpoint is pending_verification and gets no events until it passes a test event and the wrong-signature probe and is activated (POST /webhook-endpoints/{id}/test, /probe and /activate). The answer carries the signing secret in secret, only this once: store it on your server. An optional Idempotency-Key (company scope): the same key with the same body answers 200 with the endpoint, Idempotent-Replayed: true and secret null (if you lost the first answer, rotate the secret); another body with the same key gets 409 idempotency_key_reused. A read-only company gets 403 tenant_read_only. The address is looked up in DNS during the request, one at a time per company together with test events and probes: a create that would have to wait gets 429 rate_limited with details.reason concurrent_checks and Retry-After, and nothing is created.

Needs the webhooks:manage scope. An endpoint of another company, or outside the channel of a key bound to one channel, is 404. verification says whether a test event and the wrong-signature probe passed within the last hour (the conditions of activation); weekly_test is the optional weekly test event.

Needs the webhooks:manage scope. Changes only the fields you send, with the rules of creating; an empty body changes nothing. A new url sends the endpoint back to pending_verification (its events wait) until it passes the test event and the wrong-signature probe again and is activated; a disabled endpoint stays disabled. A key bound to one channel cannot remove the channel filter or move it to another channel (403 channel_not_allowed). A read-only company gets 403 tenant_read_only. A body with url is looked up in DNS as on create, one at a time per company together with test events and probes (429 rate_limited with details.reason concurrent_checks otherwise, and nothing changes); a body without url is not.

Needs the webhooks:manage scope. Deletes the endpoint and its deliveries; the events stay available for the other endpoints and for GET /events. Answers 200 with {object, id, deleted}. A read-only company gets 403 tenant_read_only (the panel can still delete it).

Needs the webhooks:manage scope. Send an empty body or {}. Creates a new signing secret and returns it in secret, only in this answer: no endpoint shows a secret again. The secret it replaces keeps signing for 24 hours (webhook-signature then carries two v1 values; secret_rotating_until says until when): switch your receiver to the new secret within that time. A rotation keeps only the secret it replaces, so rotate again only after your receiver uses the newest secret.

Needs the webhooks:manage scope. Sends a sample event of type (webhook.test if left out) to the endpoint now, with the endpoint's signature and the published egress IP, test true in the body, and answers with the result: passed (your server answered 2xx), status, latency_ms, the first characters of the answer and the error, if any. The request waits for your server (at most 10 seconds). Tests and probes together: at most 10 per minute for all keys of the company, one at a time per company and only a few at once for the whole service. A check that would have to wait is not queued: it answers 429 rate_limited with details.reason concurrent_checks and Retry-After, nothing is sent and it is not counted; send it again then. A passing test also clears the warning of a failed weekly test. A test that passed within the last hour is a condition of activation. The event is not stored and not listed by GET /events.

Needs the webhooks:manage scope. Send an empty body or {}. Sends webhook.test signed with a wrong secret. It passes when your server refuses it (any HTTP answer other than 2xx): that shows your receiver checks the signature. A 2xx answer or a connection error does not pass. A new endpoint, and an endpoint whose address changed, needs a passing probe within the last hour to be activated. Counted with the tests: at most 10 per minute for the company, one at a time (429 rate_limited with details.reason concurrent_checks otherwise).

Needs the webhooks:manage scope. Send an empty body or {}. Starts the deliveries: a pending_verification endpoint needs a passing test event and a passing wrong-signature probe within the last hour; a suspended or disabled endpoint a passing test event (and the probe too when its address changed). Otherwise 422 validation_failed with field endpoint and code not_verified. Held events are then delivered in order. An endpoint that already receives events stays as it is (200).

Needs the webhooks:manage scope. Send an empty body or {}. Stops the deliveries: pending, waiting and held deliveries become dead (the panel can send them again for 30 days). Activate it again after a passing test event. A disabled endpoint stays disabled (200).

Staging only (https://messaging-staging.uppu.net/v1 with a uppu_test_ key); the live API has no /sandbox paths (404). Needs the messages:send scope and a simulated channel, created on the developer page of the staging panel; any other channel gets 422 validation_failed (channel_id not_simulated). Nothing reaches Meta.

The content has the shape of a received message's content (message.received): text, image, video, audio, document, sticker (media_id of a file uploaded to the same channel with POST /media, otherwise a sample file), location, contacts, interactive_reply (a button or list reply; source template for a template's quick-reply button), reaction (message_id of a message on this channel; an empty emoji removes it) and unsupported (Meta's own unsupported type: marking it as read gets 422 not_inbound with details.reason unsupported_message, as on a real channel). from needs phone (E.164), bsuid or both. context.message_id makes it a reply. The event goes through the normal inbound pipeline: contact, conversation, 24-hour window, media download and the message.received webhook event are the same as for a real message.

Staging only. A delivery status for an outbound message on a simulated channel: sent, delivered, read or failed (provider_code is Meta's error code, default 131026). Statuses only move forward; a status that does not advance is ignored (reason status_stale). The message.status webhook event follows as for a real status. Without this call a simulated send walks through accepted, sent, delivered and read by itself; the last two digits of the recipient's phone choose another outcome (see the developer page).

Staging only. The contact's current BSUID on a simulated channel changes to new_bsuid; the contact.identity_changed webhook event follows with reason user_id_update (a live change has reason user_changed_user_id or, when the person changed their number, user_changed_number). A contact without a BSUID on a simulated channel gets 422 validation_failed (contact_id no_bsuid): simulate an inbound message with from.bsuid first.

Staging only. Moves the contact's last inbound message on simulated channels more than 24 hours back: a session message then gets 422 window_closed and only a template can be sent. No webhook event. Send an empty body or {}.

Staging only (added within v1). Writes the checklist of a simulated channel as a fixed scenario, so the channel object (health) changes and endpoints subscribed to channel.health_changed get the same event a real channel sends: green (every item green), amber (account_limited: Meta limits the account) or red (not_registered: the number is not connected). messaging_limit and quality are the event's messaging_limit and quality; they alone do not change the health, so they send no event. No real channel is touched and no e-mail goes out. The same status again gives outcome ignored with reason health_unchanged. A real channel gets 422 validation_failed (field channel_id, code not_simulated).

Staging only (added within v1). Sends Meta's template status notice for a template of a simulated channel through the normal pipeline: the template's status changes (GET /templates shows it) and endpoints subscribed to template.updated get the same event a real template sends. status: APPROVED, PENDING, REJECTED (with an optional reason, NONE if left out), PAUSED or DISABLED. A template that is not APPROVED cannot be sent (422 template_not_approved); APPROVED makes it sendable again. A template of a real channel gets 422 validation_failed (field template_id, code not_simulated).

Staging only, without a key. Not part of the API you call: UPPU Bot's actions call it on staging in place of a company's own API, to rehearse a read. Answers fixed sample data and ignores the query, apart from the options below. At most 120 requests a minute per client address (429 with {"error": "rate_limited"}). A delay is honoured only for UPPU's own address, one request at a time; other requests answer without it. The live API has no /sandbox paths.

Staging only, without a key. UPPU Bot's write actions call it on staging to rehearse a write that happens at most once. The Idempotency-Key header is required (400 with {"error": "idempotency_key_required"} otherwise). The write is recorded before the delay, so a client that gives up or dies while waiting still leaves it recorded. The same key gets the same reference; receipts counts how often that key arrived. The request body is not stored.

Staging only, without a key. The last 100 idempotency keys of writes, newest first, with how often each arrived: a write that UPPU Bot sent once shows receipts 1. Kept for 24 hours; no personal data (a key is a bot turn's id and a step id).

One event per request, compact UTF-8 JSON, at most 256 KB, from the published egress IP. Verify the signature over the raw body: base64(HMAC-SHA256(base64decode(secret without "whsec_"), webhook-id + "." + webhook-timestamp + "." + body)), compared in constant time; refuse a timestamp more than 300 seconds away; drop repeats by webhook-id (keep ids for at least 35 days). During a secret rotation webhook-signature carries two space-separated v1 values. Answer 2xx within 10 seconds and process later. Any other answer is retried 12 times over about 76 hours; 410 suspends the endpoint. Delivery is at least once and FIFO per contact; message.status carries previous_status for reordering. message.status can carry status expired (added within v1; previous_status queued): the ttl of the send ran out before UPPU handed it to the provider, nothing was sent, error.code is ttl_expired. When an earlier attempt got an error answer from the provider, the ttl ends the send as failed with that error instead. Rank expired with accepted and unknown, below sent: in the rare case that the provider took the message after all (UPPU could not reach it and counted the attempt as not delivered), a later sent, failed, delivered or read still moves it forward. message.received carries service_window {open, closes_at}, counted from Meta's timestamp of the message: a message Meta delivered late (received_at far after sent_at) can arrive with open false; on WhatsApp answer it with a template. On Messenger and Instagram the person's reaction opens the window as a message does (added within v1). On web chat, Telegram and e-mail service_window is null (no reply window). contact.reachability_changed (added within v1, Telegram) carries {contact_id, channel_id, identity: {type, value}, reachable, reason, occurred_at}; reason is blocked_by_contact, send_forbidden (both reachable false), unblocked_by_contact or contact_wrote (both reachable true). channel.status_changed carries {channel_id, status, previous_status, mode, previous_mode, reason}; when Meta tells UPPU that a WhatsApp Business account left UPPU, status is disconnected and reason is partner_removed, account_deleted or account_offboarded (the last two added within v1). Accept unknown reasons. conversation.updated (produced within v1; subscribe to it explicitly, new endpoints leave it off) carries ConversationUpdate: the conversation as GET /conversations/{id} returns it, change (handed_over, returned_to_bot, released, resolved, reopened, assigned, unassigned), reason, actor {type, api_key_prefix} and occurred_at. It is written only while an endpoint of the company subscribes to it, so GET /events has it only then too. Accept unknown changes, reasons and actor types. contact.updated (added within v1; subscribe to it explicitly, new endpoints leave it off) carries ContactUpdate: the contact as GET /contacts/{id} returns it to a key for all channels, changes (the names of the fields that changed: display_name, identities, merged_into, notes, attributes), reason and occurred_at; the envelope's channel is null. One change sends one event, a merge and its undo one for each of the two contacts; a change of the team's notes alone sends none. The contact carries its identities on all channels, so an endpoint with a channel filter gets it only when all of the contact's identities and conversations are on that channel. It is written only while an endpoint of the company subscribes to it. UPPU switches it on per environment; until then it can be subscribed to and nothing is sent. The opening of a contact is not a change (message.received carries it). Accept unknown changes and reasons. account.service_stop_scheduled and account.service_resumed (added within v1; on by default for new endpoints, which can leave them out of their event list) go to every subscribed endpoint of the company whatever its channel filter; the envelope's channel is null, so GET /events lists them only for an all-channels key. account.service_stop_scheduled carries {stop_at, reason, occurred_at} (reason billing_overdue or subscription_ended): the service stops at stop_at unless the payment is recorded first. If the warning reached nobody and goes again, a second account.service_stop_scheduled names a later stop_at: the instant only moves later, and UPPU-Service-Stop-At always carries the current one. account.service_resumed carries {stopped_at, resumed_at, occurred_at}. A stopped company produces no other event; its due deliveries end dead with last_error service_stopped and are not sent by themselves after the resume (resend them). An endpoint can opt in to a weekly test event (weekly_test; added within v1): UPPU then sends webhook.test, test true, once a week. A failed weekly test is only a warning on the endpoint (weekly_test.failed_at); the endpoint is never suspended for it.