ePrivacy and GPDR Cookie Consent by Cookie Consent Skip to main content

WhatsApp Campaign Delivery Flow and System Events

Once your WhatsApp channel is integrated and active, Meiro automatically logs key system events associated with WhatsApp communication. These events provide valuable insights into message delivery status, user behavior, and subscription management.

Message Delivery Flow

Every WhatsApp message goes through several stages of delivery. Understanding these helps you interpret events and delivery metrics correctly.

  1. Sent – Meiro successfully hands off the message to the WhatsApp Business API.

  2. Delivered – The message reaches the recipient’s device.

  3. Seen – The recipient opens or views the message.

  4. Undelivered – The message could not reach the recipient (invalid number, opt-out, malformed templates, etc.).

  5. Blocked – The recipient’s number cannot receive WhatsApp messages (invalid, blacklisted, or not registered).

Each stage generates a corresponding Meiro WhatsApp event, which can be found in Data Library → Events → Meiro WhatsApp.

Available WhatsApp System Events

WhatsApp Campaign Sent

The event WhatsApp Campaign Sent is triggered when a campaign message is successfully sent through the WhatsApp channel to the recipient’s phone number.

Event Type: wa_campaign_sent
Autoload: Enabled
Retention: Not set by default, but can be customized.

This event is useful for tracking outbound message activity, monitoring send performance, and initiating subsequent actions or workflows within Meiro.

Example Payload:

{
    "activation_id": number, // required, ID of the activation (campaign execution)
    "campaign": { // required object
        "id": "uuid", // required string, unique campaign ID
        "name": "string" // required string, campaign name
    },
    "event_time": "datetime", // required string, ISO 8601 timestamp when the message was sent
    "message_id": "string", // required string, unique identifier of the message
    "phone_number": "string", // required string, recipient's phone number in E.164 format
    "sender": { // required object
        "id": "string", // required string, WhatsApp Business Account ID
        "name": "string" // required string, display name of the sender
    },
    "type": "wa_campaign_sent", // required string, fixed value for this event type
    "wa_template_params": { // optional object
        "body_params": [ "string" ], // optional array, parameters used in the message body
        "button_params": [ [ "string" ] ], // optional array, nested parameters for buttons
        "header_params": [ "string" ] // optional array, parameters for header, if used
    }
}

Event example:

{
  "activation_id": 0,
  "campaign": {
    "id": "d4af8c2b-f80b-47a2-920f-6daca191609d",
    "name": "Milestone Celebration Message"
  },
  "event_time": "2025-08-13T15:22:39Z",
  "message_id": "6e74de07-8b37-4bfb-9863-9e59b3d59ae5-0",
  "phone_number": "+420792775888",
  "sender": {
    "id": "677802452089546",
    "name": "test"
  },
  "type": "wa_campaign_sent",
  "wa_template_params": {
    "body_params": [
      "{{mx_lifetime_amount_spent}}"
    ],
    "button_params": [
      {
        "url": "de0997bc13b613709a58b8f70987a756"
      }
    ],
    "header_params": [
      {
        "text": "Tonya Griffin"
      }
    ]
  }
}

WhatsApp Campaign Seen

The event WhatsApp Campaign Seen is triggered when the recipient opens or views a WhatsApp message sent through a campaign. This helps measure actual visibility and user engagement beyond delivery.

Event Type: wa_campaign_seen
Autoload: Enabled
Retention: Not set by default, but can be customized.

Use this event to analyze message view rates and to define engagement-based audience segments.

Event Structure:

