post
https://partner.gupshup.io/partner/app/{appId}/v3/message
Send a V3 document message to a WhatsApp user using either a media ID or a hosted link
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Note:
- Use the
recipientparameter only when BSUID is enabled for the app.- When both
toandrecipientfields are used in the payload, thetofield 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}}"
}
}'
Sample Response
{
"messages": [
{
"id": "GUPSHUP_MESSAGE_ID"
}
],
"messaging_product": "whatsapp",
"contacts": [
{
"input": "DESTINATION_PHONE_NO",
"wa_id": "DESTINATION_PHONE_NO"
}
]
}
Request Parameters
| 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 | 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 | | 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 | String | Required | Required if using hosted media, otherwise omit. For better performance, we recommend using id and an uploaded media asset ID instead. |
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 |