Developers · API reference
Message schemas
Messages, their content, templates and media in the UPPU customer API v1, generated from the copy of the OpenAPI document pinned on this site. The endpoints are on the API reference; the other objects are on the schemas page.
- API version
v1 - OpenAPI
3.1.0 - Generated from
a1fec8942· 19 November 2026
Schemas
Objects used by the endpoints and the webhook event. Fields marked “required” are always present; nullable fields are present with null.
TemplateCategoryChangeMessageMessageRetryMessageAuthorMessageContentMessageContextMessageTemplateDeliveryErrorProviderErrorMessageListSendMessageRequestRecipientOutboundContentTextContentInteractiveContentInteractiveOptionReactionContentLocationContentMediaContentMediaSourceStickerContentContactsContentContactCardMediaTemplateContentMediaHeaderHeaderFileTemplateButtonValueTemplateValuesInlineConsentReadReceiptTypingIndicatorTemplateListTemplateTemplateComponentTemplateParameterSchemaTemplateButtonFieldTemplateVariableTemplateCreateRequestTemplateCreateHeaderTemplateCreateMediaHeaderTemplateCreateBodyTemplateCreateButtonDeletedTemplateMediaLink
TemplateCategoryChange
A category change of a WhatsApp template that UPPU recorded (added within v1, with account protection). kind changed: Meta moved the template from previous_category to new_category (a change back is a change of its own). announced: Meta announced that it will move the template to new_category; previous_category is the template's category when UPPU saw the notice, and scheduled_at the date Meta gave in its notice (null when Meta gave none, as in its template list). A later notice from Meta for the same change can fill in or move scheduled_at without a new event; the template's category_change shows the current value. created_as: a new template was approved by Meta in new_category instead of the submitted previous_category. changed_at is the earliest moment UPPU can know for the change: when UPPU received or found Meta's notice, when the template was created, or, for a completed change UPPU found in its periodic read of Meta's template list, the time of the read before it, which can be hours before the event. reviewable is true only for what Meta accepts a review of (a completed change from UTILITY to MARKETING, or a template submitted in another category and approved as MARKETING); appeal_until is then changed_at plus 60 days, otherwise null. A review is requested in WhatsApp Manager, not through the API. Accept unknown kinds and categories.
| Field | Type | Description |
|---|---|---|
idrequired | Id | |
kindrequired | string |
|
previous_categoryrequired | string | null | Meta's category before the change (UTILITY, MARKETING, AUTHENTICATION). |
new_categoryrequired | string | Meta's category after the change. |
changed_atrequired | Timestamp | |
scheduled_atrequired | NullableTimestamp | |
appeal_untilrequired | NullableTimestamp | |
reviewablerequired | boolean |
Message
A message of either direction. The API and the webhooks never mask text: the company's own system gets the text as written. When the platform has switched on the company's special-category data protection, a recognized Turkish national ID number in a message older than the short retention (90 days by default, at least 30) is masked in storage for good (***46). The mask covers preview, the text fields of content (template variables included) and the names of the message's files (media.filename and attachments[].media.filename here, filename in GET /media/{id}); ids and context stay. One exception: a file uploaded with POST /media (or in the inbox) and sent in an outbound message keeps its own row, which is not tied to the message, because the upload can be reused in later sends. The short retention does not mask that row: media.filename here and filename in GET /media/{id} keep the uploaded name until the row is deleted on its own schedule (the file 90 days after its last use, the row 30 days later). The content's own filename is masked. A closed company's messages are masked the same way until its data is deleted.
| Field | Type | Description |
|---|---|---|
objectrequired | "message" | |
idrequired | Id | |
channel_idrequired | Id | |
channel_typerequired | string | |
conversation_idrequired | Id | |
contact_idrequired | Id | |
directionrequired | string |
|
authorrequired | MessageAuthor | |
contentrequired | MessageContent | |
contextrequired | MessageContext | null | |
templaterequired | MessageTemplate | null | |
previewrequired | string | |
statusrequired | string | Outbound: queued, accepted, sent, delivered, read, failed, unknown, or (added within v1) expired: the ttl ran out before UPPU handed the message to the provider, nothing was sent, error.code ttl_expired. Inbound: received. Accept values you do not know.
|
status_changed_atrequired | NullableTimestamp | |
errorrequired | DeliveryError | null | |
client_referencerequired | string | null | max length |
provider_message_idrequired | string | null | |
sent_atrequired | NullableTimestamp | Inbound: the provider's timestamp of the message (Meta's; on Telegram its date, in seconds; the receive time when the provider sent none). Outbound: when the provider accepted it (Meta accepted it, Telegram stored it; web chat: when it was written). |
received_atrequired | NullableTimestamp | Inbound: when the message reached UPPU; null outbound. On channels with a reply window (WhatsApp, Messenger, Instagram) the window counts from the earlier of sent_at and received_at: a received_at far after sent_at marks a message Meta delivered late, whose window may already be closed. Telegram and web chat have no reply window. |
created_atrequired | Timestamp | |
retry | MessageRetry | Added within v1, available once UPPU switches account protection on for your company; until then the key is absent. Only in the answers of |
MessageRetry
Added within v1: UPPU's retries after Meta's per-user marketing limit (error 131049) for a send that asked for retry.per_user_limit. The first message and every resend carry the same object, read when UPPU answers; it is read-only. Accept values you do not know in state, held_reason and stop_reason.
| Field | Type | Description |
|---|---|---|
staterequired | string | watching: no 131049 yet. waiting: the next attempt is due at next_attempt_at (held_reason set: UPPU holds the round). sending: an attempt is under way. sent: a resend was queued and its outcome is awaited. delivered: the latest message was delivered or read. sent_unconfirmed: no outcome of the latest resend within two days. exhausted: the 7-day window or the attempt limit ran out. stopped: UPPU stopped retrying (stop_reason). The last four are final (final_at). Accept values you do not know.
|
attemptsrequired | integer | Resends started so far. A round that UPPU held (held_reason) gives its number back and does not count. min |
max_attemptsrequired | integer | The most resends UPPU makes for one send. min |
first_failed_atrequired | NullableTimestamp | When Meta first failed the send with 131049; null before that. |
last_failed_atrequired | NullableTimestamp | The latest 131049 of the chain; null before the first. |
window_ends_atrequired | NullableTimestamp | UPPU resends only before this time (7 days after the first 131049); null before the first. |
next_attempt_atrequired | NullableTimestamp | Only while state is waiting: when the next attempt is due (at least 24 hours after the latest 131049, or the end of a hold). Null in every other state. |
held_reasonrequired | string | null | Why UPPU holds a waiting round, then tries again: channel_backlog (the channel's queue is full), iys_unavailable (İYS could not be asked), iys_credentials (the company's İYS credentials do not work), channel_unavailable or channel_paused (the channel cannot send now), tenant_read_only or service_stopped (the company cannot send now) or outage (UPPU suspects a Meta outage). Null otherwise. Accept values you do not know.
|
stop_reasonrequired | string | null | Why UPPU stopped (state stopped); null otherwise. company_off: your company switched these retries off or was closed. key_unusable: the API key of the send can no longer send for you (stop_code says why, for example invalid_api_key or insufficient_scope). rejected: the attempt was refused as a new send of the key would be (stop_code is its error code, for example consent_withdrawn or template_not_approved). other_error: Meta failed the latest message with another error (read error of latest_message_id). expired: the latest message expired before it was sent. message_gone: the latest message no longer exists. Accept values you do not know.
|
stop_coderequired | string | null | The API error code of the refusal that stopped the retries (stop_reason rejected or key_unusable); null otherwise. |
original_message_idrequired | Id | null | The first message of the send; null once it was deleted. |
latest_message_idrequired | Id | null | The newest message of the chain (the first message until a resend); null once it was deleted. |
final_atrequired | NullableTimestamp | When the retries reached a final state; null before that. |
MessageAuthor
| Field | Type | Description |
|---|---|---|
typerequired | string | contact, agent (the team), system (UPPU), api (your API key) or bot (UPPU Bot; label is the bot's display name).
|
labelrequired | string | null | |
api_key_prefixrequired | string | null |
MessageContent
{"type": T, T: {...}}. Types: text, image, video, audio, document, sticker, location, contacts, interactive, interactive_reply, template, reaction, unsupported, system. Media of both directions carries media: {id, mime_type, size, sha256, filename, state, failure_reason}: id is UPPU's media id (GET /media/{id}/content), size and sha256 stay null until the file is stored (state pending -> ready). A media object whose id is null belongs to an old inbound message stored before UPPU kept its files (on WhatsApp, Messenger and Instagram, before their media support): it stays pending, never becomes ready and cannot be downloaded, so do not poll for it. Messenger and Instagram (added within v1): a message's type is the type of its first media attachment, whatever attachment comes before it (a link preview, a location, a template, a shared post, a reel or a story mention followed by a photo is an image message). A message with several media attachments carries attachments: [{type, media}] next to media, every media attachment (image, video, audio, document, sticker) in Meta's order (the first is the same file as media; the key is absent when there is at most one media attachment). Other attachment types (location, link previews, templates, shared posts, reels, story mentions) are not listed and have no file; the preview text counts every attachment. A message without a media attachment takes the type of its first attachment: a shared post or reel (unsupported) carries the preview's file as unsupported.media when Meta gave one; an Instagram story mention has no file (Meta does not allow storing story content). On Messenger and Instagram a caption reaches the person as a separate text message after the file. Meta's attachment links are never exposed. Telegram (added within v1): a message carries at most one file (every album item is its own message; an animated sticker's file is its thumbnail), which UPPU downloads; Telegram's file ids are never exposed. Web chat (added within v1): a visitor's message carries at most one file (image, video, audio or document, with an optional caption) with the same media object; it is stored as it arrives. UPPU Bot on web chat (added within v1): a question with options is interactive (quick_replies whose ids are the bot's option ids) and the visitor's tap is interactive_reply (kind quick_reply, the option's id and title; context.message_id is the question). Stickers and contact cards you send (added within v1) read back with the shapes of received ones: sticker with the upload's media object and animated, contacts with the cards (phones carry bsuid null). A template or buttons message sent with a file header (added within v1) carries header: {type, T: {media, filename?}} in template or interactive, with the upload's media object; the template's variables and button values are not echoed. Link buttons (added within v1): a sent interactive of type cta_url reads back as sent. Telegram phone requests (added within v1): a sent interactive of type request_phone reads back as sent. The person's own card arrives as contacts (one card, one phone); when the card is not a reply and the latest reply keyboard sent to the person in the last 24 hours is a request_phone (a later quick_replies message takes its place), context.message_id is that request. The number also becomes the contact's phone identity on the channel. E-mail (added within v1): a received e-mail is text: body is its plain text (an HTML e-mail is turned into text; the quoted earlier messages of a reply are cut, the full e-mail is not kept in the message), email is {subject, from: {address, name}, reply_to, authenticated, in_reply_to, references, trimmed, truncated, html, attachment_count, attachments_omitted} (authenticated: UPPU's mail server found a valid DKIM signature of the domain of the person's address, the reply_to when given, else from; false means the address may be forged; trimmed: a quote was cut; truncated: the text was longer than the message keeps; html: the text came from HTML; attachments_omitted: attachments over UPPU's limit that were not kept) and attachments: [{type, media}] lists its files in order (absent when it has none). provider_message_id is the e-mail's Message-ID without angle brackets (UPPU's own Message-ID on an e-mail you sent).
| Field | Type | Description |
|---|---|---|
typerequired | string |
Other keys may appear: read the ones you know and ignore the rest.
MessageContext
| Field | Type | Description |
|---|---|---|
message_idrequired | string | null | |
provider_message_idrequired | string | null | |
forwardedrequired | boolean | |
frequently_forwardedrequired | boolean | |
referralrequired | object | null | |
story | object | Present only on a reply to an Instagram story: the story's id. UPPU does not keep the story's file or its address (Meta does not allow storing story content; a story expires after 24 hours). |
story.idrequired | string | null | |
start_parameter | string | Telegram only, present only when the person opened the bot with a deep link (https://t.me/<bot>?start=<parameter>, delivered as "/start <parameter>"): the parameter, 1-64 of A-Z a-z 0-9 _ -. The message itself stays a text "/start <parameter>". |
media_group_id | string | Telegram only, present only on an item of an album: the album's id. Every item of an album is its own message with its own media; the caption sits on one of them. |
MessageTemplate
| Field | Type | Description |
|---|---|---|
idrequired | string | null | |
namerequired | string | null | |
languagerequired | string | null | |
categoryrequired | string | null |
DeliveryError
| Field | Type | Description |
|---|---|---|
coderequired | string |
|
messagerequired | string | |
retryablerequired | boolean | |
provider_errorrequired | ProviderError | null |
ProviderError
| Field | Type | Description |
|---|---|---|
providerrequired | string | meta, or telegram (added within v1; code is Telegram's error_code, title its description), or email (added within v1; code is the SMTP reply code of UPPU's mail server, title its masked reply).
|
coderequired | integer | |
subcoderequired | integer | null | |
titlerequired | string | null | |
detailsrequired | string | null |
MessageList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of Message | |
next_cursorrequired | string | null |
SendMessageRequest
| Field | Type | Description |
|---|---|---|
channel_idrequired | Id | |
torequired | Recipient | |
context | object | 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). |
context.message_idrequired | Id | |
contentrequired | OutboundContent | |
client_reference | string | Your opaque reference (no personal data); echoed in GET and in every message.status event. min length |
consent | InlineConsent | |
ttl | integer | 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 |
retry | object | 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, |
retry.per_user_limitrequired | boolean | Retry after Meta's per-user marketing limit (error 131049). |
Recipient
Exactly one of contact_id, phone (E.164 with a plus sign, WhatsApp only) or an identity that already exists on the channel (telegram: the person's Telegram user id as a decimal string; the person must have written to the bot first; email, added within v1: the address the person wrote from, case-insensitive).
One of:
| Field | Type | Description |
|---|---|---|
contact_idrequired | Id |
| Field | Type | Description |
|---|---|---|
phonerequired | string | pattern |
| Field | Type | Description |
|---|---|---|
identityrequired | object | |
identity.typerequired | string |
|
identity.valuerequired | string | max length |
OutboundContent
{"type": T, T: {...}}. Web chat channels take text and, added within v1, media by media_id only (see MediaContent). Limits come from the channel's capabilities (GET /channels; ChannelCapabilities.limits says how they relate to the providers' own limits). Media (image, video, audio, document) takes exactly one of media_id (POST /media) or an https link that UPPU downloads before sending. Added within v1: sticker (StickerContent) and contacts (ContactsContent) on WhatsApp and Telegram; other channels get 422 content_not_supported_on_channel. Telegram takes text (1-4096 UTF-16 units, plain text), interactive buttons and quick_replies (no header, footer or list), reaction (an emoji of capabilities.reaction_emojis; an empty string removes it), location (name and address both or neither: a venue) and, added within v1, media (image, video, audio, document; see MediaContent), a static sticker and one contact card with one phone. Added within v1: interactive cta_url (a link button) on WhatsApp and Messenger and interactive request_phone (the person shares their own phone number) on Telegram; see InteractiveContent.
One of:
TextContent
| Field | Type | Description |
|---|---|---|
typerequired | "text" | |
textrequired | object | |
text.bodyrequired | string | min length |
text.preview_url | boolean |
InteractiveContent
| Field | Type | Description |
|---|---|---|
typerequired | "interactive" | |
interactiverequired | object | body is required on every type. |
interactive.typerequired | string | buttons and list on WhatsApp; buttons and quick_replies on Messenger and Telegram; quick_replies on Instagram (see the channel's capabilities.interactive_types). quick_replies has the shape of buttons. On Telegram buttons are an inline keyboard (a tap arrives as interactive_reply, kind button) and quick_replies a one-time reply keyboard whose titles must be unique (a tap arrives as interactive_reply, kind quick_reply). Added within v1: cta_url, one button that opens an https address (WhatsApp and Messenger; see cta_url), and request_phone, a Telegram one-time keyboard with one button that sends the person's own phone number (Telegram only; see request_phone). A type the channel does not list gets 422 content_not_supported_on_channel (details.field content.interactive.type).
|
interactive.header | object | MediaHeader | A text header, or (added within v1) on a WhatsApp buttons or cta_url message a file header: an image, a video or a document given by the media_id of an upload of the same channel ( |
interactive.body | object | |
interactive.body.textrequired | string | |
interactive.footer | object | |
interactive.footer.textrequired | string | |
interactive.buttons | array of InteractiveOption | Buttons and quick replies messages only. |
interactive.button | string | List message only; the label of the list button. |
interactive.sections | array of object | List message only. |
interactive.sections[].title | string | |
interactive.sections[].rowsrequired | array of InteractiveOption | |
interactive.cta_url | object | cta_url message only (added within v1): one button that opens an https address in the person's browser. display_text is the button's text (capabilities.limits.cta_display_text: 20 on WhatsApp and Messenger). url is an https address made of the characters of a web address (letters, digits, -._~:/?#[]@!$&'()*+,;= and percent-encoding: encode a space as %20 and Turkish letters too), at most capabilities.limits.cta_url characters (the providers give no limit; this is UPPU's). UPPU sends the address as written: no shortener, no tracking. The body is required (WhatsApp interactive_body, Messenger button_text); WhatsApp also takes a header (text or file) and a footer, Messenger neither. Instagram, Telegram and web chat do not send it (422 content_not_supported_on_channel). A tap opens the address and sends nothing back. |
interactive.cta_url.display_textrequired | string | |
interactive.cta_url.urlrequired | string | |
interactive.request_phone | object | request_phone message only (added within v1; Telegram): a one-time reply keyboard with one button whose tap sends the person's own phone number as a contact card ("the user's phone number will be sent as a contact when the button is pressed"). display_text is the button's text (at most capabilities.limits.quick_reply_title characters). The body is required; say in it why you ask for the number (your privacy notice applies). No header, footer or buttons. The person's card comes back on message.received as content type contacts, with context.message_id of this message while it is the latest reply keyboard sent to the person in the last 24 hours (a later quick_replies message takes its place), and the number becomes a phone identity of the contact on this channel (only the person's own card, never someone else's). The next text, location, media or contact message removes the keyboard. |
interactive.request_phone.display_textrequired | string |
InteractiveOption
| Field | Type | Description |
|---|---|---|
idrequired | string | |
titlerequired | string | |
description | string | List rows only. |
ReactionContent
| Field | Type | Description |
|---|---|---|
typerequired | "reaction" | |
reactionrequired | object | |
reaction.message_idrequired | Id | |
reaction.emojirequired | string | An empty string asks the channel to remove the reaction. |
LocationContent
| Field | Type | Description |
|---|---|---|
typerequired | "location" | |
locationrequired | object | |
location.latituderequired | number | min |
location.longituderequired | number | min |
location.name | string | |
location.address | string |
MediaContent
An image, video, audio or document: {"type": "document", "document": {"media_id": "…", "filename": "…", "caption": "…"}}. Give exactly one of media_id (an upload of the same channel, within reusable_until) or link (https on port 443, public addresses only, no redirects, at most the type's size, 15 seconds; a failure ends as failed with media_fetch_failed). Audio has no caption; only a document has a filename. The type's MIME types and sizes are those of POST /media for the channel's type. WhatsApp, Messenger, Instagram and Telegram channels send media (see capabilities.content_types; Instagram only once UPPU switches sending media on there, otherwise 422 content_not_supported_on_channel); Instagram has no document (422 content_not_supported_on_channel). Web chat (added within v1) takes media_id only: a link is 422 content_not_supported_on_channel (details.field content.{type}.link); the message is sent at once and the visitor opens the file in the chat widget through a short-lived link. On Messenger and Instagram the caption is sent as a separate text message right after the file (it has the channel's text limit: Messenger 2000 characters, Instagram 1000 bytes), and Meta shows a document under the name it was uploaded with (the upload's file name, or filename with a link); one message, one status. If the file was accepted but the caption could not be sent, the message stays accepted. On Telegram (added within v1) the file is uploaded inside the send call and the caption is Telegram's own (at most 1024 UTF-16 units, 422 validation_failed beyond); an audio/ogg file goes out as a voice note. Later sends of the same upload reuse Telegram's file id (a document sent under another filename is uploaded again). A file Telegram refuses ends as failed with media_rejected.
| Field | Type | Description |
|---|---|---|
typerequired | string |
|
image | MediaSource | |
video | MediaSource | |
audio | MediaSource | |
document | MediaSource |
MediaSource
| Field | Type | Description |
|---|---|---|
media_id | Id | |
link | string | pattern |
caption | string | |
filename | string | max length |
StickerContent
Added within v1, on WhatsApp and Telegram: {"type": "sticker", "sticker": {"media_id": "…"}}. media_id is an upload of the same channel within reusable_until, made with POST /media and kind sticker (on Telegram also a WebP uploaded without kind): a WebP of exactly 512×512 pixels, static up to 100 KB or animated up to 500 KB; Telegram sends static stickers only. A link is 422 validation_failed (code not_supported); a sticker has no caption. A file that breaks the rules gets 413 media_too_large or 422 validation_failed for content.sticker.media_id (sticker_dimensions, sticker_unreadable, sticker_animated_not_allowed, mime_not_allowed), checked in the order POST /media gives: the 413's details carry kind sticker, the max_bytes of the file's own kind (static or animated, read from the header) and animated. The message reads back as content sticker with the media object and animated.
| Field | Type | Description |
|---|---|---|
typerequired | "sticker" | |
stickerrequired | object | |
sticker.media_idrequired | Id |
ContactsContent
Added within v1, on WhatsApp and Telegram: {"type": "contacts", "contacts": {"contacts": [card, …]}}, the shape a received contact card has. At least one card; at most capabilities.limits.contact_cards cards (Telegram: one). Every card needs name.formatted_name and at least one phone number or e-mail address (Telegram: exactly one phone; e-mail addresses and org are 422 content_not_supported_on_channel). A phone number has 3 to 20 digits and may carry a plus sign, spaces, hyphens, dots and brackets; an e-mail address must be valid. Each text field has at most capabilities.limits.contact_field characters. On WhatsApp a name with formatted_name only is sent with first_name set to it. A contact card is personal data of the person it describes: it is kept, exported and erased with the message.
| Field | Type | Description |
|---|---|---|
typerequired | "contacts" | |
contactsrequired | object | |
contacts.contactsrequired | array of ContactCard |
ContactCard
| Field | Type | Description |
|---|---|---|
namerequired | object | |
name.formatted_namerequired | string | The name as it is shown. min length |
name.first_name | string | |
name.last_name | string | |
name.middle_name | string | |
name.prefix | string | |
name.suffix | string | |
phones | array of object | |
phones[].phonerequired | string | |
phones[].type | string | For example CELL, MAIN, IPHONE, HOME or WORK. |
emails | array of object | |
emails[].emailrequired | string | |
emails[].type | string | For example HOME or WORK. |
org | object | |
org.company | string | |
org.department | string | |
org.title | string |
Media
| Field | Type | Description |
|---|---|---|
objectrequired | "media" | |
idrequired | Id | |
channel_idrequired | string | null | |
directionrequired | string |
|
kindrequired | string |
|
mime_typerequired | string | null | |
sizerequired | integer | null | Bytes; null until the file is stored. |
sha256required | string | null | The hex SHA-256 of the stored file; null until it is stored. |
filenamerequired | string | null | |
staterequired | string |
|
failure_reasonrequired | string | null | Set when state is failed: too_large, mime_not_allowed, quota_exceeded, empty, no_provider_id, no_token, provider_refused, provider_expired, download_failed, link_refused, link_failed, upload_failed or channel_unavailable. |
reusable_untilrequired | NullableTimestamp | Uploads only; the last moment the file can be sent with media_id. |
created_atrequired | Timestamp |
TemplateContent
| Field | Type | Description |
|---|---|---|
typerequired | "template" | |
templaterequired | object | Give id, or name and language (a name and language with several rows resolves to the single APPROVED one). POSITIONAL templates take a list ({{1}} first), NAMED templates an object of name and value. Values are text only. A text header takes its variables; a template whose header is an image, a video or a document (added within v1) takes the file as {"type": "image", "image": {"media_id": "…"}}, the upload of the same channel ( |
template.id | Id | |
template.name | string | |
template.language | string | |
template.header | object | MediaHeader | |
template.body | object | |
template.body.parametersrequired | TemplateValues | |
template.buttons | array of TemplateButtonValue | At most 10 values, one per button that takes a value. A template with a WhatsApp form button (FLOW) is unsendable (unsupported_component). |
MediaHeader
A file header (added within v1): the media_id of an upload of the same channel made with POST /media; only a document takes a filename.
One of:
| Field | Type | Description |
|---|---|---|
typerequired | "image" | |
imagerequired | HeaderFile |
| Field | Type | Description |
|---|---|---|
typerequired | "video" | |
videorequired | HeaderFile |
| Field | Type | Description |
|---|---|---|
typerequired | "document" | |
documentrequired | object | |
document.media_idrequired | Id | |
document.filename | string | max length |
HeaderFile
| Field | Type | Description |
|---|---|---|
media_idrequired | Id |
TemplateButtonValue
The value of a template button (added within v1), by the button's position in the template (index, 0 to 9).
One of:
| Field | Type | Description |
|---|---|---|
indexrequired | integer | min |
typerequired | "url" | |
parameterrequired | string | The end of the address that replaces the URL's variable. min length |
| Field | Type | Description |
|---|---|---|
indexrequired | integer | min |
typerequired | "quick_reply" | |
payloadrequired | string | Comes back as the id of the person's interactive_reply (kind button, source template). min length |
TemplateValues
Any of:
array of string
object of string
InlineConsent
Templates only; needs consents:write. Recorded before the policy check, exactly as a consent of its own. The same granted consent sent again (same fields, any Idempotency-Key) is recorded once and keeps its first time, so a later withdrawal of the person (for example STOP) still wins. A grant without collected_at is not recorded while the latest record is a withdrawal: send the time the new consent was collected.
| Field | Type | Description |
|---|---|---|
purposerequired | string |
|
staterequired | string |
|
source_textrequired | string | The exact text the person agreed to. max length |
source_refrequired | string | Your reference to the evidence (no personal data), for example web-form:checkout:7781. max length |
collected_at | string (date-time) | When the person gave or withdrew the consent; now if left out. A grant overrides an earlier withdrawal only with a collected_at after that withdrawal. |
ReadReceipt
| Field | Type | Description |
|---|---|---|
objectrequired | "read_receipt" | |
message_idrequired | Id | |
staterequired | string |
|
TypingIndicator
Added within v1. The answer of POST /conversations/{id}/typing; nothing is stored.
| Field | Type | Description |
|---|---|---|
objectrequired | "typing_indicator" | |
conversation_idrequired | Id | |
message_idrequired | string | null | WhatsApp only, the contact's message the indicator marks as read; null on other channels. |
staterequired | string | Always queued; the outcome is not reported.
|
TemplateList
| Field | Type | Description |
|---|---|---|
objectrequired | "list" | |
datarequired | array of Template | |
next_cursorrequired | string | null |
Template
| Field | Type | Description |
|---|---|---|
objectrequired | "template" | |
idrequired | Id | |
namerequired | string | |
languagerequired | string | |
categoryrequired | string | Meta's category (UTILITY, MARKETING, AUTHENTICATION). |
statusrequired | string | Meta's status (APPROVED, PENDING, REJECTED, PAUSED, DISABLED ...). |
qualityrequired | string | null | |
parameter_formatrequired | string |
|
channel_idsrequired | array of Id | |
componentsrequired | array of TemplateComponent | |
parametersrequired | TemplateParameterSchema | |
sendablerequired | boolean | |
unsendable_reasonrequired | string | null |
|
send_examplerequired | TemplateContent | null | The content object of |
status_changed_atrequired | NullableTimestamp | |
created_atrequired | NullableTimestamp | |
category_change | TemplateCategoryChange | null | Added within v1, present only once UPPU switches account protection on for the company: the open category change of the template (the latest change UPPU recorded and still follows: an announcement, a completed change or a category set at creation; see template.category_changed), or null. UPPU stops following a change when the template's category goes back, 60 days after it (after the announced date for an announcement), when the template is deleted, when a team member marks it, or when Meta completes an announced change; template.category_change_closed reports each stop. |
TemplateComponent
| Field | Type | Description |
|---|---|---|
typerequired | string | |
format | string | |
text | string | |
buttons | array of object | |
buttons[].typerequired | string | |
buttons[].textrequired | string | null | |
buttons[].url | string | |
buttons[].phone_number | string |
TemplateParameterSchema
| Field | Type | Description |
|---|---|---|
formatrequired | string |
|
headerrequired | array of TemplateVariable | |
bodyrequired | array of TemplateVariable | |
header_mediarequired | string | null | Added within v1: image, video or document when the template's header is a file (send it in content.template.header with the media_id of an upload), null otherwise.
|
buttonsrequired | array of TemplateButtonField | Added within v1: the buttons that take a value, by their position in the template. A URL button whose address has a variable needs its parameter (required true; example is the end of the address in the template's example); a quick reply may carry a payload. Buttons without a variable are not listed. |
TemplateButtonField
A button that takes a value.
| Field | Type | Description |
|---|---|---|
indexrequired | integer | min |
typerequired | string |
|
textrequired | string | null | |
requiredrequired | boolean | |
examplerequired | string | null |
TemplateVariable
| Field | Type | Description |
|---|---|---|
namerequired | string | The variable name, or its number for POSITIONAL templates. |
examplerequired | string | null |
TemplateCreateRequest
A WhatsApp template to create (POST /templates, added within v1): the rules of the panel's template page. Variables are either numbered ({{1}}, {{2}} ... from 1 without gaps) or named ({{first_name}}: lowercase letters, digits and underscores), never both; each variable once, every variable with a one-line example of at most 200 characters, and the body neither starts nor ends with a variable.
| Field | Type | Description |
|---|---|---|
channel_idrequired | string | A WhatsApp channel of the key; the template belongs to the channel's WhatsApp Business account. pattern |
namerequired | string | 1 to 512 lowercase letters, digits and underscores, for example order_update. pattern |
languagerequired | string | 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.
|
categoryrequired | string | Upper or lower case. Authentication templates cannot be created.
|
header | TemplateCreateHeader | |
bodyrequired | TemplateCreateBody | |
footer | object | One line of at most 60 characters, without variables. |
footer.textrequired | string | max length |
buttons | array 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. |
TemplateCreateHeader
A text header: one line of at most 60 characters with at most one variable ({{1}} in a numbered template) and its example. Or (added within v1) a file header with a sample file: the media_id of an upload of the same channel made with POST /media (a JPEG or PNG image up to 5 MB, an MP4 video up to 16 MB, a PDF document up to 25 MB). UPPU uploads the sample to Meta for the review (Meta's Resumable Upload); every message sent with the template still carries its own file. A header with a location cannot be created through UPPU (422 validation_failed, code not_supported).
One of:
| Field | Type | Description |
|---|---|---|
typerequired | "text" | |
textrequired | string | max length |
example | string | The example of the header's variable. max length |
TemplateCreateMediaHeader
A file header of a new template (added within v1): the sample file is the media_id of an upload of the same channel made with POST /media.
One of:
| Field | Type | Description |
|---|---|---|
typerequired | "image" | |
imagerequired | HeaderFile |
| Field | Type | Description |
|---|---|---|
typerequired | "video" | |
videorequired | HeaderFile |
| Field | Type | Description |
|---|---|---|
typerequired | "document" | |
documentrequired | HeaderFile |
TemplateCreateBody
| Field | Type | Description |
|---|---|---|
textrequired | string | Plain text of at most 1024 characters; line breaks allowed. max length |
examples | object of string | array of string | An example for every variable: an object by variable name (or number), or for a numbered template a list in the order of the numbers. |
TemplateCreateButton
quick_reply {type, text}; url {type, text, url, example}: an https or http address of at most 2000 characters whose only variable is {{1}} at its end, with example the end of an example address (the characters of a web address only); phone_number {type, text, phone_number}: E.164 with a plus sign. text is required for these three types.
| Field | Type | Description |
|---|---|---|
typerequired | string |
|
text | string | max length |
url | string | max length |
example | string | max length |
phone_number | string | pattern |
DeletedTemplate
| Field | Type | Description |
|---|---|---|
objectrequired | "template" | |
idrequired | Id | |
namerequired | string | |
languagerequired | string | |
deletedrequired | true |
MediaLink
A short-lived signed download link of a media file. url works without the API key until expires_at, for at most max_uses requests; only the expiry revokes it.
Generated from openapi.json (commit a1fec8942, 19 November 2026) · Live OpenAPI document