{
    "activation_id": number, // required, ID of the activation (campaign execution)
    "campaign": { // required object
        "id": "uuid", // required string, unique campaign ID
        "name": "string" // required string, campaign name
    },
    "event_time": "datetime", // required string, ISO 8601 timestamp when the message was seen
    "message_id": "string", // required string, unique identifier of the message
    "phone_number": "string", // required string, recipient's phone number in E.164 format
    "sender": { // required object
        "id": "string", // required string, WhatsApp Business Account ID
        "name": "string" // required string, display name of the sender
    },
    "type": "wa_campaign_seen", // required string, fixed value for this event type
    "wa_template_params": { // optional object
        "body_params": [ "string" ], // optional array, parameters used in the message body
        "button_params": [ { "url": "string" } ], // optional array, button parameters (e.g. URLs)
        "header_params": [ { "text": "string" } ] // optional array, header parameters if used
    }
}

Event Example:

{
  "activation_id": 0,
  "campaign": {
    "id": "d4af8c2b-f80b-47a2-920f-6daca191609d",
    "name": "Milestone Celebration Message"
  },
  "event_time": "2025-08-13T15:23:08Z",
  "message_id": "6e74de07-8b37-4bfb-9863-9e59b3d59ae5-0",
  "phone_number": "+420792775888",
  "sender": {
    "id": "677802452089546",
    "name": "test"
  },
  "type": "wa_campaign_seen",
  "wa_template_params": {
    "body_params": [
      "{{mx_lifetime_amount_spent}}"
    ],
    "button_params": [
      {
        "url": "de0997bc13b613709a58b8f70987a756"
      }
    ],
    "header_params": [
      {
        "text": "Tonya Griffin"
      }
    ]
  }
}

Learn more: See Notes & Limitations on “Seen” Status Reporting to understand why some messages may not generate a wa_campaign_seen event.

WhatsApp Campaign Delivered

The event WhatsApp Campaign Delivered is triggered when a message sent via the WhatsApp channel is successfully delivered to the recipient's phone number.

Event Type: wa_campaign_delivered
Autoload: Enabled
Retention: Not set by default, but can be customized.

This event is useful for tracking delivery performance, analyzing engagement, and triggering follow-up actions in Meiro.

Event structure:

{
    "activation_id": number, // required, ID of the activation (campaign execution)
    "campaign": { // required object
        "id": "uuid", // required string, unique campaign ID
        "name": "string" // required string, campaign name
    },
    "event_time": "datetime", // required string, ISO 8601 timestamp when the message was delivered
    "message_id": "string", // required string, unique identifier of the message
    "phone_number": "string", // required string, recipient's phone number in E.164 format
    "sender": { // required object
        "id": "string", // required string, WhatsApp Business Account ID
        "name": "string" // required string, display name of the sender
    },
    "type": "wa_campaign_delivered", // required string, fixed value for this event type
    "wa_template_params": { // optional object
        "body_params": [ "string" ], // optional array, parameters used in the message body
        "button_params": [ [ "string" ] ], // optional array, nested parameters for buttons
        "header_params": [ "string" ] // optional array or null, parameters for header if used
    }
}

Event example:

{
  "activation_id": 1140,
  "campaign": {
    "id": "29048819-6ca1-4f7e-9bff-c12742909f68",
    "name": "default test"
  },
  "event_time": "2025-07-24T07:05:05Z",
  "message_id": "c6686bfa-3b49-4c32-b158-c224c9ebf9e7-0",
  "phone_number": "+420792775888",
  "sender": {
    "id": "668858762973438",
    "name": "MeiroQA"
  },
  "type": "wa_campaign_delivered",
  "wa_template_params": {
    "body_params": [
      "{{customer_db_name | default: \"there\"}}"
    ],
    "button_params": [
      [
        "{{customer_db_name | default: \"there\"}}"
      ]
    ],
    "header_params": null
  }
}

WhatsApp Campaign Undelivered

The event WhatsApp Campaign Undelivered is logged when a campaign message fails to reach the recipient via the WhatsApp channel. This can occur due to issues like invalid numbers, user opt-outs, or malformed templates.

Event Type: wa_campaign_undelivered
Autoload: Enabled
Retention: Not set by default, but can be customized.

