Events

In addition to sending messages, you can also send various event notifications through our platform. Events allow you to perform specific actions, such as updating message statuses or reacting to user interactions, by communicating with our services. Events are processed in a similar way to messages but are distinguished by their type and purpose.

📘

API endpoint

To send events, use the events specific endpoint: https://gw.messaging.cm.com/v1.0/event

To send an event, ensure your request follows this structure:

{
    "channel": "WhatsApp",
    "event": {
        "custom": {
            "key": "value"
        },
        "type": "EventTypeHere"
    },
    "from": {
        "number": "00316098765432"
    },
    "to": {
        "number": "00316012345678"
    }
}

The event object contains a type field specifying the event type you wish to send. Events might include updating a message's status or responding to user interactions. You can also include custom attributes within the custom object to provide any event-specific information.

Mark as Read

The Mark as Read event lets you update the status of a message to indicate that it has been read. This is useful for synchronizing message status between your application and WhatsApp.
Here’s an example request for a Mark as Read event:

{
    "channel": "WhatsApp",
    "event": {
        "custom": {
            "message_id": "wamid.HBgLMzQ2ODUxMjA0NzMVAgASGBYzRUIwOTE5OURCMjdDQ0RCNjM3OTBEAA==" //This ID refers to the supplier ticket received through the MO Webhook for the MO message you want to mark as read.
        },
        "type": "MarkAsRead"
    },
    "from": {
        "number": "00316098765432"
    },
    "to": {
        "number": "00316012345678"
    }
}

In this request:

• The type field specifies the MarkAsRead event type.
• The custom object contains the message_id of the message you want to mark as read.

By sending this event, the specified message's status will be updated to reflect it has been read by the recipient.

Block

The Block event lets you block end users. When you block a WhatsApp user, the following happens:

• The user cannot contact your business or see that you are online.
• Your business cannot message the user. If you do, you will encounter an error.

📘

Limitations

You can only block users that have messaged your business in the last 24 hours.

Here’s an example request for a Block event:

{
    "channel": "WhatsApp",
    "event": {
        "type": "Block"
    },
    "from": {
        //Your bussiness phone number
        "number": "00316098765432"
    },
    "to": {
        //The phone number you want to block
        "number": "00316012345678"
    }
}

UnBlock

The UnBlock event lets you unblock end users. When you unblock a WhatsApp user, the following happens:

• The user can contact your business and see that you are online.
• Your business can message the user again.

Here’s an example request for an UnBlock event:

{
    "channel": "WhatsApp",
    "event": {
        "type": "UnBlock"
    },
    "from": {
        //Your bussiness phone number
        "number": "00316098765432"
    },
    "to": {
        //The phone number you want to block
        "number": "00316012345678"
    }
}

Meta Conversions

With the Meta Conversions API you can send conversion events to Meta. These events help you track and analyze the performance of your ads that drive traffic to WhatsApp, enabling you to optimize your campaigns and achieve better results for your business.

📘

Note

Please note that this feature is only available if you are based outside the UK, Japan and the European Union.

The following types are allowed as type of event for Meta Conversions event. This is the list of allowed types:

• Purchase
• LeadSubmitted
• InitiateCheckout
• AddToCart
• ViewContent
• OrderCreated
• OrderShipped
• OrderDelivered
• OrderCanceled
• OrderReturned
• CartAbandoned
• QualifiedLead
• RatingProvided
• ReviewProvided

Here's an example request for a Meta Conversions event:

{
    "authentication": {
            "productToken": "your product token"
        },
    "from": {
				//your business phone number
        "number": "00316098765432"
    },
    "to": {
        "number": "00316012345678"
    },
  "event": {
				//type of event, check the list of allowed events
        "type": "ViewContent",
        "custom": {
            "ctwa_id":"your ctwa_id identifier for the ad your customer clicked on to start a conversation on WhatsApp"
        }
    },
    "channel": "WhatsApp"
}

For guidance on knowing where to get the value of the property ctwa_clid, refer to the documentation example here.

🚧

Warning

For Purchase, OrderCreated and OrderShipped event type is mandatory to add the currency and the value inside the custom object.

Here's an example request for these events with currency and value properties:

{
    "authentication": {
        "productToken": "your product token"
    },
    "from": {
        //your business phone number
        "number": "00316098765432"
    },
    "to": {
        "number": "00316012345678"
    },
    "event": {
        //type of event, check the list of allowed events
        "type": "Purchase",
        "custom": {
            "ctwa_id": "your ctwa_id identifier for the ad your customer clicked on to start a conversation on WhatsApp",
            "currency": "USD", //the currency for purchase, i.e: USD, EUR, AUD
            "value": "12.60" //the total amount of the order
        }
    },
    "channel": "WhatsApp"
}

Typing Indicator

The Typing event allows you to notify the consumer that you are actively preparing a response to their previous message. This feature helps create a more engaging and transparent communication experience by signaling that their message has been read and a reply is in progress.

When triggering the Typing event, you include the message_id of the consumer's message you are responding to. This ensures that the consumer is informed that their specific message has been read and that you are working on a reply. The typing indicator will appear to the consumer as a visual cue that a response is being prepared.

Here’s an example request for a Typing event:

{
    "authentication": {
        "productToken": "your product token"
    },
    "channel": "WhatsApp",
    "event": {
        "custom": {
            "message_id": "wamid.HBgLMzQ2ODUxMjA0NzMVAgASGBYzRUIwOTE5OURCMjdDQ0RCNjM3OTBEAA==", //This ID refers to the supplier ticket received via the MO Webhook for the MO message you want to display a typing indicator for.
            "typing_indicator": "text" //mandatory, this indicates that your are typing a message
        },
        "type": "Typing"
    },
    "from": {
        "number": "00316098765432"
    },
    "to": {
        "number": "00316012345678"
    }
}

Once the Typing event is sent, the status of the consumer's previous message will update to reflect that it has been read. As a best practice, you should send your response shortly after triggering the typing indicator. The indicator will automatically disappear either when your response is sent or after 25 seconds, whichever comes first.

It’s important to use the Typing event only when you are actively preparing a response. Avoid triggering this event if no reply will be provided, as this could lead to confusion or frustration for the consumer.