MESSAGE CATEGORY

Marketing

Promotions, offers, and awareness messages. No audience or campaign tooling, and no approval step.

Requirements

The recipient must actively follow your business and have opted in to marketing messages; otherwise the request is rejected with business_follow_required or marketing_opt_in_required. Your developer app token must carry the marketing scope, and the business account must be live.

Marketing accepts either a plain body or a message_content object - not both. Sending neither is rejected with invalid_message_content.

Content shape

When using message_content, these components are available:

Component	Required	Notes
header	Optional	At most one. Format `text`, or `image`/`video`/`document` with a `media_url` you already host.
body	Required	Plain text, exactly one.
buttons	Optional	1-3 buttons, each `url` or `coupon_code`. Mutually exclusive with `carousel`.
carousel	Optional	1-10 items, each with a `title`, `image_url`, and exactly one `url` button. Mutually exclusive with `buttons`.

There is no footer component for this category.

Example: plain text

{
  "to": "+15555550123",
  "category": "marketing",
  "body": "Flash sale - 20% off everything this weekend only."
}

Example: carousel

{
  "to": "+15555550123",
  "category": "marketing",
  "message_content": {
    "language": "en",
    "components": [
      { "type": "body", "text": "New arrivals just dropped." },
      {
        "type": "carousel",
        "carousel": [
          {
            "title": "Weekend tote",
            "image_url": "https://cdn.example.com/tote.jpg",
            "buttons": [ { "type": "url", "text": "Shop now", "url": "https://shop.example.com/tote" } ]
          }
        ]
      }
    ]
  }
}

See the API reference for the endpoint and error codes, or Message types for how this compares to the other categories.