Transactional template sends

Transactional template sends let trusted external systems trigger expected WhatsApp messages through Switchbord. The endpoint is designed for Utility messaging such as payment receipts, instalment receipts, booking confirmations, vouchers, and other customer-expected operational events.

This endpoint is not a bulk marketing API. Switchbord validates the caller workspace, template status, and template category before queueing a send. Use approved UTILITY templates for transactional flows.

Endpoint

POST /api/v1/template-sends

The endpoint lives on the API app. Hosted workspaces call:

https://api.switchbord.ai/api/v1/template-sends

Self-hosted deployments should replace the host with their API domain.

Authentication

Use a Switchbord API key scoped to the workspace. The workspace is resolved from the API key; do not send workspace ids in the request body.

Authorization: Bearer sk_live_...
Content-Type: application/json
Idempotency-Key: receipt-event-123

You can also send the idempotency key as idempotencyKey in the JSON body. Prefer the header when the upstream system supports it.

Request shape

{
  "templateName": "payment_receipt_link",
  "templateLocale": "it",
  "recipient": {
    "phoneE164": "+393331234567",
    "externalId": "traveller-123",
    "name": "Giulia Rossi"
  },
  "variables": {
    "body": {
      "1": "Giulia",
      "2": "R-1001",
      "3": "€ 240,00"
    },
    "buttons": {
      "url": [
        { "index": 0, "suffix": "R-1001" }
      ]
    }
  },
  "metadata": {
    "source": "booking-system",
    "eventType": "payment.receipt.created"
  }
}

Field	Type	Required	Notes
`templateName`	string	Yes	Must resolve to an approved Utility template visible to the caller workspace.
`templateLocale`	string	No	Meta locale such as `it`, `it_IT`, or `en_US`. If omitted, the template lookup uses the workspace default behavior.
`recipient.phoneE164`	string	Yes unless contact/external lookup is supplied by a future contract	Phone in E.164 format.
`recipient.externalId`	string	No	External customer id to persist on the resolved contact.
`recipient.name`	string	No	Display name for newly created/resolved contact context.
`variables`	object	No	Body/header/button values compiled into Meta template components.
`components`	object	No	Alias for `variables`; use one or the other.
`idempotencyKey`	string	Recommended	Prevents duplicate sends for the same upstream event.
`metadata`	object	No	Stored with the message for audit/debug context. Do not include secrets.

Responses

A successful request queues an outbound message.dispatch job and returns the Switchbord identities for audit and reconciliation. New sends return HTTP 201:

{
  "data": {
    "contactId": "contact_123",
    "conversationId": "conversation_123",
    "messageId": "message_123",
    "clientMessageId": "receipt-event-123",
    "status": "queued",
    "reused": false,
    "idempotent": true
  }
}

If the same idempotency key is sent again, Switchbord returns HTTP 200 with the existing message identity and reused: true instead of creating a duplicate send.

Variables

Body variables

For positional templates, use 1-based numeric keys:

{
  "variables": {
    "body": {
      "1": "Giulia",
      "2": "R-1001",
      "3": "€ 240,00"
    }
  }
}

Named body variables are supported by Switchbord’s internal transactional compiler for inbound webhook mappings, but the public API route currently accepts positional body variables only. Use numeric body keys or an array when calling POST /api/v1/template-sends directly.

Dynamic URL button variables

For templates with a URL button such as https://example.com/r/{{1}}, supply the dynamic suffix by zero-based button index:

{
  "variables": {
    "buttons": {
      "url": [
        { "index": 0, "suffix": "R-1001" }
      ]
    }
  }
}

text and suffix are accepted aliases. The value must be non-empty.

Document header variables

For templates with a DOCUMENT header, supply a public HTTPS link. filename is optional but recommended.

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

Document links must use HTTPS. Invalid or non-HTTPS links are rejected before queueing.

Error responses

HTTP	Error	Meaning
`400`	`invalid_json`	Request body could not be parsed as JSON.
`400`	`invalid_request`	JSON parsed but did not match the endpoint schema.
`400`	`template_not_approved`	The template exists but is not approved by Meta.
`400`	`template_category_not_allowed`	The template is not Utility; transactional sends are Utility-only by default.
`400`	`invalid_media_link`	A document or image link is missing, invalid, or not HTTPS.
`400`	`missing_button_url_variable`	A dynamic URL button variable is required but empty.
`401`	`missing_authorization`	Missing `Authorization: Bearer ...` header.
`403`	`invalid_or_insufficient_key`	API key is invalid or does not have `data_write` scope.
`404`	`template_not_found`	Template name/locale could not be resolved for the workspace.
`429`	API access denied	Public API rate/security middleware denied the request.

Idempotent reuses are not errors. They return HTTP 200 with data.reused: true.

Operational notes

The worker still owns the final Meta dispatch. The API response means the message was accepted into Switchbord’s outbox, not necessarily delivered by Meta.
Delivery transitions (queued, sent, delivered, read, failed) are visible on the message/conversation records and in webhook status events.
Do not include raw card details, private receipt tokens, or long-lived secrets in template variables or metadata. Prefer short receipt ids or pre-signed URLs with appropriate expiry.

​Endpoint

​Authentication

​Request shape

​Responses

​Variables

​Body variables

​Dynamic URL button variables

​Document header variables

​Error responses

​Operational notes

​Related guides

Endpoint

Authentication

Request shape

Responses

Variables

Body variables

Dynamic URL button variables

Document header variables

Error responses

Operational notes

Related guides