Use this event to monitor delivery failures and troubleshoot issues such as formatting errors or compliance rejections from WhatsApp.

Event Structure:

{
    "activation_id": number, // required, ID of the activation (campaign execution)
    "campaign": { // required object
        "id": "uuid", // required string, unique campaign ID
        "name": "string" // required string, campaign name
    },
    "event_time": "datetime", // required string, ISO 8601 timestamp when the delivery failure occurred
    "message_id": "string", // required string, unique identifier of the message
    "phone_number": "string", // required string, recipient's phone number in E.164 format
    "reason": "string", // required string, reason for the undelivered status (e.g., "[100] Invalid parameter")
    "sender": { // required object
        "id": "string", // required string, WhatsApp Business Account ID
        "name": "string" // required string, display name of the sender
    },
    "type": "wa_campaign_undelivered", // required string, fixed value for this event type
    "wa_template_params": { // optional object
        "body_params": [ "string" ], // optional array, parameters used in the message body
        "button_params": [ array|null ], // optional array, button parameters (e.g., URLs) or null if not used
        "header_params": [ "string" ] // optional array, header parameters if used
    }
}

Event Example:

{
  "activation_id": 18,
  "campaign": {
    "id": "f1b8e7b3-4c78-4326-9e43-a9274e2ec9f3",
    "name": "WA-63_2"
  },
  "event_time": "2025-07-24T12:25:31Z",
  "message_id": "654d1363-322f-4763-9941-73005e471bed-0",
  "phone_number": "+420792775888",
  "reason": "[100] Invalid parameter",
  "sender": {
    "id": "668858762973438",
    "name": "test"
  },
  "type": "wa_campaign_undelivered",
  "wa_template_params": {
    "body_params": [
      "{{mx_geo_country}}",
      "{{mw_undelivered_comp_last.campaign_name | default: \"default value\"}}"
    ],
    "button_params": [
      null,
      [
        "{{mx_geo_city}}"
      ]
    ],
    "header_params": [
      "{{bank_cs_survey_response.date}}"
    ]
  }
}
Undelivered or Failed Messages

When a WhatsApp message cannot reach the recipient, Meiro logs a WhatsApp Campaign Undelivered event. This event helps you identify delivery issues and understand why certain messages failed.

Common reasons why messages are undelivered:

  • The recipient’s phone number is invalid or incorrectly formatted.

  • The recipient is not registered on WhatsApp (the number does not have an active WhatsApp account).

  • The message template contains an error, such as:

    • Missing required parameters (e.g., a placeholder like {{name}} is empty).

    • The translated text or template header exceeds the allowed length.

    • Invalid or mismatched personalization parameters.

  • Temporary or network-related errors at the provider level.

These events help you monitor delivery issues, understand campaign performance, and identify data that needs cleanup.

WhatsApp Error & Reason Codes

Reason codes explain why a message failed. Here are common ones and what they mean:

Code Meaning Recommended Action
131026 Recipient not registered on WhatsApp Meiro automatically blocks this number for the WhatsApp channel. No further messages will be sent unless manually unblocked.
132005 Translated text too long Shorten your template header or body text — combined parameter and text length exceeds WhatsApp limits.
131008 Required parameter is missing Check your message template — make sure all placeholders (e.g. {{name}}) have valid values.
100 Invalid parameter Verify that personalization fields and dynamic values match your approved template structure.
13002 Invalid number format Check and correct the phone number format to match E.164 standard (e.g. +420123456789).
10001 Temporary network or timeout Try resending later or verify connection with your WhatsApp Business provider.

WhatsApp Subscribed

The event WhatsApp Subscribed is triggered when a user opts in to receive messages via the WhatsApp channel. This typically happens through sources such as website modals, sign-up forms, or other touchpoints where users give explicit consent.

Event Type: wa_subscribed
Autoload: Enabled
Retention: Not set by default, but can be customized.

