> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/api-integration-guide/webhooks/incoming-message-callback.md).

# Incoming Message Callback

## Incoming Message Callback

The **Incoming Message Callback** is triggered when a WhatsApp user sends a message to your business number.

Inbound messages are returned inside the `notifications` array of the webhook payload. Depending on the message type, related sender information may also be included in the `contacts` array.

### Notification Structure

Each object inside `notifications` may contain the following fields:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>from</code></td><td>String</td><td>MSISDN of the user sending the message.</td></tr><tr><td><code>from_user_id</code></td><td>String</td><td>User ID of the user sending the message.</td></tr><tr><td><code>to</code></td><td>String</td><td>Identifier of the receiving WhatsApp business number.</td></tr><tr><td><code>replying_to</code></td><td>Object</td><td>Context object included when the user is replying to a specific message.</td></tr><tr><td><code>message_id</code></td><td>String</td><td>Generated ID of the inbound message.</td></tr><tr><td><code>message</code></td><td>Object</td><td>Contains the content and type of the inbound message.</td></tr><tr><td><code>timestamp</code></td><td>String</td><td>ISO-8601 date and time of the inbound message.</td></tr><tr><td><code>forwarded</code></td><td>Boolean</td><td>Indicates whether the message was forwarded.</td></tr><tr><td><code>frequently_forwarded</code></td><td>Boolean</td><td>Indicates whether the message was frequently forwarded.</td></tr><tr><td><code>referral</code></td><td>Object</td><td>Referral information when the message originates from an advertisement or post.</td></tr></tbody></table>

### Example Callback

The following example illustrates the general structure of an inbound message callback:

```json
{
  "type": "whatsapp",
  "statuses": [],
  "contacts": [],
  "notifications": [
    {
      "from": "9665XXXXXXXX",
      "from_user_id": "<USER_ID>",
      "to": "<WHATSAPP_BUSINESS_NUMBER>",
      "message_id": "<MESSAGE_ID>",
      "message": {
        "type": "text",
        "text": "Hello"
      },
      "timestamp": "2026-08-17T12:30:00Z",
      "forwarded": false,
      "frequently_forwarded": false
    }
  ]
}
```

> The values shown in this example are illustrative. The exact structure inside the `message` object depends on the inbound message type.

### Supported Referral Message Types

A `referral` object may be included when the customer sends a message in response to an advertisement or post.

According to the current Taqnyat API reference, referral information may be included with:

* Text
* Location
* Contacts
* Image
* Video
* Document
* Voice
* Sticker

### Reply Context

When a customer replies to a specific WhatsApp message, the callback may include the `replying_to` object.

Your application can use this information to identify the message the customer is responding to.

```json
{
  "replying_to": {
    "...": "..."
  }
}
```

> The current Taqnyat reference identifies `replying_to` as a context object but does not document its internal fields, so those fields should not be assumed here.

### Contact Information

The callback may also contain a `contacts` array with information related to the sender.

The current API reference notes that contact information may be included for:

* Text messages
* Contact messages
* Location messages

Example general structure:

```json
{
  "type": "whatsapp",
  "contacts": [
    {
      "...": "..."
    }
  ],
  "notifications": [
    {
      "...": "..."
    }
  ]
}
```

The exact fields inside the `contacts` object should be handled according to the data returned by the API.

### Processing Incoming Messages

When your application receives an inbound message:

1. Read the object inside `notifications`.
2. Identify the sender using `from` or `from_user_id`.
3. Use `message_id` as the unique identifier for the inbound message.
4. Inspect the `message` object to determine the message type and content.
5. Check `replying_to` when the message is a reply to an earlier message.
6. Process `referral` information when present.
7. Return a successful `2xx` response to Taqnyat.

### Expected Response

Your webhook endpoint should acknowledge successful receipt of the callback:

```http
HTTP/1.1 200 OK
```

If Taqnyat does not receive a successful response, the callback may be retried up to three times.

> A single webhook request can contain both inbound messages and delivery status updates, so your integration should check both `notifications` and `statuses` when processing callbacks.