Skip to content

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.

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.

TemplateCategoryChange: Fields
FieldTypeDescription
idrequiredId
kindrequiredstring
  • changed
  • announced
  • created_as
previous_categoryrequiredstring | null

Meta's category before the change (UTILITY, MARKETING, AUTHENTICATION).

new_categoryrequiredstring

Meta's category after the change.

changed_atrequiredTimestamp
scheduled_atrequiredNullableTimestamp
appeal_untilrequiredNullableTimestamp
reviewablerequiredboolean

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.

Message: Fields
FieldTypeDescription
objectrequired"message"
idrequiredId
channel_idrequiredId
channel_typerequiredstring
conversation_idrequiredId
contact_idrequiredId
directionrequiredstring
  • in
  • out
authorrequiredMessageAuthor
contentrequiredMessageContent
contextrequiredMessageContext | null
templaterequiredMessageTemplate | null
previewrequiredstring
statusrequiredstring

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.

  • queued
  • accepted
  • sent
  • delivered
  • read
  • failed
  • unknown
  • expired
  • received
status_changed_atrequiredNullableTimestamp
errorrequiredDeliveryError | null
client_referencerequiredstring | null

max length 64

provider_message_idrequiredstring | null
sent_atrequiredNullableTimestamp

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_atrequiredNullableTimestamp

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_atrequiredTimestamp
retryMessageRetry

Added within v1, available once UPPU switches account protection on for your company; until then the key is absent. Only in the answers of GET /messages/{id}, GET /messages and POST /messages (202 and the 200 replay): never in webhook bodies, GET /events answers or sandbox events. Present only when UPPU recorded a retry for a send that asked for retry.per_user_limit (a MARKETING template, sent while your company kept these retries switched on), on the first message and on every resend of it; otherwise the key is absent, never null. On a 202 that asked for retry, no key means that no retry was recorded. The key is absent again once UPPU deletes the record: 8 days after a send that Meta did not fail with error 131049, or 30 days after the retry reached its final state. Every key that can read the message sees it. Match a resend to your send by client_reference or by latest_message_id.

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.

MessageRetry: Fields
FieldTypeDescription
staterequiredstring

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.

  • watching
  • waiting
  • sending
  • sent
  • delivered
  • sent_unconfirmed
  • exhausted
  • stopped
attemptsrequiredinteger

Resends started so far. A round that UPPU held (held_reason) gives its number back and does not count.

min 0

max_attemptsrequiredinteger

The most resends UPPU makes for one send.

min 1

first_failed_atrequiredNullableTimestamp

When Meta first failed the send with 131049; null before that.

last_failed_atrequiredNullableTimestamp

The latest 131049 of the chain; null before the first.

window_ends_atrequiredNullableTimestamp

UPPU resends only before this time (7 days after the first 131049); null before the first.

next_attempt_atrequiredNullableTimestamp

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

  • channel_backlog
  • iys_unavailable
  • iys_credentials
  • channel_unavailable
  • channel_paused
  • tenant_read_only
  • service_stopped
  • outage
  • null
stop_reasonrequiredstring | 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.

  • company_off
  • key_unusable
  • rejected
  • other_error
  • expired
  • message_gone
  • null
stop_coderequiredstring | null

The API error code of the refusal that stopped the retries (stop_reason rejected or key_unusable); null otherwise.

original_message_idrequiredId | null

The first message of the send; null once it was deleted.

latest_message_idrequiredId | null

The newest message of the chain (the first message until a resend); null once it was deleted.

final_atrequiredNullableTimestamp

When the retries reached a final state; null before that.

MessageAuthor

MessageAuthor: Fields
FieldTypeDescription
typerequiredstring

contact, agent (the team), system (UPPU), api (your API key) or bot (UPPU Bot; label is the bot's display name).

  • contact
  • agent
  • system
  • api
  • botComing soon
labelrequiredstring | null
api_key_prefixrequiredstring | 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).

MessageContent: Fields
FieldTypeDescription
typerequiredstring

Other keys may appear: read the ones you know and ignore the rest.

MessageContext

