---
updatedAt: 2026-02-10T09:26:57.000Z
agentTools:
  projectIndex: https://developers.kaleyra.io/llms.txt
---

# Document Message

The Document messages are messages that display a document icon, linked to a document, that a WhatsApp user can tap to download.

<Image align="center" border={true} src="https://files.readme.io/2e563ba7904a3eb6b1fc7a8754aa169344d1c8a8ea2ad5074fa450f06fc1d235-Document_Message.png" className="border" />

## Prerequisites

1. An active WhatsApp plan on Kaleyra platform.
2. An active WhatsApp for Business API plan that includes:
   1. A WhatsApp business number.
   2. An associated profile with the business number.
   3. A WhatsApp verified and approved profile.
   4. A WABA ID onboarded on Kaleyra WhatsApp API V2.
3. You must have the callback registered in the WhatsApp channel for the phone numbers.

## Sample Webhook

The following is the sample webhook.

```json
{
    "meta_object": {
        "value": {
            "messaging_product": "whatsapp",
            "metadata": {
                "display_phone_number": "918XXXXXXXXX",
                "phone_number_id": "1046XXXXXXXXXXX"
            },
            "contacts": [
                {
                    "profile": {
                        "name": "Samuel"
                    },
                    "wa_id": "919XXXXXXXXX"
                }
            ],
            "messages": [
                {
                    "from": "919XXXXXXXXX",
                    "id": "wamid.HBgMOTE5NzQwNzc2NTA1FQIAEhgXXXXXXXXgQzM4RUE2RjRBMDcyODcyNEY5RjIwREUwMzcA",
                    "timestamp": "172XXXXXXX",
                    "type": "document",
                    "document": {
                        "filename": "Open smile features for variability.pdf",
                        "mime_type": "application\/pdf",
                        "sha256": "a5auRphs4M7S53IpTQstXXXXXXFrDfh08Aj3tMvur5g=",
                        "id": "1062XXXXXXXXXX98"
                    }
                }
            ]
        },
        "field": "messages"
    },
     "extra_info": {    
      	 		"media_url": "",
      	 		"ref": "Hello This will be my reference id - 123",
      	 		"ref1": "shoes campaign",
      	 		"ref2": "summer sale campaign",
      			"reply_to": "48c38d78-4ec5-XXXX-abee-03XXXXXX6c85",
       	 		"trace_id": "cb94fee2-3e70-XXXX-944a-2a4XXXXdb90a",
      	 		"waba_id": "347XXXXXXXXXX69"    
    }
}
```

The `extra_info` object contains additional metadata related to end-user message or reply. These fields help in tracking message context, references, and internal identifiers.

The following describes each field within the `extra_info` object:

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Parameter
      </th>

      <th style={{ textAlign: "left" }}>
        Data Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>

      <th style={{ textAlign: "left" }}>
        Example
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `media_url`
      </td>

      <td style={{ textAlign: "left" }}>
        URL
      </td>

      <td style={{ textAlign: "left" }}>
        Contains the URL of the media (image, video, document, and many more) shared by the end user, if applicable.
      </td>

      <td style={{ textAlign: "left" }}>
        https://example.com/images/product123.jpg
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `ref, ref1, and ref2`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        A reference parameter provided by the brand during the original message send request.
        This value appears in `extra_info` only when:  
        i. The end-user replies to a previous message by selecting or highlighting it, or  
        ii. The end-user responds through an interactive element (for example, a button) from an earlier message.
      </td>

      <td style={{ textAlign: "left" }}>
        shoes campaign
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `reply_to`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        This field represents the parent message ID (the original message to which the end-user is replying) in the following scenarios:  
        i. The end-user replies to a previous message by selecting or highlighting it, or  
        ii. The end-user responds through an interactive element (for example, a button) from an earlier message.  
        Note: If there is NO parent message ID, the `reply_to` field in the callback will be empty.
      </td>

      <td style={{ textAlign: "left" }}>
        48c38d78-4ec5-XXXX-abee-03XXXXXX6c85
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `trace_id`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        An internal Kaleyra-generated identifier used for message tracing and debugging.
      </td>

      <td style={{ textAlign: "left" }}>
        cb94fee2-3e70-XXXX-944a-2a4XXXXdb90a
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `waba_id`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        The WhatsApp Business Account (WABA) ID associated with the message.
      </td>

      <td style={{ textAlign: "left" }}>
        347XXXXXXXXXX69
      </td>
    </tr>
  </tbody>
</Table>

<br />