Send a PDF invoice via WhatsApp API (sendFile)

This scenario sends a PDF document with sendFile during the 24-hour WhatsApp customer service window.

Use case overview

This scenario sends a PDF document with sendFile during the 24-hour WhatsApp customer service window. Use it when billing must attach an invoice without starting a new template conversation.

Template example

Invoice for ticket {{1}}

{{1}}
support ticket number shown in the PDF caption

WhatsApp Business API for session send — invoice pdf

When to use it

Reach for this scenario when billing must deliver a PDF invoice while a support conversation is still open on WhatsApp — the client already wrote first and the 24-hour session window is active. It fits billing follow-up inside helpdesk threads where attaching documents through approved templates would be slow or unnecessary for teams integrating 1MSG with ticket and invoicing backends.

No template round-trip for a PDF

sendFile delivers the invoice inside the open 24-hour session window, so billing attaches application/pdf without submitting or waiting on a new Meta template approval.

Invoice stays in the support thread

The PDF arrives in the same WhatsApp chat the client used for support, as application/pdf with filename invoice.pdf, instead of a separate email attachment they may never open.

Client can match the file to their ticket

One caption variable carries the support ticket number in "Invoice for ticket {{1}}", so the client can tie the document to the open case without searching another channel.

Less manual forwarding from the helpdesk

When the helpdesk marks a ticket ready for invoicing, your backend resolves the ticket number and PDF URL or upload path, then sendFile fires from that event.

Delivery logged for billing follow-up

Delivery status is written back to the helpdesk or billing system, so finance knows the invoice reached the client in the same thread.

Workflow

Trigger
The helpdesk marks a ticket ready for invoicing while the session is still open.
event · triggered
Capture event
Your backend resolves the ticket number and invoice PDF location.
phone: "+…"
Build & send
sendFile sends application/pdf with filename invoice.pdf and a caption referencing the ticket.
POST /send_file
Delivered
The client receives the PDF in the same WhatsApp thread.
delivered

Technical implementation

Prerequisites

1MSG API Key · How to get API Key
WhatsApp Business account · How to Connect WABA
Open 24-hour session window · How the 24-hour window works
Customer opt-in · How to Manage Customers Consent
Webhook endpoint · How to Set Up Webhooks

Code examples

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===
API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
MEDIA_URL="___"                         # local file path or HTTPS URL for sendFile body

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendFile"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "body": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "filename": "invoice.pdf"
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
  *'"sent":true'*) ok=1 ;;
  *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
  echo "Message sent to client."
  echo "API response: $BODY"
else
  echo "Send failed. HTTP status: $HTTP_CODE" >&2
  echo "$BODY" >&2
  exit 1
fi

Response and delivery status

HTTP 2xx and JSON "sent": true mean 1MSG accepted the message for sending — not that it already reached the customer's phone. Save the id field (looks like wamid.…) to correlate delivery callbacks.

200 OKResponse

{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}

sent
Accepted for sending — not yet on the customer's phone
id
Store it; delivery callbacks and hookInfo are keyed on this

Delivery statuses and webhooks →

Common errors

Status	API response	Cause	Fix
200	Message was not sent: provide chatId, phone, bsuid, or username	No recipient the channel could resolve.	Pass exactly one recipient: phone (country code plus number, digits only), chatId (for example [email protected]) or bsuid.
200	wrong file	The media could not be fetched or uploaded: the URL is not reachable or the base64 is invalid.	Pass a public HTTPS URL or valid base64 in body, or upload the file with /uploadMedia and send mediaId with mediaType.
200	Message was not sent: filename	sendFile was called without filename, so the file has no extension.	Add filename with an extension, for example invoice.pdf.