Skip to content
Shortcut: /, ⌘K or Ctrl+K

Marketing

View as Markdown

Send a marketing message

POST/graph/whatsapp/{version}/{phoneNumberId}/marketing_messagesGraph APIMeta Cloud API
Base URL
https://api.polymorfa.com
Required permission
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 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:

CodeMeaningRecovery
131055, 134100Only Marketing templates are accepted.Send a template whose category is MARKETING.
134101The template is still syncing.Wait about 10 minutes after creating the template, then send again.
134102The 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.
131062The 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 for the full list.

Path parameters

  • versionstringrequired

    Specifies version for this path parameter.

  • phoneNumberIdstringrequired

    Identifier for the phone number.

Body

  • messaging_productstringrequired

    Messaging product associated with this Graph API object.

    Allowed valueswhatsapp
  • recipient_typestringrequired

    Category assigned to recipient.

    Allowed valuesindividual
  • tostringrequiredmin length1

    Specifies to for this graph graph marketing send request.

  • typestringrequired

    Type discriminator for this object.

    Allowed valuestemplate
  • templateobjectrequired

    Structured template values for this graph graph marketing send request.

    Show 3 child fields
  • product_policystringrequired

    Specifies product policy for this graph graph marketing send request.

    Allowed valuesSTRICT
  • message_activity_sharingboolean

    Whether message activity sharing.

Responses

POST /graph/whatsapp/{version}/{phoneNumberId}/marketing_messagescURL

Graph API v26.0. The version is part of the URL; Graph requests take no Polymorfa-Version header.

curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/marketing_messages" \
  -H "Authorization: Bearer YOUR_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"
}'
Response
null

Get marketing status

GET/graph/whatsapp/{version}/{wabaId}/marketing_messages/statusGraph APIMeta Cloud API
Base URL
https://api.polymorfa.com
Required permission
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:

FieldValues
marketing_messages_onboarding_statusELIGIBLE: the account can onboard to Marketing Messages. ONBOARDED: onboarding is complete. Other values pass through as sent.
owner_business_info.marketing_messages_onboarding_statusstatus 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_apitrue 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. 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

  • versionstringrequired

    Specifies version for this path parameter.

  • wabaIdstringrequired

    Identifier for the waba.

Responses

  • 200Meta's marketing status fields
    • idstringrequired

      WhatsApp Business Account ID.

    • marketing_messages_onboarding_statusstring

      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_infoobject

      Only the portfolio's Marketing Messages terms state. Other business details are not returned.

      Show 1 child field
    • disable_marketing_messages_on_cloud_apiboolean

      True when the WABA refuses Marketing templates on the Cloud API /messages endpoint (error 131063).

    Show 3 headers
  • 400Bad request
  • 401Unauthenticated
  • 403Permission error
  • 404Object does not exist
  • 429Rate limited
  • 500Internal error
GET /graph/whatsapp/{version}/{wabaId}/marketing_messages/statuscURL

Graph API v26.0. The version is part of the URL; Graph requests take no Polymorfa-Version header.

curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<wabaId>/marketing_messages/status" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "id": "string"
}