Onboarding and Sending Messages

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

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 Partner Hub

To streamline client onboarding, partners will now see a banner in the Partner Hub. This banner contains a unique link that you can easily share with your clients to begin the MM API onboarding process.

Follow the link below:

https://hub.360dialog.com/mmlite-tos

How to use that?

To use the onboarding link, you must copy and share this link with your clients.

Once the client uses the link, they will be prompted to connect to their Facebook account. They 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.

If the user does not have full admin permissions to manage all the client's accounts, the user will need to ask each client to follow the same process described in this step-by-step guideline.

---

Onboarding Confirmation

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

This webhook is the recommended way to track onboarding and eligibility status. Once received, you can safely assume that the WABA is enabled to send messages through the MM API.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<BUSINESS_ID>",
      "time": "<WEBHOOK_TIMESTAMP>",
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "MM_LITE_TERMS_SIGNED",
            "waba_info": {
              "owner_business_id": "<BUSINESS_PORTFOLIO_ID>",
              "waba_id": "<WABA_ID>"
            }
          }
        }
      ]
    }
  ]
}

Notes:

• A webhook can be sent per WABA or once per business (in which case, all WABAs under that business become eligible).

• waba_id indicates which WhatsApp Business Account is now enabled.

• owner_business_id can be used to match the WABA with the correct Business Manager in your system.

• Receiving this webhook means the WABA is ready to send messages via the MM API.

---

Sending Messages with MM API

To send a marketing 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.

If you do not want to implement the new endpoint, please use our fallback system explained here.

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"
        }
    ]
}

Fallback Mechanism

A new option is now available to route marketing messages via the MM API when possible. If a message is ineligible, it will automatically fall back to the Cloud API.

Benefits

• Continue using the standard /messages endpoint.

• All marketing messages submitted through the /messages endpoint will be automatically forwarded to the MM API if the business is currently onboarded with the MM API. This routing logic is handled automatically.

This feature applies to all channels/numbers under your Partner ID when enabled. It is enabled by default for all existing and new numbers.

• To opt out of this feature, please follow the steps below.

• To opt in or out for a specific channel/number, please reach out to our support team.

Messages sent very close to a Meta template recategorization may still pass through the Cloud API until the updated category is reflected in our cache.

The recommended approach to achieve 100% of marketing templates going through the MM API and having a better performance is to use the dedicated MM API endpoint /marketing_messages

For more details, please check this specific section about MM API technical implementation.

How to enable or disable it?

If you want to enable/disable this option, please follow the steps below:

Via Partner Hub UI:

1

Access the partner hub and log in to your account here.

2

Go to the Integration tab

3

Under Integration Settings > Route Marketing via MM API

Via API

PATCH https://hub.360dialog.io/api/v2/partners/{partner_id}/settings/marketing_templates_routing

Request example

curl --request PATCH \
  --url https://hub.360dialog.io/api/v2/partners/{partner_id}/settings/marketing_templates_routing \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "use_marketing_messages_api": true
}'

Path Parameters

Name	Type	Description
partner_id	String	The ID of the partner

Body

Expected outcomes

200: OK

Successful response

400: Wrong Payload

404: Not found

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.

See our documentation on How to set a TTLs for Marketing template messages.

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.

Tracking click events limitations

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

• This feature is not available for all users.

• Click events are only available for messages sent in the last 7 days.

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"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Delivered

Read

Click Event

If you want to obtain more details about the webhook events, please see the Meta doc here.