MessageContext: Fields
FieldTypeDescription
message_idrequiredstring | null
provider_message_idrequiredstring | null
forwardedrequiredboolean
frequently_forwardedrequiredboolean
referralrequiredobject | null
storyobject

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.idrequiredstring | null
start_parameterstring

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_idstring

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

MessageTemplate: Fields
FieldTypeDescription
idrequiredstring | null
namerequiredstring | null
languagerequiredstring | null
categoryrequiredstring | null

DeliveryError

DeliveryError: Fields
FieldTypeDescription
coderequiredstring
  • window_closed
  • payment_required
  • marketing_opt_out
  • not_registered
  • recipient_unreachable
  • provider_rate_limited
  • provider_unavailable
  • credentials_invalid
  • permission_denied
  • account_restricted
  • invalid_parameter
  • channel_unavailable
  • channel_paused
  • no_recipient
  • template_unavailable
  • media_fetch_failed
  • media_upload_failed
  • media_rejected
  • delivery_unverified
  • ttl_expired
  • service_stopped
  • provider_error
messagerequiredstring
retryablerequiredboolean
provider_errorrequiredProviderError | null

ProviderError

ProviderError: Fields
FieldTypeDescription
providerrequiredstring

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

  • meta
  • telegram
  • email
coderequiredinteger
subcoderequiredinteger | null
titlerequiredstring | null
detailsrequiredstring | null

MessageList

MessageList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of Message
next_cursorrequiredstring | null

SendMessageRequest

SendMessageRequest: Fields
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).

context.message_idrequiredId
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.

retry.per_user_limitrequiredboolean

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:

Recipient: variant 1
FieldTypeDescription
contact_idrequiredId
Recipient: variant 2
FieldTypeDescription
phonerequiredstring

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

Recipient: variant 3
FieldTypeDescription
identityrequiredobject
identity.typerequiredstring
  • bsuid
  • psid
  • igsid
  • web_visitor
  • telegram
  • email
identity.valuerequiredstring

max length 255

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

InteractiveContent

ReactionContent

LocationContent

TemplateContent

MediaContent

StickerContent

ContactsContent

TextContent

TextContent: Fields
FieldTypeDescription
typerequired"text"
textrequiredobject
text.bodyrequiredstring

min length 1

text.preview_urlboolean

InteractiveContent

InteractiveContent: Fields
FieldTypeDescription
typerequired"interactive"
interactiverequiredobject

body is required on every type.

interactive.typerequiredstring

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

  • buttons
  • list
  • quick_replies
  • cta_url
  • request_phone
interactive.headerobject | 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 (POST /media; a link is not accepted), with the MIME types and sizes of the media type. A list message takes only a text header. Messenger, Instagram and Telegram take no header: 422 content_not_supported_on_channel (details.field content.interactive.header).

interactive.bodyobject
interactive.body.textrequiredstring
interactive.footerobject
interactive.footer.textrequiredstring
interactive.buttonsarray of InteractiveOption

Buttons and quick replies messages only.

interactive.buttonstring

List message only; the label of the list button.

interactive.sectionsarray of object

List message only.

interactive.sections[].titlestring
interactive.sections[].rowsrequiredarray of InteractiveOption
interactive.cta_urlobject

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_textrequiredstring
interactive.cta_url.urlrequiredstring
interactive.request_phoneobject

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_textrequiredstring

InteractiveOption

InteractiveOption: Fields
FieldTypeDescription
idrequiredstring
titlerequiredstring
descriptionstring

List rows only.

ReactionContent

ReactionContent: Fields
FieldTypeDescription
typerequired"reaction"
reactionrequiredobject
reaction.message_idrequiredId
reaction.emojirequiredstring

An empty string asks the channel to remove the reaction.

LocationContent

LocationContent: Fields
FieldTypeDescription
typerequired"location"
locationrequiredobject
location.latituderequirednumber

min -90 · max 90

location.longituderequirednumber

min -180 · max 180

location.namestring
location.addressstring

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.

MediaContent: Fields
FieldTypeDescription
typerequiredstring
  • image
  • video
  • audio
  • document
imageMediaSource
videoMediaSource
audioMediaSource
documentMediaSource

MediaSource

MediaSource: Fields
FieldTypeDescription
media_idId
linkstring

pattern ^https:// · max length 2048

