> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketing Messages API

> Meta's dedicated API for marketing template messages — unlocks Creative Optimizations, conversion tracking, and message TTL.

The Marketing Messages API (MM API) is Meta's advanced send endpoint for WhatsApp marketing templates. It sits alongside the standard Cloud API and activates a set of features — Creative Optimizations, click tracking, message TTL, and conversion metrics — that are not available when sending through the regular `POST /<phone_id>/messages` endpoint.

## Cloud API vs Marketing Messages API

| Feature                  | Cloud API                   | Marketing Messages API                |
| ------------------------ | --------------------------- | ------------------------------------- |
| Send endpoint            | `POST /<phone_id>/messages` | `POST /<phone_id>/marketing_messages` |
| Message TTL              | Not configurable            | 12 hours – 30 days                    |
| Creative Optimizations   | No                          | Yes (+13.9% avg CTR)                  |
| Click tracking           | No                          | Yes                                   |
| Conversion metrics       | No                          | Yes                                   |
| Read rate benchmarks     | No                          | Yes                                   |
| Webhook pricing category | `marketing`                 | `marketing_lite`                      |
| Fallback behaviour       | —                           | `CLOUD_API_FALLBACK` or `STRICT`      |
| Onboarding requirement   | None                        | WABA ToS signed + `ONBOARDED`         |

## How to enable

<Steps>
  <Step title="Sign the WABA Terms of Service">
    Go to **Meta Business Manager → WhatsApp Accounts → \[your WABA] → Settings**. Accept the Marketing Messages Terms of Service if prompted. You cannot proceed without this step.
  </Step>

  <Step title="Check onboarding status">
    In Switchbord, go to **Settings → Channel**. The `onboarding_status` field must read `ONBOARDED`. If it shows `NOT_ONBOARDED` or is missing, complete the Meta onboarding flow first.
  </Step>

  <Step title="Enable in Switchbord">
    Go to **Settings → Channel → Marketing Messages API** and toggle it on. Switchbord stores this preference and routes eligible marketing template sends through the MM API endpoint automatically.
  </Step>
</Steps>

## Message TTL

TTL (time-to-live) controls how long WhatsApp holds a message waiting for delivery before discarding it. The default Cloud API TTL is 30 days for all messages. With MM API you can set it per-message:

* **12 hours**: flash sales, event day reminders — discard if the user is offline too long
* **7 days**: weekly newsletter, standard campaign
* **30 days**: re-engagement, winback (same as Cloud API default)

Set `ttl` in the MM API request body (in seconds). A value of `43200` = 12 hours, `604800` = 7 days, `2592000` = 30 days.

```json theme={null}
POST /<PHONE_NUMBER_ID>/marketing_messages
{
  "messaging_product": "whatsapp",
  "to": "+393289214993",
  "ttl": 43200,
  "product_policy": "CLOUD_API_FALLBACK",
  "template": {
    "name": "summer_flash_sale",
    "language": { "code": "it" }
  }
}
```

## Creative Optimizations

When `creative_optimizations` is enabled in your channel settings, Meta's delivery system may automatically adjust message timing, copy variant selection, or button order to maximise engagement. Across Meta's internal tests this raised average CTR by 13.9%.

Optimizations apply at delivery time and are invisible in the API payload — you send the same template, Meta decides the optimal rendering for each recipient.

## Click tracking and conversion metrics

MM API automatically tracks:

* **Link clicks**: taps on URL buttons in the template
* **Conversions**: downstream purchase or booking events (requires Meta Pixel or CAPI integration)
* **Read rate**: percentage of delivered messages opened within 24 hours

These metrics appear in **Meta Business Manager → WhatsApp Manager → Insights** and are also available via the Graph API reporting endpoints. Switchbord surfaces a read rate summary on the campaign detail page.

## `product_policy`

Controls what happens if the phone number is not fully onboarded for MM API:

| Value                | Behaviour                                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLOUD_API_FALLBACK` | If MM API delivery fails due to onboarding, the message falls back to the standard Cloud API send automatically. No error returned to your server. |
| `STRICT`             | If MM API delivery is not available, the message fails with an error. Use this if you must guarantee MM API features (e.g. TTL) are applied.       |

## `message_activity_sharing`

Controls whether read receipts for this specific message are shared with Meta for delivery optimisation. Default is `true`. Set to `false` if your workspace has a privacy policy that prohibits sharing engagement signals.

## Per-user delivery limits

WhatsApp limits the number of marketing messages delivered to users with low engagement. This is separate from MM API — it applies to all marketing templates regardless of send path.

### Error codes

| Code     | Meaning                                                              | Action                                                                                     |
| -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `131049` | Per-user marketing limit reached. Message not delivered.             | Wait at least 24 hours before retrying to this user.                                       |
| `131050` | User has stopped receiving marketing messages from this business.    | Update `subscriber_status = unsubscribed`. Do **not** retry — this is a permanent opt-out. |
| `131063` | Marketing templates are disabled on Cloud API for this phone number. | Switch to the MM API endpoint.                                                             |

### Silent limits

If a message is not delivered and no error code is returned, the user has hit WhatsApp's silent per-user limit. Monitor campaign read rates — a sudden drop without delivery errors is the primary signal.

### Regional exemptions

The following regions are **exempt** from per-user marketing delivery limits:

* European Economic Area (EEA)
* United Kingdom
* Japan
* South Korea

### US numbers

Marketing template delivery to US (+1) phone numbers has been paused since April 2025. Templates will not be delivered to US numbers through either Cloud API or MM API until Meta lifts the restriction.

## Targeting by contact tag

To send only to engaged segments, filter campaign recipients by tag before sending. Common tag patterns:

| Tag                | Meaning                       |
| ------------------ | ----------------------------- |
| `import:list-name` | Imported from a specific list |
| `confirmed-2026`   | Confirmed booking in 2026     |
| `futura-agency`    | Agency contact                |

See [Contacts import](/features/contacts-import) for how tags are assigned on bulk import.

## See also

* [Configure marketing messages](/getting-started/configure-marketing) — enable MM API step by step
* [Marketing templates](/whatsapp/marketing-templates) — category rules and opt-out requirements
* [Template rules](/whatsapp/template-rules) — Meta validation rules reference