This event is critical for maintaining compliance with WhatsApp opt-in policies and tracking when users become eligible for communication via the channel.

Event Structure:

{
    "event_time": "datetime", // required string, ISO 8601 timestamp when the user opted in
    "phone_number": "string", // required string, recipient's phone number in E.164 format
    "subscription_source": "string", // required string, source of the opt-in (e.g., "website modal", "form signup")
    "type": "wa_subscribed" // required string, fixed value for this event type
}

Event Example:

{
  "event_time": "2025-08-13T11:44:38.205Z",
  "phone_number": "+420792775888",
  "subscription_source": "website modal",
  "type": "wa_subscribed"
}

WhatsApp Unsubscribed

The WhatsApp Unsubscribed event is triggered when a user opts out of receiving WhatsApp messages. This typically happens through user-initiated actions, such as replying with "unsubscribe" or clicking an opt-out button.

Event Type: wa_unsubscribed
Autoload: Enabled
Retention: Not set by default, but can be customized.

This event is essential for managing user preferences and respecting consent across your WhatsApp communications.

Event Structure:

{
    "campaign": { // required object, campaign details
        "id": "string", // required string, campaign ID (UUID)
        "name": "string" // required string, campaign name
    },
    "event_time": "datetime", // required string, ISO 8601 timestamp when the unsubscribe occurred
    "message_id": "string", // required string, unique message identifier
    "phone_number": "string", // required string, recipient's phone number in E.164 format
    "sender": { // required object, WhatsApp Business Account details
        "id": "string", // required string, sender (WABA) ID
        "name": "string" // required string, sender display name
    },
    "type": "wa_unsubscribed", // required string, fixed value for this event type
    "unsubscribe_source": "string", // required string, how the user unsubscribed (e.g., "WA reply: unsubscribe", "link")
    "wa_template_params": { // optional object, contains personalized parameters used in the template
        "body_params": [ "string" ], // optional array of strings, parameters used in the message body
        "button_params": [ array|null ], // optional array or null, button-related parameters
        "header_params": [ "string" ] // optional array of strings, parameters used in the header
    }
}

Event Example:

{
  "campaign": {
    "id": "d7144b2e-e213-4a61-ac00-799bd1dcec53",
    "name": "Test campaign"
  },
  "event_time": "2025-07-24T13:02:46Z",
  "message_id": "3caed9a5-c39a-4da8-88b0-1b0e3cf785bb-0",
  "phone_number": "+420792775888",
  "sender": {
    "id": "668858762973438",
    "name": "MeiroQA"
  },
  "type": "wa_unsubscribed",
  "unsubscribe_source": "WA reply: unsubscribe",
  "wa_template_params": {
    "body_params": [
      "wow {{customer_db_name}} hello"
    ],
    "button_params": [
      null
    ],
    "header_params": [
      "lads"
    ]
  }
}

WhatsApp Subscription Imported

The event WhatsApp Subscription Imported is triggered when consent or block status for a phone number in the WhatsApp channel is updated based on imported data.

Event Type: wa_subscription_import
Retention: Not set by default, but can be customized.

This event is useful for bulk updating subscription statuses in Meiro, such as during initial data migration or regular synchronization with external systems.

Event structure:

{
    "blocked": false, // optional boolean, true if the user has opted out of receiving WhatsApp messages
    "consent": true, // optional boolean, true if the user has given consent to receive messages
    "event_time": "datetime", // required string, ISO 8601 timestamp when the subscription status was updated
    "phone_number": "string", // required string, phone number in E.164 format with '+' prefix
    "type": "wa_subscription_import" // required string, fixed value for this event type
}

Event Example:

{
  "blocked": false,
  "consent": true,
  "event_time": "2025-02-27T11:28:06Z",
  "phone_number": "+48572575811",
  "type": "wa_subscription_import"
}

WhatsApp Blocked

