Skip to content

Developers

API reference v1

Endpoints, parameters and the webhook event of the UPPU customer API, generated from the copy of the OpenAPI document pinned on this site (commit and date below). It shows what you can use on the live API today; the schemas are on two pages of their own. For a guided start, read the quickstart; for events, the webhooks guide.

  • API version v1
  • OpenAPI 3.1.0
  • Generated from a1fec8942 · 19 November 2026

Servers and authentication

Servers
EnvironmentBase URLKey
Livehttps://messaging.uppu.net/v1uppu_live_…
Staginghttps://messaging-staging.uppu.net/v1uppu_test_…
  • Send Authorization: Bearer <key> on every request. A key of the other environment gets 401 wrong_environment.
  • Call from your server. A request with an Origin header gets 403 browser_request_refused, so there is no “try it” button here.
  • Scopes are listed with each endpoint; a missing scope gets 403 insufficient_scope with details.required.

Conventions

  • IDs are lowercase ULIDs; times are RFC 3339 UTC with milliseconds; null fields are always present.
  • Unknown request fields get 422 validation_failed (unknown_field). Ignore unknown response fields and event types, accept unknown enum values and treat an unknown content.type as unsupported.
  • Lists take limit, cursor, order, created_after and created_before, and return next_cursor.
  • Rate limits, retries and the Idempotency-Key rules are explained on the developers overview.

Errors

Every error is an ErrorEnvelope. error.code is the stable contract and error.retryable tells you whether to retry. The error codes page lists every code.

Channels

The channels your key can use, with their status and what each one can send. A key bound to one channel sees only that channel.

GET/v1/channels

List the channels this key can use

  • Scope none (any key)

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

Parameters

GET /v1/channels: Parameters
NameInTypeDescription
limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc
created_afterquerystring (date-time)
created_beforequerystring (date-time)

Responses

GET /v1/channels: Responses
StatusDescriptionBody
200A page of channels

Headers UPPU-Service-Stop-At

ChannelList
400 401 403 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/channels/{id}

Get a channel

  • Scope none (any key)

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

Parameters

GET /v1/channels/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/channels/{id}: Responses
StatusDescriptionBody
200The channel

Headers UPPU-Service-Stop-At

Channel
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Messages

Send messages, read them back for reconciliation and mark inbound WhatsApp messages as read.

GET/v1/messages/{id}

Get a message of either direction

  • Scope messages:read

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

Parameters

GET /v1/messages/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/messages/{id}: Responses
StatusDescriptionBody
200The message

Headers UPPU-Service-Stop-At

Message
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/messages

List messages of either direction (reconciliation after a webhook gap)

  • Scope messages:read

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

Parameters

GET /v1/messages: Parameters
NameInTypeDescription
channel_idqueryId
conversation_idqueryId
contact_idqueryId
directionquerystring
  • in
  • out
limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc
created_afterquerystring (date-time)
created_beforequerystring (date-time)

Responses

GET /v1/messages: Responses
StatusDescriptionBody
200A page of messages

Headers UPPU-Service-Stop-At

MessageList
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/messages

Send a message

  • Scope messages:send
  • Idempotency-Key required

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 send refused by these rules creates no message (UPPU keeps only an internal record of the refusal); a validation error records 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.

Parameters

POST /v1/messages: Parameters
NameInTypeDescription
Idempotency-Keyrequiredheaderstring

Unique per channel for good (1 to 64 characters: letters, digits, dot, underscore, colon, hyphen). Use a UUID or ULID per logical send.

pattern ^[A-Za-z0-9._:-]{1,64}$

Request body

application/json · SendMessageRequest

POST /v1/messages: Request body
FieldTypeDescription
channel_idrequiredId
torequiredRecipient
contextobject

