# Marketing

## Endpoints

- `POST /graph/whatsapp/{version}/{phoneNumberId}/marketing_messages`: [Send a marketing message](https://docs.polymorfa.com/api/graph/marketing/send-a-marketing-message)
- `GET /graph/whatsapp/{version}/{wabaId}/marketing_messages/status`: [Get marketing status](https://docs.polymorfa.com/api/graph/marketing/get-marketing-status)

## Send a marketing message

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/marketing_messages` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

Requires an explicit STRICT product policy. The connected Meta account must independently meet Marketing Messages eligibility and terms requirements. A simulated Number cannot send this request.

Send a marketing template through a connected Official API Number with a credential
that has `messages:write`. Meta must allow that account to use its Marketing
Messages API and accept the required terms. This request does not enroll an
account or accept terms for it. A simulated Number cannot send it.

Set `product_policy` to `STRICT` explicitly. The endpoint rejects a missing
policy or `CLOUD_API_FALLBACK`. Include the recipient, a template name, and a
deterministic language code:

```json
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "YOUR_APPROVED_TEMPLATE",
    "language": { "policy": "deterministic", "code": "en_US" }
  },
  "product_policy": "STRICT"
}
```

When you provide `template.components`, use the shapes in the API reference.
Carousel components accept 1 to 10 cards with zero-based `card_index` values from 0 to 9.
For a date-time body parameter, include `fallback_value`; you may also send
`year`, `month`, `day_of_month`, `hour`, `minute`, `day_of_week`, and `calendar`
as structured values supported by Meta.
For a limited-time offer template, send one `limited_time_offer` component
with one `limited_time_offer` parameter whose `expiration_time_ms` is the
offer's expiration as a Unix timestamp in milliseconds:

```json
{
  "type": "limited_time_offer",
  "parameters": [
    {
      "type": "limited_time_offer",
      "limited_time_offer": { "expiration_time_ms": 1767225600000 }
    }
  ]
}
```

Buttons accept the `quick_reply`, `url`, `catalog`, and `copy_code` subtypes.
The endpoint rejects other button subtypes, such as Flow or multi-product
buttons.

Send the body as `Content-Type: application/json`. The endpoint validates the
whole request before sending it to Meta. A `400` response names the field that
failed validation. For a component, it reports the field within the component
matching your `type` and `sub_type`, or reports an unsupported component when
none matches.

Meta returns the send response and remains the authority for account
eligibility, template approval, message status, and any charge. This endpoint
does not switch a Campaign send to Marketing Messages. After an uncertain
response, reconcile the message with Meta and your status webhooks before
deciding whether to send again. Do not replay the request blindly.

Set `message_activity_sharing` only after establishing the required permission
for that recipient and account. Direct Graph requests do not perform Campaign
audience suppression and opt-out checks; use the Campaign workflow when those
controls are required.

[Read the WABA's Marketing Messages status](https://docs.polymorfa.com/api/graph/marketing/get-marketing-status?playground=open)
to check onboarding and terms before sending. WhatsApp still decides each send.

## Errors and recovery

Errors use Meta's envelope and codes. These are the Marketing Messages errors
Meta documents:

| Code | Meaning | Recovery |
| --- | --- | --- |
| `131055`, `134100` | Only Marketing templates are accepted. | Send a template whose category is `MARKETING`. |
| `134101` | The template is still syncing. | Wait about 10 minutes after creating the template, then send again. |
| `134102` | The template cannot be used, or the account is not onboarded. | Read the marketing status. Accept the terms in WhatsApp Manager when the account is not onboarded. If it is onboarded and the error persists, contact Meta support. |
| `131062` | The template uses dynamic pricing (`bid_spec`) with a business-scoped user ID. | Send to the person's phone number, or use a template without `bid_spec`. |

Two failures arrive later, as a `failed` status in your webhooks:

- `131049`: WhatsApp withheld the message under the per-user marketing limit.
  Wait at least 24 hours before sending this person another marketing message.
  Repeated attempts can block delivery to them for up to 24 hours.
- `131050`: the person stopped marketing messages from your business. Do not
  send them marketing messages again unless they resume.

See [Meta's error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
for the full list.

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body

- `messaging_product` (string, required). Messaging product associated with this Graph API object. Values: `whatsapp`.
- `recipient_type` (string, required). Category assigned to recipient. Values: `individual`.
- `to` (string, required, min length 1). Specifies to for this graph graph marketing send request.
- `type` (string, required). Type discriminator for this object. Values: `template`.
- `template` (object, required). Structured template values for this graph graph marketing send request.
  - `name` (string, required, min length 1). Human-readable name for this resource.
  - `language` (object, required). Language or locale code used for this content.
    - `policy` (string, required). Specifies policy for this language. Values: `deterministic`.
    - `code` (string, required, min length 1). Stable machine-readable code for this result.
  - `components` (array of object, max items 1000). Structured components that make up this message or template.
    - One of:
      - `header` (object).
        - `type` (string, required). Type discriminator for this object. Values: `header`.
        - `parameters` (array of object, required, items 1–1000). Parameters associated with this any of.
          - One of:
            - `text` (object).
            - `location` (object).
            - `image` (object).
            - `video` (object).
            - `document` (object).
      - `body` (object).
        - `type` (string, required). Type discriminator for this object. Values: `body`.
        - `parameters` (array of object, required, max items 1000). Parameters associated with this any of.
          - One of:
            - `text` (object).
            - `currency` (object).
            - `date_time` (object).
      - `Option 3` (object).
        - `type` (string, required). Type discriminator for this object. Values: `button`.
        - `sub_type` (string, required). Category assigned to sub. Values: `quick_reply`.
        - `index` (string or integer, required). Specifies index for this any of.
          - Accepts one of:
            - string, `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` or `9`
            - integer, range 0–9
        - `parameters` (array of object, required, items 1–1000). Parameters associated with this any of.
          - `type` (string, required). Type discriminator for this object. Values: `payload`.
          - `payload` (string, required). Structured payload carried by this event or operation.
      - `Option 4` (object).
        - `type` (string, required). Type discriminator for this object. Values: `button`.
        - `sub_type` (string, required). Category assigned to sub. Values: `url`.
        - `index` (string or integer, required). Specifies index for this any of.
          - Accepts one of:
            - string, `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` or `9`
            - integer, range 0–9
        - `parameters` (array of object, required, items 1–1000). Parameters associated with this any of.
          - `type` (string, required). Type discriminator for this object. Values: `text`.
          - `text` (string, required). Text content carried by this object.
      - `Option 5` (object).
        - `type` (string, required). Type discriminator for this object. Values: `button`.
        - `sub_type` (string, required). Category assigned to sub. Values: `catalog`, `CATALOG`.
        - `index` (string or integer, required). Specifies index for this any of.
          - Accepts one of:
            - string, `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` or `9`
            - integer, range 0–9
        - `parameters` (array of object, required, items 1–1000). Parameters associated with this any of.
          - `type` (string, required). Type discriminator for this object. Values: `action`.
          - `action` (object, required). Action represented by this parameter.
      - `Option 6` (object).
        - `type` (string, required). Type discriminator for this object. Values: `button`.
        - `sub_type` (string, required). Category assigned to sub. Values: `copy_code`.
        - `index` (string or integer, required). Specifies index for this any of.
          - Accepts one of:
            - string, `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` or `9`
            - integer, range 0–9
        - `parameters` (array of object, required, items 1–1000). Parameters associated with this any of.
          - `type` (string, required). Type discriminator for this object. Values: `coupon_code`.
          - `coupon_code` (string, required). Machine-readable coupon code for this parameter.
      - `limited_time_offer` (object).
        - `type` (string, required). Type discriminator for this object. Values: `limited_time_offer`.
        - `parameters` (array of object, required, items 1). Parameters associated with this any of.
          - `type` (string, required). Type discriminator for this object. Values: `limited_time_offer`.
          - `limited_time_offer` (object, required). Limited-time offer values for this parameter.
      - `carousel` (object).
        - `type` (string, required). Type discriminator for this object. Values: `carousel`.
        - `cards` (array of object, required, items 1–10). Cards associated with this any of.
          - `card_index` (integer, required, range 0–9). Specifies card index for this card.
          - `components` (array of one of, required, max items 1000). Structured components that make up this message or template.
- `product_policy` (string, required). Specifies product policy for this graph graph marketing send request. Values: `STRICT`.
- `message_activity_sharing` (boolean). Whether message activity sharing.

### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/marketing_messages" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "string",
  "type": "template",
  "template": {
    "name": "string",
    "language": {
      "policy": "deterministic",
      "code": "string"
    }
  },
  "product_policy": "STRICT"
}'
```