The wa_blocked event is triggered when a message is rejected due to an invalid or blocked number (e.g., [302] Invalid number). This typically means the recipient cannot receive WhatsApp messages, either because the number doesn't exist on WhatsApp or because it's blacklisted.

Event Type: wa_blocked
Retention: Not set by default, but can be customized.
Autoload: Enabled

Event structure:

{
    "activation_id": 0, // required number, ID of the activation (campaign execution)
    "campaign": { // required object
        "id": "string", // required string, UUID of the campaign
        "name": "string" // required string, name of the campaign
    },
    "event_time": "datetime", // required string, ISO 8601 timestamp when the block occurred
    "message_id": "string", // required string, unique identifier of the attempted message
    "phone_number": "string", // required string, phone number in E.164 format with '+' prefix
    "reason": "string", // required string, reason for the block (e.g., "[302] Invalid number")
    "sender": { // required object
        "id": "string", // required string, WhatsApp Business Account ID
        "name": "string" // required string, display name of the sender
    },
    "type": "wa_blocked" // required string, fixed value for this event type
}

Event example:

{
  "activation_id": 28,
  "campaign": {
    "id": "55f6704d-4c29-4b36-8161-31c48e9d34e7",
    "name": "Welcome Campaign"
  },
  "event_time": "2025-07-10T13:41:40Z",
  "message_id": "88f6704d-4c29-4b36-8161-31c48e9d34e7",
  "phone_number": "+4207927758744",
  "reason": "[302] Invalid number",
  "sender": {
    "id": "668858762973438",
    "name": "MeiroQA"
  },
  "type": "wa_blocked"
}
Automatic Blocking for Non-WhatsApp Numbers

When a WhatsApp message cannot be delivered because the recipient’s phone number is not registered on WhatsApp, Meiro automatically maps the undelivered event with reason “Recipient not registered on WhatsApp” (131026) to a WhatsApp Blocked (wa_blocked) event.

This means the number is automatically marked as blocked for the WhatsApp channel, preventing future attempts to send messages to an unreachable recipient.

Once blocked, the number’s WhatsApp channel attribute in the contact profile is set to blocked = true.
Any subsequent WhatsApp campaigns will skip this contact until it is manually unblocked by a user in CDP.

This behavior helps keep your contact data accurate, avoids repeated failed deliveries, and ensures campaign statistics reflect only reachable recipients.

Tip: If a contact later registers on WhatsApp, you can manually unblock them in their CDP profile to resume sending.

Delivery and Troubleshooting

If your campaign shows failed or missing deliveries:

  1. Check undelivered events and note the reason codes.

  2. Verify consent — ensure users are opted in.

  3. Confirm template approval and validity.

  4. Review sending window (late-night or off-hour sends may be blocked).

  5. Inspect blocked numbers — numbers automatically blocked due to reason 131026 will not receive messages.

Where to Find These Events

To view and explore these events:

  • Go to Data Library > Events

  • Use filter Data Source = Meiro WhatsApp

  • Click Show Raw Payload to inspect event structure

wa events.gif

Notes & Limitations on “Seen” Status Reporting

Sometimes, a message sent on WhatsApp may be read by the recipient but still not appear as “seen” in Meiro reports. This behavior is due to how WhatsApp sends status updates for message delivery and reads.

Common scenarios:

  • Delivered skipped → Seen directly
    Suppose the recipient is already in the chat when your message arrives. In that case, WhatsApp may skip the “delivered” status entirely and mark the message as read immediately — without sending all intermediate updates.

  • Multiple unread messages are opened at once
    If the recipient has several unread messages and opens them all together, WhatsApp may send the “seen” update only for the last message in the sequence, skipping earlier ones.

Impact on reporting
Because of these behaviors, the “seen” count in campaign reports might be slightly lower than the actual number of recipients who viewed your message. The message was still read, but WhatsApp did not send the “seen” status update for every individual message.

No Comments
Back to top