Marketing
Send a marketing message
- 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:
{
"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:
{
"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:
| 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 for the full list.
Path parameters
versionstringrequiredSpecifies version for this path parameter.
phoneNumberIdstringrequiredIdentifier for the phone number.
Body
messaging_productstringrequiredMessaging product associated with this Graph API object.
Allowed valueswhatsapprecipient_typestringrequiredCategory assigned to recipient.
Allowed valuesindividualtostringrequiredmin length1Specifies to for this graph graph marketing send request.
typestringrequiredType discriminator for this object.
Allowed valuestemplatetemplateobjectrequiredStructured template values for this graph graph marketing send request.
Show 3 child fields
product_policystringrequiredSpecifies product policy for this graph graph marketing send request.
Allowed valuesSTRICTmessage_activity_sharingbooleanWhether message activity sharing.
Responses
200Meta's response to the marketing message request
Show 3 headers
400Bad request
401Unauthenticated
403Permission error
404Object does not exist
429Rate limited
500Internal error
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"
}'nullGet marketing status
- 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:
| 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. 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
versionstringrequiredSpecifies version for this path parameter.
wabaIdstringrequiredIdentifier for the waba.
Responses
200Meta's marketing status fields
idstringrequiredWhatsApp Business Account ID.
marketing_messages_onboarding_statusstringMeta's Marketing Messages onboarding status for the WABA, unchanged. Meta documents
ELIGIBLE(the WABA can onboard) andONBOARDED(onboarding is complete). Any other value is passed through as Meta sent it.owner_business_infoobjectOnly the portfolio's Marketing Messages terms state. Other business details are not returned.
Show 1 child field
disable_marketing_messages_on_cloud_apibooleanTrue when the WABA refuses Marketing templates on the Cloud API
/messagesendpoint (error131063).
Show 3 headers
400Bad request
401Unauthenticated
403Permission error
404Object does not exist
429Rate limited
500Internal error
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"{
"id": "string"
}