captionstring
filenamestring

max length 255

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.

StickerContent: Fields
FieldTypeDescription
typerequired"sticker"
stickerrequiredobject
sticker.media_idrequiredId

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.

ContactsContent: Fields
FieldTypeDescription
typerequired"contacts"
contactsrequiredobject
contacts.contactsrequiredarray of ContactCard

ContactCard

ContactCard: Fields
FieldTypeDescription
namerequiredobject
name.formatted_namerequiredstring

The name as it is shown.

min length 1

name.first_namestring
name.last_namestring
name.middle_namestring
name.prefixstring
name.suffixstring
phonesarray of object
phones[].phonerequiredstring
phones[].typestring

For example CELL, MAIN, IPHONE, HOME or WORK.

emailsarray of object
emails[].emailrequiredstring
emails[].typestring

For example HOME or WORK.

orgobject
org.companystring
org.departmentstring
org.titlestring

Media

Media: Fields
FieldTypeDescription
objectrequired"media"
idrequiredId
channel_idrequiredstring | null
directionrequiredstring
  • in
  • out
kindrequiredstring
  • image
  • video
  • audio
  • document
  • sticker
mime_typerequiredstring | null
sizerequiredinteger | null

Bytes; null until the file is stored.

sha256requiredstring | null

The hex SHA-256 of the stored file; null until it is stored.

filenamerequiredstring | null
staterequiredstring
  • pending
  • ready
  • failed
  • expired
failure_reasonrequiredstring | 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_untilrequiredNullableTimestamp

Uploads only; the last moment the file can be sent with media_id.

created_atrequiredTimestamp

TemplateContent

