Meta · Schema
Meta Messaging API Message
Represents a message across Meta messaging platforms including WhatsApp Cloud API, Messenger Platform, and Instagram Messaging. Covers text, media, template, and interactive message types.
AdvertisingAnalyticsArtificial IntelligenceMessagingSocialSocial MediaVirtual Reality
Properties
| Name | Type | Description |
|---|---|---|
| messaging_product | string | The messaging platform this message is sent through. |
| recipient_type | string | The type of recipient. Currently only 'individual' is supported for most platforms. |
| to | string | The recipient identifier. For WhatsApp this is the phone number in international format; for Messenger/Instagram this is a page-scoped or Instagram-scoped ID. |
| type | string | The type of message being sent. |
| text | object | Text message payload. Required when type is 'text'. |
| image | object | Image message payload. Required when type is 'image'. |
| audio | object | Audio message payload. Required when type is 'audio'. |
| video | object | Video message payload. Required when type is 'video'. |
| document | object | Document message payload. Required when type is 'document'. |
| sticker | object | Sticker message payload. Required when type is 'sticker'. |
| location | object | Location message payload. Required when type is 'location'. |
| contacts | array | Contact card(s) payload. Required when type is 'contacts'. |
| interactive | object | Interactive message payload with buttons or lists. Required when type is 'interactive'. |
| template | object | Template message payload for pre-approved message templates. Required when type is 'template'. |
| reaction | object | Reaction message payload. Required when type is 'reaction'. |
| context | object | Context for reply messages, referencing the original message. |
| biz_opaque_callback_data | string | Arbitrary string for tracking messages in webhook callbacks. |
JSON Schema
{
"$id": "https://meta.com/schemas/messaging/message.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Meta Messaging API Message",
"description": "Represents a message across Meta messaging platforms including WhatsApp Cloud API, Messenger Platform, and Instagram Messaging. Covers text, media, template, and interactive message types.",
"type": "object",
"required": [
"messaging_product",
"to",
"type"
],
"properties": {
"messaging_product": {
"type": "string",
"enum": [
"whatsapp",
"messenger",
"instagram"
],
"description": "The messaging platform this message is sent through."
},
"recipient_type": {
"type": "string",
"enum": [
"individual",
"group"
],
"default": "individual",
"description": "The type of recipient. Currently only 'individual' is supported for most platforms."
},
"to": {
"type": "string",
"description": "The recipient identifier. For WhatsApp this is the phone number in international format; for Messenger/Instagram this is a page-scoped or Instagram-scoped ID."
},
"type": {
"type": "string",
"enum": [
"text",
"image",
"audio",
"video",
"document",
"sticker",
"location",
"contacts",
"interactive",
"template",
"reaction"
],
"description": "The type of message being sent."
},
"text": {
"type": "object",
"description": "Text message payload. Required when type is 'text'.",
"properties": {
"body": {
"type": "string",
"maxLength": 4096,
"description": "The text content of the message."
},
"preview_url": {
"type": "boolean",
"description": "Whether to enable URL preview for the first URL in the message body."
}
},
"required": [
"body"
]
},
"image": {
"type": "object",
"description": "Image message payload. Required when type is 'image'.",
"properties": {
"id": {
"type": "string",
"description": "The media ID of a previously uploaded image."
},
"link": {
"type": "string",
"format": "uri",
"description": "URL of the image to send. Either id or link is required."
},
"caption": {
"type": "string",
"description": "Caption for the image."
}
}
},
"audio": {
"type": "object",
"description": "Audio message payload. Required when type is 'audio'.",
"properties": {
"id": {
"type": "string",
"description": "The media ID of a previously uploaded audio file."
},
"link": {
"type": "string",
"format": "uri",
"description": "URL of the audio file to send."
}
}
},
"video": {
"type": "object",
"description": "Video message payload. Required when type is 'video'.",
"properties": {
"id": {
"type": "string",
"description": "The media ID of a previously uploaded video."
},
"link": {
"type": "string",
"format": "uri",
"description": "URL of the video to send."
},
"caption": {
"type": "string",
"description": "Caption for the video."
}
}
},
"document": {
"type": "object",
"description": "Document message payload. Required when type is 'document'.",
"properties": {
"id": {
"type": "string",
"description": "The media ID of a previously uploaded document."
},
"link": {
"type": "string",
"format": "uri",
"description": "URL of the document to send."
},
"caption": {
"type": "string",
"description": "Caption for the document."
},
"filename": {
"type": "string",
"description": "The filename to display for the document."
}
}
},
"sticker": {
"type": "object",
"description": "Sticker message payload. Required when type is 'sticker'.",
"properties": {
"id": {
"type": "string",
"description": "The media ID of a previously uploaded sticker."
},
"link": {
"type": "string",
"format": "uri",
"description": "URL of the sticker to send."
}
}
},
"location": {
"type": "object",
"description": "Location message payload. Required when type is 'location'.",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude of the location."
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude of the location."
},
"name": {
"type": "string",
"description": "Name of the location."
},
"address": {
"type": "string",
"description": "Address of the location."
}
},
"required": [
"latitude",
"longitude"
]
},
"contacts": {
"type": "array",
"description": "Contact card(s) payload. Required when type is 'contacts'.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "object",
"required": [
"formatted_name"
],
"properties": {
"formatted_name": {
"type": "string",
"description": "Full formatted name of the contact."
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
}
}
},
"phones": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phone": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"CELL",
"MAIN",
"IPHONE",
"HOME",
"WORK"
]
}
}
}
},
"emails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"type": {
"type": "string",
"enum": [
"HOME",
"WORK"
]
}
}
}
}
},
"required": [
"name"
]
}
},
"interactive": {
"type": "object",
"description": "Interactive message payload with buttons or lists. Required when type is 'interactive'.",
"properties": {
"type": {
"type": "string",
"enum": [
"button",
"list",
"product",
"product_list",
"flow",
"cta_url"
],
"description": "The type of interactive message."
},
"header": {
"type": "object",
"description": "Header content for the interactive message.",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"image",
"video",
"document"
]
},
"text": {
"type": "string"
}
}
},
"body": {
"type": "object",
"description": "Body text of the interactive message.",
"properties": {
"text": {
"type": "string"
}
},
"required": [
"text"
]
},
"footer": {
"type": "object",
"description": "Footer text of the interactive message.",
"properties": {
"text": {
"type": "string"
}
}
},
"action": {
"type": "object",
"description": "The action configuration (buttons or list sections).",
"properties": {
"buttons": {
"type": "array",
"maxItems": 3,
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"reply"
]
},
"reply": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string",
"maxLength": 20
}
},
"required": [
"id",
"title"
]
}
}
}
},
"button": {
"type": "string",
"description": "Button text for list messages."
},
"sections": {
"type": "array",
"description": "Sections for list messages.",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title"
]
}
}
}
}
}
}
}
},
"required": [
"type",
"body",
"action"
]
},
"template": {
"type": "object",
"description": "Template message payload for pre-approved message templates. Required when type is 'template'.",
"properties": {
"name": {
"type": "string",
"description": "The name of the approved message template."
},
"language": {
"type": "object",
"description": "The language of the template.",
"properties": {
"code": {
"type": "string",
"description": "Language code (e.g. en_US, es, pt_BR)."
}
},
"required": [
"code"
]
},
"components": {
"type": "array",
"description": "Variable components to populate the template.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"header",
"body",
"button"
]
},
"parameters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"currency",
"date_time",
"image",
"video",
"document"
]
},
"text": {
"type": "string"
}
},
"required": [
"type"
]
}
}
}
}
}
},
"required": [
"name",
"language"
]
},
"reaction": {
"type": "object",
"description": "Reaction message payload. Required when type is 'reaction'.",
"properties": {
"message_id": {
"type": "string",
"description": "The ID of the message to react to."
},
"emoji": {
"type": "string",
"description": "The emoji to react with. Send empty string to remove reaction."
}
},
"required": [
"message_id",
"emoji"
]
},
"context": {
"type": "object",
"description": "Context for reply messages, referencing the original message.",
"properties": {
"message_id": {
"type": "string",
"description": "The ID of the message being replied to."
}
},
"required": [
"message_id"
]
},
"biz_opaque_callback_data": {
"type": "string",
"description": "Arbitrary string for tracking messages in webhook callbacks."
}
},
"additionalProperties": true,
"examples": [
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "15551234567",
"type": "text",
"text": {
"body": "Hello! Your order #12345 has been shipped and will arrive by Thursday.",
"preview_url": false
}
},
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "template",
"template": {
"name": "order_confirmation",
"language": {
"code": "en_US"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Jane"
},
{
"type": "text",
"text": "#12345"
}
]
}
]
}
},
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "Would you like to schedule a delivery?"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "schedule-yes",
"title": "Yes, schedule"
}
},
{
"type": "reply",
"reply": {
"id": "schedule-no",
"title": "No thanks"
}
}
]
}
}
}
]
}