Meta Messaging API Message

{
  "$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"
              }
            }
          ]
        }
      }
    }
  ]
}