WhatsApp Service Messages — Reference

Common envelope — present in every payload below; the per-type tables only list the type-specific object.

Field	Type	Required?	Notes
messaging_product	string	Required	Always "whatsapp".
recipient_type	string	Optional	"individual" (default).
to	string	Required	Recipient phone (E.164, with country code).
type	string	Required	Message type, e.g. text / image / interactive …

RequiredOptionalConditional — Conditional = required only in certain cases (noted).

Text

text Meta docs ↗

A text body with an optional link preview. URLs in the body are auto-hyperlinked.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here's the link to our latest product: https://www.example.com/product"
  }
}

Fields

Field	Type	Required?	Notes
text.body	string	Required	The message text. Max 4096 chars.
text.preview_url	boolean	Optional	true = render a preview of the first URL in body.

Limits

Constraint	Value
body	max 4096 characters
preview_url	previews first URL only, when true
URL scheme	must start with http:// or https://

Audio

audio Meta docs ↗

An audio clip delivered from a public URL. Audio has no caption.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "audio",
  "audio": {
    "link": "{{media_audio_url}}"
  }
}

Fields

Field	Type	Required?	Notes
audio.link	string (URL)	Required	Public URL of the audio file. Never a media id.

Limits

Constraint	Value
Max file size	16 MB
Formats	AAC, AMR, MP3, M4A, OGG (OPUS only, mono)
Caption	Not supported

Image

image Meta docs ↗

An image delivered from a public URL, with an optional caption.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "image",
  "image": {
    "link": "{{media_image_url}}",
    "caption": "Optional caption text"
  }
}

Fields

Field	Type	Required?	Notes
image.link	string (URL)	Required	Public URL of the image. Never a media id.
image.caption	string	Optional	Caption shown under the image. Max 1024 chars.

Limits

Constraint	Value
Max file size	5 MB
Formats	JPEG, PNG
caption	max 1024 characters

Video

video Meta docs ↗

A video delivered from a public URL, with an optional caption.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "video",
  "video": {
    "link": "{{media_video_url}}",
    "caption": "Optional caption text"
  }
}

Fields

Field	Type	Required?	Notes
video.link	string (URL)	Required	Public URL of the video. Never a media id.
video.caption	string	Optional	Caption shown under the video. Max 1024 chars.

Limits

Constraint	Value
Max file size	16 MB
Formats	MP4, 3GPP — H.264 video + AAC audio only
caption	max 1024 characters

Document

document Meta docs ↗

A document (PDF, Office files, txt, etc.) delivered from a public URL.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "document",
  "document": {
    "link": "{{media_document_url}}",
    "caption": "Optional caption text",
    "filename": "document.pdf"
  }
}

Fields

Field	Type	Required?	Notes
document.link	string (URL)	Required	Public URL of the document. Never a media id.
document.caption	string	Optional	Caption shown with the document. Max 1024 chars.
document.filename	string	Optional	Display filename; extension drives the file-type icon.

Limits

Constraint	Value
Max file size	100 MB
caption	max 1024 characters
filename	display name; extension drives the file-type icon

Sticker

sticker Meta docs ↗

A WebP sticker delivered from a public URL. No caption.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "sticker",
  "sticker": {
    "link": "{{media_sticker_url}}"
  }
}

Fields

Field	Type	Required?	Notes
sticker.link	string (URL)	Required	Public URL of the .webp sticker. Never a media id.

Limits

Constraint	Value
Format	WebP only
Static	max 100 KB
Animated	max 500 KB
Caption	Not supported

Contacts

contacts Meta docs ↗

One or more contact cards. contacts is an array — each entry is a full contact.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe"
      },
      "phones": [
        {
          "phone": "+16505551234",
          "type": "WORK",
          "wa_id": "16505551234"
        }
      ],
      "emails": [
        {
          "email": "john@example.com",
          "type": "WORK"
        }
      ],
      "org": {
        "company": "Example Inc",
        "department": "Sales",
        "title": "Manager"
      },
      "urls": [
        {
          "url": "https://www.example.com",
          "type": "WORK"
        }
      ],
      "addresses": [
        {
          "street": "1 Hacker Way",
          "city": "Menlo Park",
          "state": "CA",
          "zip": "94025",
          "country": "United States",
          "country_code": "us",
          "type": "WORK"
        }
      ],
      "birthday": "1990-01-15"
    }
  ]
}

Fields

