---
updatedAt: 2026-07-15T04:59:15.000Z
agentTools:
  projectIndex: https://partner-docs.gupshup.io/llms.txt
---

# Document message

Send a V3 document message to a WhatsApp user using either a media ID or a hosted link

<br />

> 📘 Note:
>
> 1. Use the `recipient` parameter only when BSUID is enabled for the app.
> 2. When both `to` and `recipient` fields are used in the payload, the `to` field gets the priority.

# Sample Request

```
curl --location 'https://partner.gupshup.io/partner/app/{{APP_ID}}/v3/message' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}' \
--data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "{{PHONE_NUMBER}}",
		"recipient": "{{BSUID}}"
    "type": "document",
    "document": {
        "id": "{{MEDIA_ID}}", 
        "link": "{{MEDIA_LINK}}", 
        "caption": "{{MEDIA_CAPTION}}",
        "filename": "{{MEDIA_FILENAME}}"
    }
}'
```

<br />

# Sample Response

```
{
    "messages": [
        {
            "id": "GUPSHUP_MESSAGE_ID"
        }
    ],
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "DESTINATION_PHONE_NO",
            "wa_id": "DESTINATION_PHONE_NO"
        }
    ]
}
```

<br />

# Request Parameters

<Table align={["left","left","left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Key
      </th>

      <th>
        Description
      </th>

      <th>
        Values
      </th>

      <th>
        Data Types
      </th>

      <th>
        Required/Optional
      </th>

      <th>
        Constraints
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Authorization
      </td>

      <td>
        Access Token for the application
      </td>

      <td>
        `{{PARTNER_APP_TOKEN}}`
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        Should be a valid Partner App Access Token.
      </td>
    </tr>

    <tr>
      <td>
        APP ID
      </td>

      <td>
        App ID to fetch the access token
      </td>

      <td>
        `{{APP_ID}}`
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        The Id should be a valid app Id of Gupshup
      </td>
    </tr>

    <tr>
      <td>
        messaging_product
      </td>

      <td>
        Messaging product
      </td>

      <td>
        whatsapp
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        recipient_type
      </td>

      <td>
        Recipient type
      </td>

      <td>
        individual
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        to
      </td>

      <td>
        Destination phone number where the message needs to be sent
      </td>

      <td>
        91785876xxxx
      </td>

      <td>
        String
      </td>

      <td>
        Required (Can be optional if BSUID is enabled for the app and recipient parameter is used instead)
      </td>

      <td>
        Must be a valid phone number
      </td>
    </tr>

    <tr>
      <td>
        recipient
      </td>

      <td>
        Destination BSUID where the message needs to be sent
      </td>

      <td>
        IN.461449821882xxxx
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>
        Must be a valid BSUID
      </td>
    </tr>

    <tr>
      <td>
        type
      </td>

      <td>
        Messaging type
      </td>

      <td>
        document
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        Type should be document to send document message.
      </td>
    </tr>

    <tr>
      <td>
        document
      </td>

      <td>
        Add document media ID or link inside body
      </td>

      <td>
        ```
        {
                "id": "{{MEDIA_ID}}", 
                "link": "{{MEDIA_LINK}}", 
                "caption": "{{MEDIA_CAPTION}}",
                "filename": "{{MEDIA_FILENAME}}"
            }
        ```
      </td>

      <td>
        Object
      </td>

      <td>
        Required
      </td>

      <td>
        Key should be document to send document message.
      </td>
    </tr>

    <tr>
      <td>
        caption
      </td>

      <td>
        Media asset caption text
      </td>

      <td>
        e.g - Please find the document attached
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>
        Maximum 1024 characters.
      </td>
    </tr>

    <tr>
      <td>
        filename
      </td>

      <td>
        Document filename, with extension
      </td>

      <td>
        e.g - demo.txt
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>
        The WhatsApp client will use an appropriate file type icon based on the extension.
      </td>
    </tr>

    <tr>
      <td>
        id
      </td>

      <td>
        ID of the uploaded media asset.
      </td>

      <td>
        e.g - 1013859600285441
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        Required if using uploaded media, otherwise omit.
      </td>
    </tr>

    <tr>
      <td>
        link
      </td>

      <td>
        URL of the media asset hosted on your public server.
      </td>

      <td>
        e.g - [https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf](https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf)
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        Required if using hosted media, otherwise omit. For better performance, we recommend using id and an uploaded media asset ID instead.
      </td>
    </tr>
  </tbody>
</Table>

<br />

# Status Codes

| Status Code | Response                                                                                                                                                          | Comments                                                                        |
| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| **Success** |                                                                                                                                                                   |                                                                                 |
| 200         | `{"messages": [{"id": "GUPSHUP_MESSAGE_ID"}], "messaging_product": "whatsapp", "contacts": [{"input": "DESTINATION_PHONE_NO", "wa_id": "DESTINATION_PHONE_NO"}]}` |                                                                                 |
| **Error**   |                                                                                                                                                                   |                                                                                 |
| 401         | `{"status": "error", "message": "Authentication Failed"}`                                                                                                         | When API key authentication failsIf Callback billing is not enabled for the app |
| 400         | `{"message": "Callback Billing must be enabled for this API", "status": "error"}`                                                                                 | If Callback billing is not enabled for the app                                  |
| 400         | `{"message": "Invalid App Details", "status": "error"}`                                                                                                           | If app details are not found                                                    |

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Gupshup V3 Document Session Message API",
    "description": "API for sending document messages via WhatsApp through Gupshup V3 platform",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://partner.gupshup.io/partner/app/{appId}/v3",
      "variables": {
        "appId": {
          "default": "07c7c72d-20e3-4ff9-a5a1-14d1186eeec8",
          "description": "Your Gupshup App ID"
        }
      }
    }
  ],
  "paths": {
    "/message": {
      "post": {
        "summary": "Document message",
        "description": "Send a V3 document message to a WhatsApp user using either a media ID or a hosted link",
        "operationId": "sendDocumentMessage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentMessageRequest"
              },
              "examples": {
                "withMediaId": {
                  "summary": "Document message using media ID",
                  "value": {
                    "messaging_product": "whatsapp",
                    "recipient_type": "individual",
                    "to": "917506080480",
                    "type": "document",
                    "document": {
                      "id": "1021671987023570",
                      "caption": "Please find the document attached",
                      "filename": "demo.txt"
                    }
                  }
                },
                "withHostedLink": {
                  "summary": "Document message using hosted link",
                  "value": {
                    "messaging_product": "whatsapp",
                    "recipient_type": "individual",
                    "to": "917506080480",
                    "type": "document",
                    "document": {
                      "link": "https://raw.githubusercontent.com/dwyl/english-words/master/words.txt",
                      "caption": "Please find the document attached",
                      "filename": "demo.txt"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                },
                "example": {
                  "messages": [
                    {
                      "id": "GUPSHUP_MESSAGE_ID"
                    }
                  ],
                  "messaging_product": "whatsapp",
                  "contacts": [
                    {
                      "input": "DESTINATION_PHONE_NO",
                      "wa_id": "DESTINATION_PHONE_NO"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "callbackBillingError": {
                    "summary": "Callback billing not enabled",
                    "value": {
                      "message": "Callback Billing must be enabled for this API",
                      "status": "error"
                    }
                  },
                  "invalidAppError": {
                    "summary": "Invalid app details",
                    "value": {
                      "message": "Invalid App Details",
                      "status": "error"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "error",
                  "message": "Authentication Failed"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "DocumentMessageRequest": {
        "type": "object",
        "required": [
          "messaging_product",
          "recipient_type",
          "to",
          "type",
          "document"
        ],
        "properties": {
          "messaging_product": {
            "type": "string",
            "enum": [
              "whatsapp"
            ],
            "description": "The messaging product used (currently only whatsapp)",
            "example": "whatsapp"
          },
          "recipient_type": {
            "type": "string",
            "enum": [
              "individual"
            ],
            "description": "The type of recipient (currently only individual)",
            "example": "individual"
          },
          "to": {
            "type": "string",
            "description": "Destination phone number in E.164 format",
            "example": "917506080480"
          },
          "type": {
            "type": "string",
            "enum": [
              "document"
            ],
            "description": "Message type (document for this API)",
            "example": "document"
          },
          "document": {
            "type": "object",
            "description": "Document object containing document details",
            "properties": {
              "id": {
                "type": "string",
                "description": "Media Object ID (required if not using link)",
                "example": "1021671987023570"
              },
              "link": {
                "type": "string",
                "format": "uri",
                "description": "Publicly hosted URL of the document (required if not using id)",
                "example": "https://raw.githubusercontent.com/dwyl/english-words/master/words.txt"
              },
              "caption": {
                "type": "string",
                "maxLength": 1024,
                "description": "Description of the document (optional)",
                "example": "Please find the document attached"
              },
              "filename": {
                "type": "string",
                "description": "Custom filename for the document (optional)",
                "example": "demo.txt"
              }
            },
            "oneOf": [
              {
                "required": [
                  "id"
                ]
              },
              {
                "required": [
                  "link"
                ]
              }
            ]
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Gupshup message ID",
                  "example": "GUPSHUP_MESSAGE_ID"
                }
              }
            }
          },
          "messaging_product": {
            "type": "string",
            "description": "Messaging product used",
            "example": "whatsapp"
          },
          "contacts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "input": {
                  "type": "string",
                  "description": "Input phone number",
                  "example": "DESTINATION_PHONE_NO"
                },
                "wa_id": {
                  "type": "string",
                  "description": "WhatsApp ID of the contact",
                  "example": "DESTINATION_PHONE_NO"
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Error status",
            "example": "error"
          },
          "message": {
            "type": "string",
            "description": "Error message description",
            "example": "Authentication Failed"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "API key in the format sk_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```
Key	Description	Values	Data Types	Required/Optional	Constraints
Authorization	Access Token for the application	`{{PARTNER_APP_TOKEN}}`	String	Required	Should be a valid Partner App Access Token.
APP ID	App ID to fetch the access token	`{{APP_ID}}`	String	Required	The Id should be a valid app Id of Gupshup
messaging_product	Messaging product	whatsapp	String	Required
recipient_type	Recipient type	individual	String	Required
to	Destination phone number where the message needs to be sent	91785876xxxx	String	Required (Can be optional if BSUID is enabled for the app and recipient parameter is used instead)	Must be a valid phone number
recipient	Destination BSUID where the message needs to be sent	IN.461449821882xxxx	String	Optional	Must be a valid BSUID
type	Messaging type	document	String	Required	Type should be document to send document message.
document	Add document media ID or link inside body	``` { "id": "{{MEDIA_ID}}", "link": "{{MEDIA_LINK}}", "caption": "{{MEDIA_CAPTION}}", "filename": "{{MEDIA_FILENAME}}" } ```	Object	Required	Key should be document to send document message.
caption	Media asset caption text	e.g - Please find the document attached	String	Optional	Maximum 1024 characters.
filename	Document filename, with extension	e.g - demo.txt	String	Optional	The WhatsApp client will use an appropriate file type icon based on the extension.
id	ID of the uploaded media asset.	e.g - 1013859600285441	String	Required	Required if using uploaded media, otherwise omit.
link	URL of the media asset hosted on your public server.	e.g - [https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf](https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf)	String	Required	Required if using hosted media, otherwise omit. For better performance, we recommend using id and an uploaded media asset ID instead.