Onboarding and Sending Messages

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

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

Self-Onboard using WhatsApp Manager

What is it?

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

How it works

Open WhatsApp Manager > Overview

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

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

Onboarding Confirmation

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

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 Lite 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 Lite API.

Sending Messages with MM Lite

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)

Request example

# MM Lite (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
}'

# Cloud API (current)
curl --location 'https://waba-v2.360dialog.io/messages' \
  --header 'D360-API-KEY: <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "<end_client_number>",
    "type": "template",
    "template": {
      "name": "<template_name>",
      "language": { "code": "<template_language_code>" },
      "components": []
    },
    "messaging_product": "whatsapp"
  }'

Response

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

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

Sending a Marketing Template Message with TTL using MM Lite API

MM Lite 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 Lite API.

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

Handling Webhooks

With MM Lite, 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:

This event includes the value "marketing_lite" to indicate that it was sent using the MM Lite 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"
        }
      ]
    }
  ]
}

{
  "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": "delivered",
                "timestamp": "TIMESTAMP",
                "recipient_id": "TIMESTAMP",
                "conversation": {
                  "id": "<conversation_id>",
                  "origin": {
                    "type": "marketing_lite"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "marketing_lite"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

{
  "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": "read",
                "timestamp": "TIMESTAMP",
                "recipient_id": "<CUSTOMER_PHONE_NUMBER>"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

The click event will display a click_id and a tracking_token:

{
  "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"
            },
            "user_actions": [
              {
                "timestamp": "TIMESTAMP",
                "action_type": "marketing_messages_link_click",
                "marketing_messages_link_click_data": {
                  "tracking_token": "<TRACKING_TOKEN>",
                  "click_id": "<CLICK_ID>",
                  "click_component": "CTA"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

PreviousSending Marketing Messages NextExpected Errors & Programming Languages

Last updated 1 hour ago

Was this helpful?