Reply to a message of the same channel and contact that has a provider id (WhatsApp; Telegram, a message of the contact's chat; e-mail, added within v1: a received e-mail of the contact, whose thread the reply joins).

contentrequiredOutboundContent
client_referencestring

Your opaque reference (no personal data); echoed in GET and in every message.status event.

min length 1 · max length 64

consentInlineConsent
ttlinteger

Added within v1, accepted once UPPU switches it on (until then 422 validation_failed, code unknown_field). The message's time to live in whole seconds. If UPPU has not handed the message to the provider by created_at + ttl, it is not sent: status expired, error.code ttl_expired (status failed with the provider's error when an earlier attempt got an error answer from the provider). Out of range or not a whole number: 422 validation_failed, field ttl, code between.

min 10 · max 86400

retryobject

Added within v1, accepted once UPPU switches account protection on for your company (until then 422 validation_failed, code unknown_field). With per_user_limit true, UPPU sends a WhatsApp template message again when Meta fails it with error 131049 (Meta's per-user marketing limit): at least 24 hours after each 131049 (plus a few minutes), only within 7 days after the first 131049 and at most 7 times. It has an effect only for MARKETING templates and only while your company keeps these retries switched on (account protection settings); on other templates the field is accepted and does nothing. Every attempt is checked again like a new send of this key: consent and opt-outs, the contact's block, the template's approval, category and parameters, uploads (a header or card upload can be used for 7 days after its upload, later the retry stops), the channel, and the key, its scope and your plan. Each attempt is a new message with a new id and the same client_reference (message.created and message.status as for any message); the original message stays failed. Meta charges only delivered messages. Template content only, and not together with ttl: otherwise 422 validation_failed, field retry, code not_allowed. A per_user_limit that is not true or false: code boolean. The retry object of the message (in this answer, GET /messages/{id} and GET /messages) shows the state of the retries.

Responses

POST /v1/messages: Responses
StatusDescriptionBody
200A replay of an earlier send with the same Idempotency-Key and body

Headers UPPU-Service-Stop-At, Idempotent-Replayed

Message
202Accepted; status queued (WhatsApp, Messenger, Instagram, Telegram) or sent (web chat)

Headers UPPU-Service-Stop-At

Message
400 401 403 404 409 413 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/messages/{id}/read

Mark an inbound message as read

  • Scope messages:send

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

Parameters

POST /v1/messages/{id}/read: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/messages/{id}/read: Responses
StatusDescriptionBody
200The read receipt was already requested

Headers UPPU-Service-Stop-At

ReadReceipt
202The read receipt is queued

Headers UPPU-Service-Stop-At

ReadReceipt
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Contacts

Find a contact by phone number or identity, then read the contact and its consent records. The phone number and identity go in the request body, never in a URL.

POST/v1/contacts/lookup

Find a contact by phone or identity

  • Scope contacts:read

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 and, added within v1, Telegram channels) or identity. On a Telegram channel phone finds a phone identity of that channel: the number the person shared from their own Telegram account. A contact that is not found on the channel is 404. This is a read: it also works for read-only companies.

Request body

application/json · ContactLookupRequest

POST /v1/contacts/lookup: Request body
FieldTypeDescription
channel_idrequiredId
phonestring

pattern ^\+[1-9][0-9]{4,19}$

identityobject

Responses

POST /v1/contacts/lookup: Responses
StatusDescriptionBody
200The contact

Headers UPPU-Service-Stop-At

Contact
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/contacts/{id}

Get a contact

  • Scope contacts:read

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.

Parameters

GET /v1/contacts/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/contacts/{id}: Responses
StatusDescriptionBody
200The contact

Headers UPPU-Service-Stop-At

Contact
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/contacts/{id}/consents

List the consent records of a contact

  • Scope contacts:read

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.

Parameters

GET /v1/contacts/{id}/consents: Parameters
NameInTypeDescription
idrequiredpathId
limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc
created_afterquerystring (date-time)
created_beforequerystring (date-time)

Responses

GET /v1/contacts/{id}/consents: Responses
StatusDescriptionBody
200A page of consent records

Headers UPPU-Service-Stop-At

ConsentList
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Consents

Record a consent or a withdrawal on its own, without a template send (WhatsApp).

