PDF receipt via DOCUMENT header

This guide shows the Option B receipt pattern: the WhatsApp message includes a PDF document header and body variables describing the receipt. Use this pattern when the customer should receive the receipt document directly in WhatsApp instead of opening a receipt page.

Before you start

You need:

A connected WhatsApp channel in Switchbord.
An approved Utility template with a DOCUMENT header, for example payment_receipt_document.
A public HTTPS PDF URL. Meta must be able to fetch it.
A stable upstream event id for idempotency.

The document URL must be HTTPS and reachable by Meta. Do not use internal-only URLs, localhost, expiring URLs that expire before dispatch, or URLs containing reusable secrets.

Template shape

A typical document receipt template has a document header and a body like:

Ciao {{1}}, la ricevuta {{2}} è allegata a questo messaggio.

The document header receives:

{
  "link": "https://cdn.example.com/receipts/R-1001.pdf",
  "filename": "R-1001.pdf"
}

Direct API send

curl -X POST https://api.switchbord.ai/api/v1/template-sends \
  -H "Authorization: Bearer $SWITCHBORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-receipt-pdf-R-1001" \
  -d '{
    "templateName": "payment_receipt_document",
    "templateLocale": "it",
    "recipient": {
      "phoneE164": "+393331234567",
      "externalId": "traveller-123",
      "name": "Giulia Rossi"
    },
    "variables": {
      "header": {
        "document": {
          "link": "https://cdn.example.com/receipts/R-1001.pdf",
          "filename": "R-1001.pdf"
        }
      },
      "body": {
        "1": "Giulia",
        "2": "R-1001"
      }
    },
    "metadata": {
      "source": "booking-system",
      "eventType": "payment.receipt.pdf_ready"
    }
  }'

Expected response:

{
  "data": {
    "contactId": "contact_123",
    "conversationId": "conversation_123",
    "messageId": "message_123",
    "clientMessageId": "payment-receipt-pdf-R-1001",
    "status": "queued",
    "reused": false,
    "idempotent": true
  }
}

Inbound webhook builder

To map an external payment event into this template:

Open Settings → Integrations → Webhooks & API.
Create a new inbound webhook.
Select the approved payment_receipt_document Utility template.
Map the fields:

Template field	Source mode	Example source
Recipient phone	Payload path	`customer.phone`
External ID	Payload path	`receipt.id`
PDF document link	Payload path	`receipt.pdf`
PDF filename	Literal or payload path	`receipt.pdf` or `receipt.filename`
Body `{{1}}`	Payload path	`customer.first_name`
Body `{{2}}`	Payload path	`receipt.number`

Paste a sample payload and run the dry-run preview.
Create the webhook. New configs stay disabled and dry-run by default until live promotion is supported.

Sample payload:

{
  "customer": {
    "phone": "+393331234567",
    "first_name": "Giulia"
  },
  "receipt": {
    "id": "payment-receipt-pdf-R-1001",
    "number": "R-1001",
    "filename": "R-1001.pdf",
    "pdf": "https://cdn.example.com/receipts/R-1001.pdf"
  }
}

Named body variables

Switchbord’s inbound webhook mapper and internal transactional compiler support Meta named body parameters and compile them into parameter_name entries. The public POST /api/v1/template-sends route currently accepts positional body variables only, so direct API callers should use numeric body keys or an array.

Validation

Switchbord validates the document header before queueing:

link must be a valid HTTPS URL.
filename, when supplied, must be non-empty.
Required body variables must resolve to non-empty strings.
The selected template must be approved Utility.
The idempotency key must be stable for retries.

Troubleshooting

Symptom	Check
`400 invalid_media_link`	The document link is not valid HTTPS or cannot be parsed as a URL.
`400 invalid_document_filename`	A filename was supplied but resolved to an empty string.
`400 missing_template_name`	The webhook mapping did not resolve a template, or no template was selected.
`401 invalid_signature`	Webhook request was not signed with the one-time webhook secret.
Meta delivery fails after queueing	Confirm the PDF URL is still reachable by Meta and returns the correct content type.

Get Started

Features

WhatsApp

Guides

Contributing

Platform

Operations

Security & Compliance

PDF receipt via DOCUMENT header

Before you start

Template shape

Direct API send

Inbound webhook builder

Named body variables

Validation

Troubleshooting

​Before you start

​Template shape

​Direct API send

​Inbound webhook builder

​Named body variables

​Validation

​Troubleshooting

​Related reference

Before you start

Template shape

Direct API send

Inbound webhook builder

Named body variables

Validation

Troubleshooting

Related reference