Technical details for MM API

You can obtain all the details for the MM API implementation

Details about the Fallback Mechanism

What is it?

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.

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 check this section here.

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

How Template Message Routing Works: Automatic Fallback Between APIs

Our /messages API (the default entry point for sending messages) supports smart routing of template messages between two backend services:

• primary path - the optimized API for marketing messages (/marketing_messages)

• fallback path - the classic Cloud API (used by default for all non-marketing messages and in case of failures)

This logic is completely transparent to the client: you send a request to /messages, and the system automatically decides which path to use - based on the template type, configuration, and current availability of services.

---

Overall Request Processing Flow

1. Configuration check

The system first determines whether routing to the marketing API is enabled for the given stack. If it’s disabled, the request goes directly to the Cloud API.

2. Determining the message type

If the message is not a template (e.g., a simple text message), it always goes through the Cloud API - regardless of any routing settings.

3. Determining the template category

For template messages, the system tries to determine whether the template belongs to the marketing category.

This is done using cached template information (including data learned during earlier requests).

There are three possible outcomes:

• the template is known to be marketing -> the request is sent directly to /marketing_messages

• the template is known to be non-marketing -> the request is sent to the Cloud API

• the category is unknown (or the cache is unavailable) → the system triggers “checked routing” with fallback

---

Fallback: How “Checked Routing” Works

When the template category is unknown, the system:

1. first attempts to send the message through /marketing_messages

2. internally intercepts the HTTP response without proxying it to the client

3. analyzes the result:

4. if the response is successful (HTTP 2xx): caches that the template is marketing and returns the original response to the client Cache TTL: 1 hour

5. if the response is unsuccessful (4xx/5xx, etc.): caches that the template is non-marketing and retries the request via the Cloud API. The client receives the response from the Cloud API.

Important:

Regardless of the outcome, the client receives exactly one HTTP response.

---

Benefits

• Faster for marketing use cases: /marketing_messages is optimized for high throughput and low latency

• Resilient: if the new API is temporarily unavailable or rejects the request, the system automatically falls back to the Cloud API

• Self-learning logic: after the first request for any template, its category is cached - so subsequent requests require no intermediate checks

• Transparent for the client: no need to change integration logic - continue using /messages as before

---

Limitations and Caveats

• The first request for a new template may be slower: in the worst case, it may require two round-trips (new API + old API). For critical cases, you may want to “warm up” the cache in advance

• The cache may lag behind Meta’s current template classification: if Meta reclassifies a template (e.g., marketing → utility) on the fly, the system will detect it only after the next failed attempt. Cache TTL: 1 hour

• You cannot guarantee which API will be used: if you require strict auditing or full control over the delivery path, use /marketing_messages directly (marketing templates only)

• Fallback does not apply to non-template messages: regular messages always use the Cloud API - this is expected and stable behavior

---

Recommendations for Integrators

• For most use cases - continue using /messages. The system will automatically choose the optimal path

• If you are certain the template is marketing and want full control - call /marketing_messages directly

• To test fallback behavior - you can temporarily disable routing (opt-out) at the stack level

---

Webhooks

Available Message Status Webhooks

Our platform utilizes the three core webhook event types available in the WhatsApp Business Cloud API, with one specific modification for marketing messages and the addition of a click event.

Webhook Event	Purpose	Details & Modifications
Sent	Indicates the message has been sent from our system.	Includes the value marketing_lite within the event payload to specifically identify that the message originated via the MM API (Marketing Messaging API).
Delivered	Indicates the message has been successfully delivered to the user’s device.	Same as above.
Read	Indicates the user has read the message.	Same as above.
Click	Additional Event	This specific event is triggered when a user clicks on a tracked link within the message content.

Explanation of the marketing_lite value

To help partners distinguish between standard operational traffic and messages sent via the Marketing Messaging (MM) API, the payload for the sent, delivered, and read status webhooks contains the specific value marketing_lite in the pricing.category field.

This value allows you to filter, route, and analyze MM API traffic separately within your application logic.