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": "your message id 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"
}