POST/v1/consents

Record a consent

  • Scope consents:write

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.

Parameters

POST /v1/consents: Parameters
NameInTypeDescription
Idempotency-Keyheaderstring

Optional; letters, digits, dot, underscore, colon or hyphen, at most 64.

pattern ^[A-Za-z0-9._:-]{1,64}$

Request body

application/json · ConsentRequest

POST /v1/consents: Request body
FieldTypeDescription
channel_idrequiredId
torequiredRecipient
purposerequiredstring
  • marketing
  • utility
staterequiredstring
  • granted
  • withdrawn
source_textrequiredstring

The exact text the person agreed to (or the withdrawal they asked for).

max length 2000

source_refrequiredstring

Your reference to the evidence (no personal data), for example web-form:checkout:7781.

max length 191

collected_atstring (date-time)

When the person gave or withdrew the consent; now if left out, never in the future.

Responses

POST /v1/consents: Responses
StatusDescriptionBody
200A replay of an earlier record with the same Idempotency-Key and consent

Headers UPPU-Service-Stop-At, Idempotent-Replayed

Consent
201The recorded consent

Headers UPPU-Service-Stop-At

Consent
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Conversations

List, read and resolve conversations. On a channel in API mode, hand a conversation over to the team and give it back to your system. Show the contact a «typing» indicator while you prepare an answer (WhatsApp and Messenger; not on Instagram or live chat).

GET/v1/conversations

List conversations

  • Scope messages:read

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.

Parameters

GET /v1/conversations: Parameters
NameInTypeDescription
contact_idqueryId
channel_idqueryId
statusquerystring
  • open
  • resolved
limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc
created_afterquerystring (date-time)
created_beforequerystring (date-time)

Responses

GET /v1/conversations: Responses
StatusDescriptionBody
200A page of conversations

Headers UPPU-Service-Stop-At

ConversationList
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/conversations/{id}

Get a conversation

  • Scope messages:read

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

Parameters

GET /v1/conversations/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/conversations/{id}: Responses
StatusDescriptionBody
200The conversation

Headers UPPU-Service-Stop-At

ConversationWithInboxState
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/conversations/{id}/resolve

Resolve a conversation

  • Scope conversations:write

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.

Parameters

POST /v1/conversations/{id}/resolve: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/conversations/{id}/resolve: Responses
StatusDescriptionBody
200The conversation, resolved

Headers UPPU-Service-Stop-At

ConversationWithInboxState
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/conversations/{id}/handover

Hand a conversation over to the team

  • Scope conversations:write

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.

Parameters

POST /v1/conversations/{id}/handover: Parameters
NameInTypeDescription
idrequiredpathId

Request body

application/json · HandoverRequest

POST /v1/conversations/{id}/handover: Request body
FieldTypeDescription
reasonstring

A short code of your own for why you hand the conversation over, for example customer_request. No personal data.

pattern ^[A-Za-z0-9._:-]+$ · max length 64

notestring

A note for the team (line breaks allowed, no other control characters).

max length 1000

Responses

POST /v1/conversations/{id}/handover: Responses
StatusDescriptionBody
200The conversation, with the team

Headers UPPU-Service-Stop-At

ConversationWithInboxState
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/conversations/{id}/release

Give a conversation back from the team

  • Scope conversations:write

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.

Parameters

POST /v1/conversations/{id}/release: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/conversations/{id}/release: Responses
StatusDescriptionBody
200The conversation, with the automation

Headers UPPU-Service-Stop-At

ConversationWithInboxState
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/conversations/{id}/typing

Show a typing indicator to the contact

  • Scope messages:send

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.

Parameters

POST /v1/conversations/{id}/typing: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/conversations/{id}/typing: Responses
StatusDescriptionBody
202The typing indicator is queued

Headers UPPU-Service-Stop-At

TypingIndicator
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Templates

The WhatsApp message templates of your channels, with what you need to send them; create and delete templates.

GET/v1/templates

List the WhatsApp templates of the key's channels

  • Scope templates:read

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.

