WhatsApp

WhatsApp message templates

View as MarkdownOpen in Claude

Templates are pre-approved message formats required when reaching out to customers who have not contacted you first. Think of them as pre-written scripts that Meta reviews and approves in advance. Once approved, you can send them to any customer at any time. See Send a template message for how to deliver one.

Your SignalWire Dashboard lists a connection’s templates on its WhatsApp Templates tab, under Integrations. Creating and editing templates is done through the API or directly in the Meta Business dashboard. A template you create in Meta appears in your Space only after you open the connection and select Sync with Meta.

Template components

A template is made up of components. A Body component is required; the header, footer, and buttons are optional.

ComponentDescription
HEADEROptional title line. Can be plain text or media (image, video, document).
BODYRequired. Main message text. Supports variable placeholders for personalization.
FOOTEROptional closing line (e.g. “Thank you for your order”).
BUTTONSOptional interactive buttons: quick reply, phone number, or URL.

Parameters

Templates support variable placeholders so you can personalize messages with customer names, order numbers, and so on. There are two styles, set by parameter_format:

  • Positional (positional): referenced as {{1}}, {{2}}, {{3}} in order.
  • Named (named): referenced by descriptive labels like {{first_name}} or {{order_status}}.

Categories

The category field must be one of:

  • marketing: promotional messages, offers, announcements
  • utility: transactional messages, order updates, account alerts
  • authentication: one-time passwords and verification codes

Manage templates

Templates are managed through the API. For the full request and response schemas, see the reference:

Create a template
List templates
Get a template
Update a template
Delete a template

The example below creates an order-update template with positional parameters. The components array is the heart of the request; each component’s fields depend on its type.

POST
/api/messaging/whatsapp/templates
curl -X POST https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates \
     -H "Content-Type: application/json" \
     -u "<project_id>:<api_token>" \
     -d '{
  "whatsapp_business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "order_update",
  "language": "en_US",
  "category": "utility",
  "parameter_format": "positional",
  "components": [
    {
      "type": "HEADER",
      "example": {
        "header_text": [
          "Jane Smith"
        ]
      },
      "format": "TEXT",
      "text": "Order Update for {{1}}"
    },
    {
      "type": "BODY",
      "example": {
        "body_text": [
          [
            "ORD-9821",
            "out for delivery"
          ]
        ]
      },
      "text": "Your order {{1}} is currently {{2}}."
    },
    {
      "type": "FOOTER",
      "text": "Thank you for shopping with us."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "text": "Track Order",
          "type": "QUICK_REPLY"
        },
        {
          "text": "Contact Support",
          "type": "URL",
          "url": "https://example.com/support"
        }
      ]
    }
  ]
}'
Try it

Approval and updates

Templates must be reviewed and approved by Meta before use. Approval typically takes a few minutes to a few hours. A template’s current state is reported in its template_status field. It must be approved before it can be used to send messages.

A template can only be updated while it is not yet approved. Once approved, delete and recreate it to make changes.

Anywhere a template ID is accepted, you can use either the SignalWire template ID (a UUID) or the Meta template ID (a numeric string).