Field	Type	Required?	Notes
contacts	array	Required	Array of contact objects.
contacts[].name	object	Required	Name object.
name.formatted_name	string	Required	Full display name.
name.first_name / last_name / …	string	Conditional	At least one required besides formatted_name.
contacts[].phones	array	Optional	phone, type (HOME/WORK), wa_id.
contacts[].emails	array	Optional	email, type.
contacts[].org	object	Optional	company, department, title.
contacts[].urls	array	Optional	url, type.
contacts[].addresses	array	Optional	street, city, state, zip, country, country_code, type.
contacts[].birthday	string	Optional	YYYY-MM-DD.

Limits

Constraint	Value
name	formatted_name + ≥1 other name field
type fields	HOME or WORK
birthday	YYYY-MM-DD
wa_id	makes the phone tappable to open a chat

Location

location Meta docs ↗

A pin on the map. Optionally labelled with a name and address.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "location",
  "location": {
    "latitude": "21.1938",
    "longitude": "81.3509",
    "name": "Atmik Bharat Industries",
    "address": "Bhilai, Chhattisgarh, India"
  }
}

Fields

Field	Type	Required?	Notes
location.latitude	string/number	Required	Latitude.
location.longitude	string/number	Required	Longitude.
location.name	string	Optional	Label for the pin.
location.address	string	Optional	Address under the name.

Limits

Constraint	Value
latitude / longitude	required
name + address	optional — set together so the pin shows a label

Reaction

reaction Meta docs ↗

React to a previous message with a single emoji.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "reaction",
  "reaction": {
    "message_id": "{{wamid_to_react_to}}",
    "emoji": "👍"
  }
}

Fields

Field	Type	Required?	Notes
reaction.message_id	string (wamid)	Required	wamid being reacted to.
reaction.emoji	string	Required	Single emoji, or "" to remove.

Limits

Constraint	Value
message_id	valid wamid, ≤ 30 days old, not deleted
emoji	single emoji; "" removes the reaction

Interactive — Reply buttons

interactive · button Meta docs ↗

Up to 3 quick-reply buttons under a body, with optional header and footer.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "image": {
        "link": "{{media_image_url}}"
      }
    },
    "body": {
      "text": "Pick an option below."
    },
    "footer": {
      "text": "Powered by Atmik Bharat"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "btn-1",
            "title": "Yes"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn-2",
            "title": "No"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn-3",
            "title": "Maybe"
          }
        }
      ]
    }
  }
}

Fields

Field	Type	Required?	Notes
interactive.type	string	Required	Must be "button".
interactive.body.text	string	Required	Body text. Max 1024.
interactive.header	object	Optional	text, or media via link.
interactive.footer.text	string	Optional	Max 60.
action.buttons	array	Required	1–3 buttons.
buttons[].reply.id	string	Required	Unique payload id. Max 256.
buttons[].reply.title	string	Required	Label. Max 20.

Limits

Constraint	Value
Buttons	1 to 3
Button title	max 20 characters
Button id	max 256 characters, unique per message
body.text	max 1024 characters
footer.text	max 60 characters
header	optional — text or media via link

Interactive — List

interactive · list Meta docs ↗

A button that opens a list of selectable rows, grouped into sections.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Our Menu"
    },
    "body": {
      "text": "Choose an item from the list."
    },
    "footer": {
      "text": "Powered by Atmik Bharat"
    },
    "action": {
      "button": "View options",
      "sections": [
        {
          "title": "Channels",
          "rows": [
            {
              "id": "row-wa",
              "title": "WhatsApp",
              "description": "WABA messaging & calling"
            },
            {
              "id": "row-ig",
              "title": "Instagram",
              "description": "DM & comment management"
            }
          ]
        },
        {
          "title": "Tools",
          "rows": [
            {
              "id": "row-flow",
              "title": "Workflows",
              "description": "No-code automation"
            }
          ]
        }
      ]
    }
  }
}

Fields

Field	Type	Required?	Notes
interactive.type	string	Required	Must be "list".
interactive.body.text	string	Required	Body text. Max 4096.
interactive.header	object	Optional	Text only.
interactive.footer.text	string	Optional	Max 60.
action.button	string	Required	Opener label. Max 20.
action.sections	array	Required	1–10 sections.
sections[].title	string	Conditional	Required if >1 section. Max 24.
sections[].rows	array	Required	Max 10 total across all sections.
rows[].id	string	Required	Unique. Max 200.
rows[].title	string	Required	Max 24.
rows[].description	string	Optional	Max 72.

Limits

Constraint	Value
Total rows	max 10 across all sections
Sections	max 10
Row title	max 24
Row description	max 72
Row id	max 200
Section title	max 24
Button label	max 20
body.text	max 4096
footer.text	max 60
header	text only

Interactive — URL button (CTA URL)

interactive · cta_url Meta docs ↗