Parameters

GET /v1/templates: Parameters
NameInTypeDescription
channel_idqueryId
statusquerystring

Meta's status, for example APPROVED.

namequerystring
languagequerystring

For example tr or en_US.

limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc
created_afterquerystring (date-time)
created_beforequerystring (date-time)

Responses

GET /v1/templates: Responses
StatusDescriptionBody
200A page of templates

Headers UPPU-Service-Stop-At

TemplateList
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/templates

Create a WhatsApp template

  • Scope templates:write

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 one of the 111 template language codes Meta supports, as Meta writes them (tr, en, ar, en_US, pt_BR, prs_AF ...; the enum lists them); 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.

Parameters

POST /v1/templates: Parameters
NameInTypeDescription
Idempotency-Keyheaderstring

Optional; letters, digits, dot, underscore, colon or hyphen, at most 64. Kept only by an accepted create; after 503 provider_unavailable with details.reason unconfirmed a retry with the same key and template looks at Meta again (for 24 hours).

pattern ^[A-Za-z0-9._:-]{1,64}$

Request body

application/json · TemplateCreateRequest

POST /v1/templates: Request body
FieldTypeDescription
channel_idrequiredstring

A WhatsApp channel of the key; the template belongs to the channel's WhatsApp Business account.

pattern ^[0-9a-hjkmnp-tv-z]{26}$

namerequiredstring

1 to 512 lowercase letters, digits and underscores, for example order_update.

pattern ^[a-z0-9_]{1,512}$

languagerequiredstring

One of the template languages Meta supports, in Meta's code (added within v1: before, only tr and en). Templates created in Meta's own tools in other languages are listed and sent all the same.

  • af
  • sq
  • ar
  • ar_EG
  • ar_AE
  • ar_LB
  • ar_MA
  • ar_QA
  • az
  • be_BY
  • bn
  • bn_IN
  • bg
  • ca
  • zh_CN
  • zh_HK
  • zh_TW
  • hr
  • cs
  • da
  • prs_AF
  • nl
  • nl_BE
  • en
  • en_GB
  • en_US
  • en_AE
  • en_AU
  • en_CA
  • en_GH
  • en_IE
  • en_IN
  • en_JM
  • en_MY
  • en_NZ
  • en_QA
  • en_SG
  • en_UG
  • en_ZA
  • et
  • fil
  • fi
  • fr
  • fr_BE
  • fr_CA
  • fr_CH
  • fr_CI
  • fr_MA
  • ka
  • de
  • de_AT
  • de_CH
  • el
  • gu
  • ha
  • he
  • hi
  • hu
  • id
  • ga
  • it
  • ja
  • kn
  • kk
  • rw_RW
  • ko
  • ky_KG
  • lo
  • lv
  • lt
  • mk
  • ms
  • ml
  • mr
  • nb
  • ps_AF
  • fa
  • pl
  • pt_BR
  • pt_PT
  • pa
  • ro
  • ru
  • sr
  • si_LK
  • sk
  • sl
  • es
  • es_AR
  • es_CL
  • es_CO
  • es_CR
  • es_DO
  • es_EC
  • es_HN
  • es_MX
  • es_PA
  • es_PE
  • es_ES
  • es_UY
  • sw
  • sv
  • ta
  • te
  • th
  • tr
  • uk
  • ur
  • uz
  • vi
  • zu
categoryrequiredstring

Upper or lower case. Authentication templates cannot be created.

  • UTILITY
  • MARKETING
  • utility
  • marketing
headerTemplateCreateHeader
bodyrequiredTemplateCreateBody
footerobject

One line of at most 60 characters, without variables.

buttonsarray of TemplateCreateButton

At most 3 quick replies, 2 URL buttons and 1 phone number button; the quick replies next to each other, before or after the other buttons. Button texts are one line of at most 25 characters without variables and differ from each other.

Responses

POST /v1/templates: Responses
StatusDescriptionBody
200A replay of an earlier request with the same Idempotency-Key and template, also when the earlier request got 503 unconfirmed and created the template

