Onboarding and Sending Messages

This documentation aims to guide you on how to onboard in Meta’s Marketing Messages API.

Marketing Messages API for WhatsApp (formerly known as Marketing Messages API) is now generally available.

In MM API, we call onboarding the process where the client reviews and accepts the MM API Terms of Service. The Onboarding is always performed at a Business Manager level. Please see the next steps to onboard to MM API:

Onboarding Link in the Client Hub

To streamline client onboarding, you will now see a banner in the Client Hub. This banner contains a unique button that you can easily click to begin the MM API onboarding process.

As an alternative, you can also use this link to accept the MM API Terms of Service.

How to do that?

1

To access the onboarding link, log in to your client account here

2

Accept MM API terms button

A banner will appear on the dashboard containing a unique button, "Accept MM API terms". You must click on it.

3

Connect your Facebook account and proceed with the next steps

Once you click there, you will be prompted to connect to your Facebook account. You can then complete the embedded signup process for the MM API.

Important: This step requires the client to be an administrator of the Business Portfolio or Business Manager.

The terms accepted in this process will apply to all existing WhatsApp Business Accounts (WABAs) under the selected Business Manager. Clients with multiple Business Managers must repeat the process for each BM.

Self-Onboard using WhatsApp Manager

What is it?

This is the best way to get access to the MM API feature. In this case, you can use the WhatsApp Business Manager to accept the terms.

How it works

1

Open WhatsApp Manager > Overview

2

In the Alerts section, click 'Accept terms to get started' for Marketing Messages API.

3

Follow the steps to finish signing the MM API Terms of Service for all eligible WABAs in the account.

Once accepted, MM API is active for that Business Manager, meaning all eligible WABAs in the Business Manager will be allowed to use MM API.

Sending Messages with MM API

To send a template message, you will need to use a POST request:

POSThttps://waba-v2.360dialog.io/marketing_messages

The only difference is the endpoint /marketing_messages, and it should be used only for Marketing messages.

Headers

Name	Value	Description
Content-Type	application/json
D360-API-KEY	Bearer <token>	D360-API-KEY received after approval to participate in this program

Body

Field	Required	Description
messaging_product	Yes	"whatsapp"
recipient_type	Yes	"individual"
to	Yes	Recipient phone number in international format. Example: "441234567890"
type	Yes	"template"
template.name	Yes	"marketing_text_no_param"
template.language.code	Yes	"en"
template.language.policy	Yes	"deterministic"
message_activity_sharing	Optional	Set to true to enable activity sharing (can be removed if not needed)
product_policy	Optional	Set to "STRICT" to not route the messages back to Cloud if onboarding requirements have not been met. Set to "cloud_api_fallback" if the routing should be enabled.

Request example

MM API (new)

# MM API (new)
curl --location 'https://https://waba-v2.360dialog.io/marketing_messages' \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: <token>' \
--data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<<RECIPIENT_PHONE_NUMBER>>",
    "type": "template",
    "template": {
        "name": "marketing_text_no_param",
        "language": {
            "policy": "deterministic",
            "code": "en"
        }
    },
    "message_activity_sharing":true ,
    "product_policy": "cloud_api_fallback"
}'

Cloud API (current)

Response

The same response from the Cloud API is expected after a successful message is sent using the MM API.

200: Ok

{
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "<phone number>",
            "wa_id": "<<waba id>"
        }
    ],
    "messages": [
        {
            "id": "wamid.HBgLNTk4OTQ3MTQ0NjMVAgARGBJDNjM1NUM2OEEyMDU4REZERTgA"
        }
    ]
}

Sending a Marketing Template Message with TTL using MM API

MM API provides additional features that are not available to Marketing templates on Cloud API.

This means you can include and set the value of the message_send_ttl_seconds in the payload of your Marketing Message Template to test this feature.

What is Time-To-Live (TTL) for Marketing template messages?

If Meta is unable to deliver a message to a WhatsApp user, they will continue attempting to deliver the message for a period of time known as a time-to-live (TTL), or message validity period.

TTL is available for Authentication and Utility template messages on Cloud API, but TTL for Marketing template messages is exclusively available on Marketing Messages API.

Handling Webhooks

With MM API, you don’t need to change your webhook setup. You will keep receiving the usual events (sent → delivered → read) the same way as with the Cloud API.

The only difference: when you send via /marketing_messages with "message_activity_sharing": true, you also get a click event whenever a user taps the CTA link in your template.

This makes it easier to track performance and optimize campaigns without changing your current logic.

At the moment, it’s not possible to know which phone number clicked. You only get the event itself.

Webhook events received:

Sent

This event includes the value "marketing_lite" to indicate that it was sent using the MM API:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
              "phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
            },
            "statuses": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "status": "sent",
                "timestamp": "TIMESTAMP",
                "recipient_id": "<CUSTOMER_PHONE_NUMBER>",
                "conversation": {
                  "id": "<conversation_id>",
                  "expiration_timestamp": "TIMESTAMP",
                  "origin": {
                    "type": "marketing_lite"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "marketing_lite"
                }
              }
            ]
          },