### Responses

#### 200

Meta's response to the marketing message request

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
null
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Get marketing status

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{wabaId}/marketing_messages/status` (Graph API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

**Required scope:** `sessions:read`

Reads Meta's documented Marketing Messages fields for a WABA through a project-owned Official API Number: the WABA onboarding status, the business portfolio's terms of service state and the Cloud API marketing setting. Values are Meta's, unchanged. Terms are accepted in WhatsApp Manager, not through the API. This is a Polymorfa WABA-scoped path, not a Meta edge.

Use a WABA ID from an Official API Number in your project and a credential with
`sessions:read`. The route rejects simulated Numbers and does not accept query
parameters. It returns these WhatsApp fields, unchanged, when WhatsApp provides
them:

| Field | Values |
| --- | --- |
| `marketing_messages_onboarding_status` | `ELIGIBLE`: the account can onboard to Marketing Messages. `ONBOARDED`: onboarding is complete. Other values pass through as sent. |
| `owner_business_info.marketing_messages_onboarding_status` | `status` is the business portfolio's terms of service state: `TERM_OF_SERVICE_SIGNED`, `REQUEST_SENT` or `NOT_STARTED`. `time` is the date WhatsApp reports. Other business details are not returned. |
| `disable_marketing_messages_on_cloud_api` | `true` when the account refuses Marketing templates on the Cloud API `/messages` endpoint (error `131063`). |

The route no longer requests `marketing_messages_lite_api_status`, which Meta
retired in Graph API v24.0.

## Accept the terms in WhatsApp Manager

No API accepts the Marketing Messages terms. Someone with full control of the
business portfolio opens WhatsApp Manager, goes to **Overview**, and selects
**Accept terms** in the Alerts section. See
[Meta's onboarding guide](https://developers.facebook.com/documentation/business-messaging/whatsapp/marketing-messages/onboarding#onboarding-business-customers).
After the terms are signed, WhatsApp sends an `account_update` notification
with `event: "MM_LITE_TERMS_SIGNED"` to your Meta-format webhooks.

These values describe the account when you read them. WhatsApp still decides
each send, and it can refuse a send despite a status returned here.

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `wabaId` (string, required). Identifier for the waba.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/marketing_messages/status" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Meta's marketing status fields
- `id` (string, required). WhatsApp Business Account ID.
- `marketing_messages_onboarding_status` (string). Meta's Marketing Messages onboarding status for the WABA, unchanged. Meta documents `ELIGIBLE` (the WABA can onboard) and `ONBOARDED` (onboarding is complete). Any other value is passed through as Meta sent it.
- `owner_business_info` (object). Only the portfolio's Marketing Messages terms state. Other business details are not returned.
  - `marketing_messages_onboarding_status` (object, required). Structured marketing messages onboarding status values for this owner business info.
    - `status` (string, required). Terms of service state of the business portfolio: `TERM_OF_SERVICE_SIGNED`, `REQUEST_SENT` or `NOT_STARTED`.
    - `time` (string). Date Meta reports for the state.
- `disable_marketing_messages_on_cloud_api` (boolean). True when the WABA refuses Marketing templates on the Cloud API `/messages` endpoint (error `131063`).

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "id": "string"
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```
