API Reference

Templates (send compatibility)

This page documents the templates send compatibility API — list approved templates and send them. Full Cloud lifecycle (validate, create/submit, sync, edit, delete, status webhooks, durable send idempotency) is under WhatsApp Templates API in the sidebar.

Two surfaces — do not confuse them

Send compatibility (this page): GET /v1/templates, POST /v1/templates/send for CRM send flows.
Full Cloud template lifecycle: WhatsApp Templates API — programmatic create/submit where the feature flag / canary allows. Do not use POST /v1/templates as an endpoint probe — use capabilities + validate.

GET /templates templates:read

List approved Cloud templates for your account.

Parameter	Type	Required	Description
`whatsapp_account_id`	integer	optional	Filter by Cloud account ID.
`per_page`	integer	optional	Page size (default 25, max 100).

curl -H "client-id: YOUR_CLIENT_ID" \
     -H "client-secret: YOUR_CLIENT_SECRET" \
     "https://staging-mobile.washeej.com/v1/templates?whatsapp_account_id=YOUR_ACCOUNT_ID"

POST /templates/send messages:send

Send an approved Cloud template message (text variables and/or DOCUMENT/IMAGE/VIDEO header media).

Parameter	Type	Required	Description
`template_id`	string	required	Washeej template ID or Meta whatsapp_template_id.
`mobile_code`	string	required	Country dial code without +.
`mobile`	string	required	National number digits only.
`whatsapp_account_id`	integer	optional	Cloud account to send from.
`from_number`	string	optional	Alternative channel selector (digits only).
`body_variables`	string[]	optional	Ordered values for {{1}}, {{2}}, … in the body. Omit when the body has no placeholders.
`header_variables`	string[]	optional	Values for TEXT header variables only.
`header_media_url`	url	optional	Public HTTPS URL Meta will fetch when header_format is DOCUMENT, IMAGE, or VIDEO. Delivers a native media bubble (not a text link).
`header_media_file`	file	optional	Multipart file upload alternative to header_media_url (also accepts media_file).

curl -X POST https://staging-mobile.washeej.com/v1/templates/send \
  -H "client-id: YOUR_CLIENT_ID" \
  -H "client-secret: YOUR_CLIENT_SECRET" \
  -H "Idempotency-Key: send-YOUR-UNIQUE-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "mobile_code": "966",
    "mobile": "500000000",
    "whatsapp_account_id": YOUR_CLOUD_ACCOUNT_ID,
    "header_media_url": "https://files.example.com/docs/INV-1001.pdf",
    "body_variables": ["Ahmed", "INV-1001"]
  }'

Notes

Templates require a Cloud API channel (not Device/QR).
Lifecycle send paths require Idempotency-Key (see WhatsApp Templates API → Send / Idempotency). Missing key → 422 idempotency_key_required.
Programmatic create/submit is available via WhatsApp Templates API when the lifecycle feature flag / canary assignment allows; otherwise create text templates in the dashboard. API send still lists and sends approved templates.
DOCUMENT/IMAGE/VIDEO: use header_media_url or header_media_file — see Guides → Template Media Headers.
Text URL inside the body: use body_variables — see Guides → Dynamic Invoice Link.
AUTHENTICATION OTP: exactly one 4–8 digit code in body_variables — see Guides → Authentication OTP.
Meta requires body/header text variables to not sit at the start or end of the copy.
If media fields are omitted on a media-header template, the template sample media may be reused.
MARKETING templates may return marketing_suppressed for opted-out contacts.

Common errors: billing_blocked, marketing_suppressed, capability_error, validation_error, not_found

Variable mapping

body_variables is a zero-based array matching Meta placeholders in order: index 0 → {{1}}, index 1 → {{2}}, and so on.

Outside the customer-care window

Do not silently transform POST /v1/messages free text into a template. When the session window requires a template, the API returns 422 template_required with template_send_endpoint. Your CRM chooses an approved scenario template.