TemplateContent: Fields
FieldTypeDescription
typerequired"template"
templaterequiredobject

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 (POST /media, no link; an image JPEG or PNG up to 5 MB, a video MP4 or 3GPP up to 16 MB, a document PDF only, up to 25 MB), and a document may carry the filename the person sees. Buttons (added within v1): give a value only for a button that takes one, by its position in the template (index, from 0): a URL button whose address ends in a variable needs its parameter (the end of the address: characters of a web address, others percent-encoded; with the template's address at most capabilities.limits.template_button_url characters), a quick reply may carry a payload (at most capabilities.limits.template_button_payload characters) that comes back in the person's tap. Buttons without a variable (a fixed address, a phone number, a quick reply without payload) take no value: they come with the approved template. GET /templates lists what a template needs (parameters.header_media, parameters.buttons). A value that does not fit the template is 422 template_parameters_invalid with the field paths (content.template.header, content.template.buttons.0.parameter); a file that cannot be used is 422 media_unavailable, 422 validation_failed (mime_not_allowed) or 413 media_too_large for content.template.header.<type>.media_id.

template.idId
template.namestring
template.languagestring
template.headerobject | MediaHeader
template.bodyobject
template.body.parametersrequiredTemplateValues
template.buttonsarray 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:

MediaHeader: variant 1
FieldTypeDescription
typerequired"image"
imagerequiredHeaderFile
MediaHeader: variant 2
FieldTypeDescription
typerequired"video"
videorequiredHeaderFile
MediaHeader: variant 3
FieldTypeDescription
typerequired"document"
documentrequiredobject
document.media_idrequiredId
document.filenamestring

max length 255

HeaderFile

HeaderFile: Fields
FieldTypeDescription
media_idrequiredId

TemplateButtonValue

The value of a template button (added within v1), by the button's position in the template (index, 0 to 9).

One of:

TemplateButtonValue: variant 1
FieldTypeDescription
indexrequiredinteger

min 0 · max 9

typerequired"url"
parameterrequiredstring

The end of the address that replaces the URL's variable.

min length 1

TemplateButtonValue: variant 2
FieldTypeDescription
indexrequiredinteger

min 0 · max 9

typerequired"quick_reply"
payloadrequiredstring

Comes back as the id of the person's interactive_reply (kind button, source template).

min length 1

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.

InlineConsent: Fields
FieldTypeDescription
purposerequiredstring
  • marketing
  • utility
staterequiredstring
  • granted
  • withdrawn
source_textrequiredstring

The exact text the person agreed to.

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. A grant overrides an earlier withdrawal only with a collected_at after that withdrawal.

ReadReceipt

ReadReceipt: Fields
FieldTypeDescription
objectrequired"read_receipt"
message_idrequiredId
staterequiredstring
  • queued
  • accepted
  • failed
  • unknown

TypingIndicator

Added within v1. The answer of POST /conversations/{id}/typing; nothing is stored.

TypingIndicator: Fields
FieldTypeDescription
objectrequired"typing_indicator"
conversation_idrequiredId
message_idrequiredstring | null

WhatsApp only, the contact's message the indicator marks as read; null on other channels.

staterequiredstring

Always queued; the outcome is not reported.

  • queued

TemplateList

TemplateList: Fields
FieldTypeDescription
objectrequired"list"
datarequiredarray of Template
next_cursorrequiredstring | null

Template

Template: Fields
FieldTypeDescription
objectrequired"template"
idrequiredId
namerequiredstring
languagerequiredstring
categoryrequiredstring

Meta's category (UTILITY, MARKETING, AUTHENTICATION).

statusrequiredstring

Meta's status (APPROVED, PENDING, REJECTED, PAUSED, DISABLED ...).

qualityrequiredstring | null
parameter_formatrequiredstring
  • NAMED
  • POSITIONAL
channel_idsrequiredarray of Id
componentsrequiredarray of TemplateComponent
parametersrequiredTemplateParameterSchema
sendablerequiredboolean
unsendable_reasonrequiredstring | null
  • not_approved
  • paused
  • category_not_allowed
  • unsupported_component
  • null
send_examplerequiredTemplateContent | null

The content object of POST /messages with the template's own examples; null when the template cannot be sent. A variable without an example reads <name> and a URL button's parameter without one <1>; a file header carries a placeholder media_id made of zeros only: upload the file with POST /media and give its id.

status_changed_atrequiredNullableTimestamp
created_atrequiredNullableTimestamp
category_changeTemplateCategoryChange | 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

TemplateComponent: Fields
FieldTypeDescription
typerequiredstring
formatstring
textstring
buttonsarray of object
buttons[].typerequiredstring
buttons[].textrequiredstring | null
buttons[].urlstring
buttons[].phone_numberstring

TemplateParameterSchema

TemplateParameterSchema: Fields
FieldTypeDescription
formatrequiredstring
  • named
  • positional
headerrequiredarray of TemplateVariable
bodyrequiredarray of TemplateVariable
header_mediarequiredstring | 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.

  • image
  • video
  • document
  • null
buttonsrequiredarray 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.

TemplateButtonField: Fields
FieldTypeDescription
indexrequiredinteger

min 0

typerequiredstring
  • url
  • quick_reply
textrequiredstring | null
requiredrequiredboolean
examplerequiredstring | null

TemplateVariable

TemplateVariable: Fields
FieldTypeDescription
namerequiredstring

The variable name, or its number for POSITIONAL templates.

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

TemplateCreateRequest: Fields
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.

footer.textrequiredstring

max length 60

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.

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:

TemplateCreateHeader: variant 1
FieldTypeDescription
typerequired"text"
textrequiredstring

max length 60

examplestring

The example of the header's variable.

max length 200

TemplateCreateMediaHeader

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:

TemplateCreateMediaHeader: variant 1
FieldTypeDescription
typerequired"image"
imagerequiredHeaderFile
TemplateCreateMediaHeader: variant 2
FieldTypeDescription
typerequired"video"
videorequiredHeaderFile
TemplateCreateMediaHeader: variant 3
FieldTypeDescription
typerequired"document"
documentrequiredHeaderFile

TemplateCreateBody

TemplateCreateBody: Fields
FieldTypeDescription
textrequiredstring

Plain text of at most 1024 characters; line breaks allowed.

max length 1024

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

TemplateCreateButton: Fields
FieldTypeDescription
typerequiredstring
  • quick_reply
  • url
  • phone_number
textstring

max length 25

urlstring

max length 2000

examplestring

max length 2000

phone_numberstring

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

DeletedTemplate

DeletedTemplate: Fields
FieldTypeDescription
objectrequired"template"
idrequiredId
namerequiredstring
languagerequiredstring
deletedrequiredtrue

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