Document 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
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

📘

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}}"
    }
}'

Sample Response

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

Request Parameters

KeyDescriptionValuesData TypesRequired/OptionalConstraints
AuthorizationAccess Token for the application{{PARTNER_APP_TOKEN}}StringRequiredShould be a valid Partner App Access Token.
APP IDApp ID to fetch the access token{{APP_ID}}StringRequiredThe Id should be a valid app Id of Gupshup
messaging_productMessaging productwhatsappStringRequired
recipient_typeRecipient typeindividualStringRequired
toDestination phone number where the message needs to be sent91785876xxxxStringRequired (Can be optional if BSUID is enabled for the app and recipient parameter is used instead)Must be a valid phone number
recipientDestination BSUID where the message needs to be sentIN.461449821882xxxxStringOptionalMust be a valid BSUID
typeMessaging typedocumentStringRequiredType should be document to send document message.
documentAdd document media ID or link inside body
{
        "id": "{{MEDIA_ID}}", 
        "link": "{{MEDIA_LINK}}", 
        "caption": "{{MEDIA_CAPTION}}",
        "filename": "{{MEDIA_FILENAME}}"
    }
ObjectRequiredKey should be document to send document message.
captionMedia asset caption texte.g - Please find the document attachedStringOptionalMaximum 1024 characters.
filenameDocument filename, with extensione.g - demo.txtStringOptionalThe WhatsApp client will use an appropriate file type icon based on the extension.
idID of the uploaded media asset.e.g - 1013859600285441StringRequiredRequired if using uploaded media, otherwise omit.
linkURL of the media asset hosted on your public server.e.g - https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdfStringRequiredRequired if using hosted media, otherwise omit. For better performance, we recommend using id and an uploaded media asset ID instead.

Status Codes

Status CodeResponseComments
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
Body Params
string
enum
required

The messaging product used (currently only whatsapp)

Allowed:
string
enum
required

The type of recipient (currently only individual)

Allowed:
string
required

Destination phone number in E.164 format

string
enum
required

Message type (document for this API)

Allowed:
document
required

Document object containing document details

Responses

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json