Receive WhatsApp messages

Discover how to effortlessly forward incoming WhatsApp messages and delivery statuses to your application using our API with this comprehensive guide. With clear and concise instructions, you can streamline your messaging process easily.

Event-Based System

Our application's event-based system ensures that updates are provided in a timely manner. To stay informed, subscribe to two different events available for each WhatsApp channel within the messaging portal.

Incoming Message

Our application generates an event when an incoming message is received on the WhatsApp business number. The event contains crucial metadata about the message, including the sender's information, message content, and forwarding timestamp.

Delivery Status

Our system generates a delivery status event as soon as a message is sent and either successfully delivered or failed to deliver. This event includes important details such as the recipient's information, message ID, delivery timestamp, and message status (read, delivered, or failed).

Event Subscription

Prerequisite

You must have an active WhatsApp channel.
You should have access to WhatsApp Assistant in the messaging portal to configure the rules.

There are two ways to subscribe to these events and forward the incoming WhatsApp messages and delivery status using our API :

1. Forwarding to an email address

When a message is received on the WhatsApp number assigned to the channel, our platform checks the events and rules configured in the WhatsApp Assistant for that channel. If the conditions specified in the rule are met, the platform forwards the message to the email addresses configured as part of the rule.

Please note that our platform currently only supports forwarding text, media, and location WhatsApp messages via email. Media are sent as links to external storage, while locations are forwarded as a Google Maps link.

2. Forwarding to an HTTP URL

To receive notifications on your server, you need to create an endpoint and configure an HTTP URL in the HTTP forward rule of the WhatsApp assistant. Whenever a message is received on the WhatsApp number assigned to the channel, our platform checks the configured events and rules for that channel. If the specified conditions are satisfied, the platform forwards the message as an HTTP POST request containing a JSON payload that describes the change. You can configure a separate URL for each channel.

The JSON payload and its components are described in our Open API documentation and its format is based on Meta’s format. For more information refer to Meta for Developers - Webhooks.

Please note: When using HTTP URL, you must confirm receipt of the notification with the response body.

Example Payload for Incoming message

{
    "object": "whatsapp_business_account",
       "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
          "changes": [{
       "value": {
          "messaging_product": "whatsapp",
                "metadata": {
             "display_phone_number": PHONE_NUMBER,
                   "phone_number_id": PHONE_NUMBER_ID
          },
          "contacts": [{
             "profile": {
                "name": "NAME"
             },
             "wa_id": PHONE_NUMBER
          }],
          "messages": [{
             "from": PHONE_NUMBER,
                   "id": "wamid.ID",
                   "timestamp": TIMESTAMP,
                   "text": {
                "body": "MESSAGE_BODY"
             },
             "type": "text"
          }]
       },
       "field": "messages"
    }]
}
]
}

If you receive a message that is not supported by WhatsApp Cloud API, you will get an unknown message webhook.

Example Payload for Delivery message

{
    "object":"whatsapp_business_account",
       "entry":[
    {
       "id":"WHATSAPP_BUSINESS_ACCOUNT_ID",
          "changes":[
       {
          "value":{
          "messaging_product":"whatsapp",
                "metadata":{
             "display_phone_number":"PHONE_NUMBER",
                   "phone_number_id":"PHONE_NUMBER_ID"
          },
          "statuses":[
          {
             "id":"wamid.ID",
                "recipient_id":"PHONE_NUMBER",
                "status":"delivered",
                "timestamp":"TIMESTAMP",
                "conversation":{
             "id":"CONVERSATION_ID",
                   "expiration_timestamp":"TIMESTAMP",
                   "origin":{
                "type":"user_initiated"
             }
          },
             "pricing":{
             "pricing_model":"CBP",
                   "billable":true,
                   "category":"service"
          }
          }
                 ]
       },
          "field":"messages"
       }
        ]
    }
  ]
}

Response JSON

{
"statusCode" : "...",
"statusMessage" : "...",
}