A tappable button that opens a URL in the device browser.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "text",
      "text": "Special offer"
    },
    "body": {
      "text": "Tap below to view the offer on our website."
    },
    "footer": {
      "text": "Powered by Atmik Bharat"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Visit website",
        "url": "https://www.example.com/offer"
      }
    }
  }
}

Fields

Field	Type	Required?	Notes
interactive.type	string	Required	Must be "cta_url".
interactive.body.text	string	Required	Max 1024.
interactive.header	object	Optional	text or media via link.
interactive.footer.text	string	Optional	Max 60.
action.name	string	Required	Must be "cta_url".
action.parameters.display_text	string	Required	Button label.
action.parameters.url	string (URL)	Required	Destination URL.

Limits

Constraint	Value
display_text	~20 characters
body.text	max 1024
footer.text	max 60
header	optional — text or media via link

Interactive — Media carousel

interactive · carousel Meta docs ↗

Horizontally scrollable media cards with image/video headers and buttons.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Here are three of our latest arrivals:"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "{{media_image_url}}"
            }
          },
          "body": {
            "text": "*Card one*\\n\\nShort description under 160 characters."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.example.com/item-1"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "{{media_image_url}}"
            }
          },
          "body": {
            "text": "*Card two*\\n\\nShort description under 160 characters."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.example.com/item-2"
            }
          }
        }
      ]
    }
  }
}

Fields

Field	Type	Required?	Notes
interactive.type	string	Required	Must be "carousel".
interactive.body.text	string	Required	Main body. Max 1024.
action.cards	array	Required	2–10 cards.
cards[].card_index	integer	Required	Zero-based order.
cards[].header	object	Required	image/video via link.
cards[].body.text	string	Optional	Max 160.
cards[].action	object	Required	cta_url params OR quick_reply buttons[] — must match across cards.

Limits

Constraint	Value
Cards	2 to 10
Main body.text	required, max 1024
Main header/footer	not supported
Card header	required — image/video via link
Card body.text	optional, max 160, ≤2 line breaks
Card buttons	1 URL button OR ≥1 quick-reply — type & count must match across ALL cards
Button label	max 20
quick-reply id	max 256

Location request

interactive · location_request_message Meta docs ↗

Prompts the user with a Send location button; result arrives via webhook.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": {
      "text": "Please share your location so we can find the nearest store."
    },
    "action": {
      "name": "send_location"
    }
  }
}

Fields

Field	Type	Required?	Notes
interactive.type	string	Required	Must be "location_request_message".
interactive.body.text	string	Required	Prompt. Max 1024.
action.name	string	Required	Must be "send_location".

Limits

Constraint	Value
body.text	max 1024 characters
action.name	must be send_location

Address

interactive · address_message Meta docs ↗

Native address form. Availability: India (IN) and Singapore (SG) only. Result via webhook.

Request payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{recipient_phone}}",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Please provide your delivery address."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "values": {
          "name": "John Doe",
          "phone_number": "+919999999999",
          "in_pin_code": "490001",
          "house_number": "12",
          "floor_number": "2",
          "tower_number": "A",
          "building_name": "Sunrise Apartments",
          "address": "Civic Centre Road",
          "landmark_area": "Near City Mall",
          "city": "Bhilai",
          "state": "Chhattisgarh"
        },
        "saved_addresses": [
          {
            "id": "address1",
            "value": {
              "name": "John Doe",
              "phone_number": "+919999999999",
              "in_pin_code": "490001",
              "house_number": "12",
              "address": "Civic Centre Road",
              "city": "Bhilai",
              "state": "Chhattisgarh"
            }
          }
        ]
      }
    }
  }
}

Fields

Field	Type	Required?	Notes
interactive.type	string	Required	Must be "address_message".
interactive.body.text	string	Required	Prompt text.
action.name	string	Required	Must be "address_message".
action.parameters.country	string	Required	"IN" or "SG".
action.parameters.values	object	Optional	Pre-fill (country-specific).
action.parameters.saved_addresses	array	Optional	Saved addresses to pick from.
action.parameters.validation_errors	object	Optional	field → error map.

Limits

Constraint	Value
Availability	India (IN) & Singapore (SG) only
country	IN or SG — values schema differs
IN values	in_pin_code, house_number, floor_number, tower_number, building_name, landmark_area, city, state…
SG values	sg_post_code, unit_number, floor_number…
values	optional — prefills the form
saved_addresses	optional — pick from saved
validation_errors	optional — field → error

On preview images: Meta's docs show a rendered preview per type, but those images use signed CDN URLs that expire within days — embedding them would break. The Meta docs ↗ link on each card opens the page where its live preview is shown.