Headers UPPU-Service-Stop-At, Idempotent-Replayed

Template
201The new template, sent to Meta for review

Headers UPPU-Service-Stop-At

Template
400 401 403 404 409 413 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/templates/{id}

Get a template

  • Scope templates:read

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

Parameters

GET /v1/templates/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/templates/{id}: Responses
StatusDescriptionBody
200The template

Headers UPPU-Service-Stop-At

Template
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

DELETE/v1/templates/{id}

Delete a WhatsApp template in one language

  • Scope templates:write

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.

Parameters

DELETE /v1/templates/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

DELETE /v1/templates/{id}: Responses
StatusDescriptionBody
200The template is deleted in this language

Headers UPPU-Service-Stop-At

DeletedTemplate
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Reports

The figures of the panel's reports, for a workspace whose plan includes the messaging panel. Counts only: no contact, conversation or message.

GET/v1/reports/summary

Get the report of a period

  • Scope reports:read

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, response 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, response targets, 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.

Parameters

GET /v1/reports/summary: Parameters
NameInTypeDescription
daysquerystring

The last 7, 30 or 90 finished days (30 when neither days nor from and to is given). Not together with from and to.

  • 7
  • 30
  • 90
fromquerystring

The first day (YYYY-MM-DD, the company's time zone); needs to. The period is at most 90 days.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

toquerystring

The last day (YYYY-MM-DD); needs from. A day after the last counted day is moved back to it.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

channel_idqueryId

Only this channel. At most one of channel_id, member_id and group_id.

member_idqueryId

Only this agent, a current member of the company (the id in breakdowns.members); not with a key bound to one channel.

group_idqueryId

Only this group (the id in breakdowns.groups); not with a key bound to one channel.

Responses

GET /v1/reports/summary: Responses
StatusDescriptionBody
200The report of the period and scope

Headers UPPU-Service-Stop-At

ReportSummary
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/reports/daily

List the days of a report

  • Scope reports:read

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.

Parameters

GET /v1/reports/daily: Parameters
NameInTypeDescription
daysquerystring

The last 7, 30 or 90 finished days (30 when neither days nor from and to is given). Not together with from and to.

  • 7
  • 30
  • 90
fromquerystring

The first day (YYYY-MM-DD, the company's time zone); needs to. The period is at most 90 days.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

toquerystring

The last day (YYYY-MM-DD); needs from. A day after the last counted day is moved back to it.

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

channel_idqueryId

Only this channel. At most one of channel_id, member_id and group_id.

member_idqueryId

Only this agent, a current member of the company (the id in breakdowns.members); not with a key bound to one channel.

group_idqueryId

Only this group (the id in breakdowns.groups); not with a key bound to one channel.

limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc

Responses

GET /v1/reports/daily: Responses
StatusDescriptionBody
200A page of days

Headers UPPU-Service-Stop-At

ReportDayList
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Events

The pull fallback for webhooks: the same events and bodies for 7 days.

GET/v1/events

Pull the events of the last 7 days (webhook fallback)

  • Scope events:read

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, template.category_changed, template.category_change_closed, account.service_stop_scheduled and account.service_resumed) need an all-channels key. Test events are never listed.

Parameters

GET /v1/events: Parameters
NameInTypeDescription
afterqueryId

The id of the last event already processed: the next_cursor of the previous page, or the last webhook-id you handled (of any type, also one outside types). Prefer a cursor from this endpoint; events recorded in the same seconds as a webhook-id may sort before it.

typesquerystring

Comma-separated event types, for example message.received,message.status.

limitqueryinteger

min 1 · max 100 · default 25

Responses

GET /v1/events: Responses
StatusDescriptionBody
200Events, oldest first

Headers UPPU-Service-Stop-At

EventList
400 401 403 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Media

Put a file on UPPU before you send it, read a file's metadata and download inbound files, also through a short-lived signed link that needs no key.

POST/v1/media

Upload a media file to send later

  • Scope media:write

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 gets 422 content_not_supported_on_channel while UPPU has not switched on sending media on Instagram; 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. 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. Files that break these rules are accepted; WhatsApp can refuse such a file when the message is sent (status failed with error.code 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 (once UPPU switches sending media 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.

Parameters

POST /v1/media: Parameters
NameInTypeDescription
Idempotency-Keyheaderstring

Optional; letters, digits, dot, underscore, colon or hyphen, at most 64.

pattern ^[A-Za-z0-9._:-]{1,64}$

Request body

multipart/form-data

POST /v1/media: Request body
FieldTypeDescription
channel_idrequiredId
filerequiredstring (binary)
kindstring

Optional, added within v1: sticker uploads the file as a sticker (WhatsApp and Telegram). It is part of the request for the Idempotency-Key.

  • sticker

Responses

POST /v1/media: Responses
StatusDescriptionBody
200A replay of an earlier upload with the same Idempotency-Key and file

Headers UPPU-Service-Stop-At, Idempotent-Replayed

Media
201The stored file; state ready

Headers UPPU-Service-Stop-At

Media
422An error (see /docs/errors). validation_failed lists the fields: for the file, codes sticker_unreadable, sticker_animated_not_allowed and sticker_dimensions (stickers).

Headers UPPU-Service-Stop-At

ErrorEnvelope
400 401 403 404 409 413 415 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/media/{id}

Get a media file's metadata

  • Scope media:read

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 the current retry 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 the current 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.

Parameters

GET /v1/media/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/media/{id}: Responses
StatusDescriptionBody
200The media file

Headers UPPU-Service-Stop-At

Media
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/media/{id}/content

Download a media file

  • Scope media:read

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

Parameters

GET /v1/media/{id}/content: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/media/{id}/content: Responses
StatusDescriptionBody
200The file

Headers UPPU-Service-Stop-At, ETag

File bytes
206A range of the fileFile bytes
400 401 403 404 409 410 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

Webhook endpoints

Manage your webhook endpoints through the API, with the rules of the panel's Webhooks page: create, test, verify and activate an endpoint, rotate its signing secret, disable and delete it.

GET/v1/webhook-endpoints

List webhook endpoints

  • Scope webhooks:manage

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.

Parameters

GET /v1/webhook-endpoints: Parameters
NameInTypeDescription
limitqueryinteger

min 1 · max 100 · default 25

cursorquerystring

The next_cursor of the previous page. It carries the sort order, so order may be left out on later pages; an order that contradicts the cursor gets 422 validation_failed (field cursor). Repeat the time filters on every page.

orderquerystring

Sort order. With a cursor and no order, the order of the cursor applies.

default "desc"

  • asc
  • desc
created_afterquerystring (date-time)
created_beforequerystring (date-time)

Responses

GET /v1/webhook-endpoints: Responses
StatusDescriptionBody
200A page of webhook endpoints

Headers UPPU-Service-Stop-At

WebhookEndpointList
400 401 403 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/webhook-endpoints

Create a webhook endpoint

  • Scope webhooks:manage

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.

Parameters

POST /v1/webhook-endpoints: Parameters
NameInTypeDescription
Idempotency-Keyheaderstring

Optional; letters, digits, dot, underscore, colon or hyphen, at most 64.

pattern ^[A-Za-z0-9._:-]{1,64}$

Request body

application/json · WebhookEndpointCreateRequest

POST /v1/webhook-endpoints: Request body
FieldTypeDescription
urlrequiredstring

Your https address on port 443, at most 2048 characters.

max length 2048

eventsarray of string

At least one type; left out, the types that are on by default. template.category_changed, channel.quality_changed and template.category_change_closed (added within v1) only while account protection is on for it; otherwise 422 validation_failed.

  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
channel_idId | null

Only the events of this channel; null for every channel.

orderingstring

default "best_effort"

  • best_effort
  • strict
max_in_flightinteger

min 1 · max 32 · default 8

weekly_testboolean

Send a test event every week (a failure is only a warning).

default false

Responses

POST /v1/webhook-endpoints: Responses
StatusDescriptionBody
200A replay of an earlier request with the same Idempotency-Key and body (secret is null)

Headers UPPU-Service-Stop-At, Idempotent-Replayed

WebhookEndpoint
201The new endpoint with its signing secret (shown only here)

Headers UPPU-Service-Stop-At

WebhookEndpoint
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

GET/v1/webhook-endpoints/{id}

Get a webhook endpoint

  • Scope webhooks:manage

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.

Parameters

GET /v1/webhook-endpoints/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

GET /v1/webhook-endpoints/{id}: Responses
StatusDescriptionBody
200The endpoint

Headers UPPU-Service-Stop-At

WebhookEndpoint
400 401 403 404 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

PATCH/v1/webhook-endpoints/{id}

Change a webhook endpoint

  • Scope webhooks:manage

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.

Parameters

PATCH /v1/webhook-endpoints/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Request body

application/json · WebhookEndpointUpdateRequest

PATCH /v1/webhook-endpoints/{id}: Request body
FieldTypeDescription
urlstring

A new address sends the endpoint back to verification.

max length 2048

eventsarray of string
  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
channel_idId | null
orderingstring
  • best_effort
  • strict
max_in_flightinteger

min 1 · max 32

weekly_testboolean

Responses

PATCH /v1/webhook-endpoints/{id}: Responses
StatusDescriptionBody
200The endpoint as changed

Headers UPPU-Service-Stop-At

WebhookEndpoint
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

DELETE/v1/webhook-endpoints/{id}

Delete a webhook endpoint

  • Scope webhooks:manage

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

Parameters

DELETE /v1/webhook-endpoints/{id}: Parameters
NameInTypeDescription
idrequiredpathId

Responses

DELETE /v1/webhook-endpoints/{id}: Responses
StatusDescriptionBody
200The endpoint is deleted

Headers UPPU-Service-Stop-At

DeletedWebhookEndpoint
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/webhook-endpoints/{id}/secret

Rotate the signing secret

  • Scope webhooks:manage

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.

Parameters

POST /v1/webhook-endpoints/{id}/secret: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/webhook-endpoints/{id}/secret: Responses
StatusDescriptionBody
200The endpoint with its new signing secret (shown only here)

Headers UPPU-Service-Stop-At

WebhookEndpoint
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/webhook-endpoints/{id}/test

Send a test event to a webhook endpoint

  • Scope webhooks:manage

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.

Parameters

POST /v1/webhook-endpoints/{id}/test: Parameters
NameInTypeDescription
idrequiredpathId

Request body

application/json · WebhookEndpointTestRequest

POST /v1/webhook-endpoints/{id}/test: Request body
FieldTypeDescription
typestring

The event type of the sample (webhook.test if left out).

  • message.received
  • message.status
  • message.created
  • contact.identity_changed
  • contact.consent_changed
  • contact.erased
  • template.updated
  • channel.status_changed
  • channel.health_changed
  • conversation.updated (off by default: subscribe the endpoint to it explicitly)
  • contact.reachability_changed
  • contact.updated (off by default: subscribe the endpoint to it explicitly)
  • account.service_stop_scheduled
  • account.service_resumed
  • template.category_changed
  • channel.quality_changed
  • template.category_change_closed
  • webhook.test

Responses

POST /v1/webhook-endpoints/{id}/test: Responses
StatusDescriptionBody
200The result of the test event

Headers UPPU-Service-Stop-At

WebhookEndpointCheck
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/webhook-endpoints/{id}/probe

Send the wrong-signature probe

  • Scope webhooks:manage

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

Parameters

POST /v1/webhook-endpoints/{id}/probe: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/webhook-endpoints/{id}/probe: Responses
StatusDescriptionBody
200The result of the probe

Headers UPPU-Service-Stop-At

WebhookEndpointCheck
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/webhook-endpoints/{id}/activate

Activate a webhook endpoint

  • Scope webhooks:manage

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

Parameters

POST /v1/webhook-endpoints/{id}/activate: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/webhook-endpoints/{id}/activate: Responses
StatusDescriptionBody
200The endpoint

Headers UPPU-Service-Stop-At

WebhookEndpoint
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

POST/v1/webhook-endpoints/{id}/disable

Disable a webhook endpoint

  • Scope webhooks:manage

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

Parameters

POST /v1/webhook-endpoints/{id}/disable: Parameters
NameInTypeDescription
idrequiredpathId

Responses

POST /v1/webhook-endpoints/{id}/disable: Responses
StatusDescriptionBody
200The endpoint

Headers UPPU-Service-Stop-At

WebhookEndpoint
400 401 403 404 409 422 429 500 503An error in the standard envelope. Error codesErrorEnvelope

OpenAPI document

This reference's source, served without a key.

GET/v1/openapi.json

This document

  • Authentication none

Responses

GET /v1/openapi.json: Responses
StatusDescriptionBody
200The OpenAPI document of v1application/json

Webhooks

UPPU posts events to your HTTPS endpoint. Setup, signature verification with a test vector and delivery rules are in the webhooks guide.

POSTYour endpoint

An event UPPU sends to your webhook endpoint

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 attempts in total, the first included, 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, language), reason and occurred_at; the envelope's channel is null. One change sends one event; 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. template.category_changed, channel.quality_changed and template.category_change_closed (added within v1; subscribe to them explicitly, new endpoints leave them off, and they can be chosen only while UPPU's account protection is on for the company) are written whether or not an endpoint subscribes, so GET /events lists them. template.category_changed carries TemplateCategoryChangeEvent: the template as template.updated carries it and the category change UPPU recorded (kind changed, announced or created_as). A completed change also sends template.updated with field category, an announcement and a creation do not; a change back is a change of its own. Its envelope's channel is null and it is ordered per template. template.category_change_closed carries TemplateCategoryChangeClosedEvent when UPPU stops following a change, once per change: state appealed or dismissed (a team member marked it), reverted (the template's category went back), expired (60 days passed; for an announcement, 60 days after the announced date, or after UPPU saw it when Meta gave no date), gone (the template was deleted) or superseded (Meta completed the announced change; sent just before that change's template.category_changed). Its data is the template, the category change with its current values, the state and closed_at. UPPU's protection round closes reverted, expired and gone changes, so these arrive up to about 5 minutes after UPPU sees the cause. Its envelope's channel is null and it is ordered per template. channel.quality_changed carries ChannelQualityChange: a WhatsApp number's quality rating (field quality) or messaging limit (field messaging_limit) going down or up as UPPU's protection round observes it. UPPU's channel checks read the values from Meta every 15 minutes (sooner when Meta reports a change on the account) and the round compares them every 5 minutes, so the event can arrive up to about half an hour after Meta's change, or later while UPPU cannot read Meta; the first reading of a number and an unrated value send nothing. It is ordered per channel. Accept unknown kinds, states, fields and values.

Headers

Webhook request headers
NameTypeDescription
webhook-idrequiredId

The event id; the same across retries, resends and endpoints.

webhook-timestamprequiredstring

Unix seconds, new on every attempt.

webhook-signaturerequiredstring

One or two values "v1,<base64>" separated by a space.

Uppu-Event-Typerequiredstring
Uppu-Delivery-IdrequiredId

The delivery to this endpoint (a resend keeps it).

Uppu-Attemptrequiredstring

Request body

application/json · Event

Your response

  • 2XX Received; UPPU does not send this event to the endpoint again.

Schemas

The objects used by the endpoints and the webhook event are on two pages. Every type above links to its schema.

  • Message schemas (45) Messages, the content you send and receive, recipients, templates, media and delivery errors.
  • Schemas (42) Channels, contacts, consents, conversations, events, webhook endpoints, reports, errors and the common types.

Generated from openapi.json (commit a1fec8942, 19 November 2026) · Live OpenAPI document