Skip to main content
Version: v0.31.0

Send template messages with variables

Save a message once with {{variable}} placeholders, then render it for each recipient with a fresh set of values. A template keeps your copy consistent — an order confirmation, an OTP notice, a status update — and one POST sends the rendered text to any chat.

This guide shows you how to create, list, fetch, update, and delete templates, and how to send a rendered template to a chat.

Prerequisites

All examples use these placeholders. Set them once in your shell:

export BASE="http://localhost:2785/api" # /api is the global prefix; behind your domain + TLS in production
export API_KEY="YOUR_API_KEY" # an operator-or-higher key, from your dashboard
export SESSION="8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a" # the UUID id of a ready session

Create a template​

Send a POST to /api/sessions/{sessionId}/templates. name and body are required; header and footer are optional. Use {{variable}} tokens in the body, header or footer for the parts that change per recipient. A send delivers the header, the body and the footer in that order as one text message, each part that is present separated from the next by a blank line.

curl -X POST "$BASE/sessions/$SESSION/templates" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order-confirmation",
"body": "Hi {{customer}}, your order {{orderId}} has shipped.",
"header": "OpenWA Store",
"footer": "Reply STOP to unsubscribe."
}'

A 201 returns the stored template with its id and timestamps:

{
"id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
"sessionId": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
"name": "order-confirmation",
"body": "Hi {{customer}}, your order {{orderId}} has shipped.",
"header": "OpenWA Store",
"footer": "Reply STOP to unsubscribe.",
"createdAt": "2026-07-28T10:00:00.000Z",
"updatedAt": "2026-07-28T10:00:00.000Z"
}

name is unique within the session and capped at 100 characters. The stored body is capped at 4096 characters; header and footer at 1024 each. The rendered result, header and footer included and after variable substitution, is capped separately at TEMPLATE_RENDER_MAX_CHARS (default 64 KiB), and a render over that cap returns 400 (see Common errors). Since v0.26.0 the length is measured before the text is built, so an oversized render is refused without ever being allocated; before, a placeholder repeated through a small body made the gateway build the whole text first, which could exhaust its memory. A bulk item whose text or caption would render past the same cap fails the same way.

Since v0.26.0 a name, body, header or footer sent as a JSON boolean or object is refused with 400; before, it was converted to text, so a template could be stored with the body [object Object]. A JSON number is still read as its text. A 409 means the session already has a template with that name. A 404 means no session has that id; before v0.23.6 that case answered 500.

Send a rendered template​

POST /api/sessions/{sessionId}/messages/send-template takes the recipient chatId and either templateId or templateName, plus a vars object whose keys substitute the {{tokens}} in the header, body and footer.

curl -X POST "$BASE/sessions/$SESSION/messages/send-template" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatId": "628123456789@c.us",
"templateName": "order-confirmation",
"vars": {
"customer": "Alice",
"orderId": "1234"
}
}'

A 201 means the template rendered and the message was sent. The send is a text send, so it waits for the same typing pause as send-text (see Send a text message). It takes the same optional linkPreview boolean as send-text; when the request leaves it unset, the linkPreview key of the session config applies (v0.30.3+, see Link previews). A 400 means the session is not active or the request is invalid; a 404 means the session or the template does not exist.

Send by id instead of name when you want to pin a specific revision:

curl -X POST "$BASE/sessions/$SESSION/messages/send-template" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatId": "628123456789@c.us",
"templateId": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
"vars": { "customer": "Bob", "orderId": "5678" }
}'

List templates​

GET /api/sessions/{sessionId}/templates returns every template for the session as an array.

curl "$BASE/sessions/$SESSION/templates" \
-H "X-API-Key: $API_KEY"

Fetch a template by id​

GET /api/sessions/{sessionId}/templates/{id} returns one template. A 404 means the id does not exist for this session.

curl "$BASE/sessions/$SESSION/templates/b1c2d3e4-f5a6-7890-bcde-f01234567890" \
-H "X-API-Key: $API_KEY"

Update a template​

PUT /api/sessions/{sessionId}/templates/{id} replaces the fields you send — name, body, header, footer — and returns the updated template. All fields are optional on update; omitted fields keep their current value. Since v0.26.0 the update writes only the fields you send, so two overlapping edits to different fields no longer undo each other, and an update that loses a race with a delete answers 404 instead of bringing the template back.

curl -X PUT "$BASE/sessions/$SESSION/templates/b1c2d3e4-f5a6-7890-bcde-f01234567890" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"body": "Hi {{customer}}, your order {{orderId}} is out for delivery."
}'

Delete a template​

DELETE /api/sessions/{sessionId}/templates/{id} removes the template and returns 204 with no body.

curl -X DELETE "$BASE/sessions/$SESSION/templates/b1c2d3e4-f5a6-7890-bcde-f01234567890" \
-H "X-API-Key: $API_KEY"

Troubleshooting​

ProblemCauseFix
404 Template not foundThe id does not belong to this session, or the template was deletedList templates to get a current id
404 Session with id '<id>' not found on createNo session has that id (v0.23.6+; a 500 before)Create the template under the id of an existing session
404 Template with name '<name>' not found on send (Template with id '<id>' not found when sent by templateId)No template with that name or id exists for this session id, which includes a session id that does not existList templates to get a current name or id
403 API key is restricted to selected chatsThe key carries allowedChats (v0.23.6+). Creating, listing, fetching, updating and deleting templates refuse such a keyManage templates with a key that has no allowedChats. A chat-scoped key can still send a stored template with send-template
403 API key not authorized for this chat on sendThe key carries allowedChats (v0.23.6+) and chatId is outside itSend only to chats in the key's allowlist; see Authentication
400 Session not active or invalid requestThe session has no running engine, because it was never started or has been stopped (Session '<id>' is not active. Start the session first.), or the request body is invalid. Since v0.26.0 that includes chatId, templateId or templateName sent as a JSON boolean or object (a JSON number is still read as its text), a chatId that is not in the form localpart@host (a number without @c.us answered 500 on Baileys before), a template that renders to empty text after variable substitution, and a vars value that a header, body or footer token refers to and that has no text formStart the session, then retry; correct the field the message array names. A vars set that does not match the body tokens is not a 400: unmatched tokens render literally, as the row below says
409 Conflict on sendAn idempotency key is still in progress or its outcome is unknown (see Retry a send), or the session has an engine but it is not ready: disconnected, reconnecting, or initializing, so the request never reached WhatsApp. One window answers this while the session still reads ready, when WhatsApp Web reloads its own page and the engine re-injects into it: on whatsapp-web.js that 409 carries code: "ENGINE_PAGE_RELOADING" and retryAfterSeconds (v0.31.0+), and nothing was sent. A whatsapp-web.js send that a page reload cut while it ran, and a Baileys send whose connection was replaced or stopped while it was being written, answer a 409 with no code whose message says the message may or may not have been sent (v0.31.0+)For a readiness refusal, wait for ready. For ENGINE_PAGE_RELOADING, ask again every retryAfterSeconds: a reload takes seconds on most pages and can take a few minutes, and no event marks its end. For IDEMPOTENCY_KEY_IN_PROGRESS, retry with the same key once the first request finishes. For IDEMPOTENCY_OUTCOME_UNKNOWN, or a 409 that says the message may or may not have been sent, check the chat first and send again only with a new key: the same key keeps answering 409 until its 24-hour window ends
503 Service Unavailable on sendOn Baileys, the recipient lookup did not finish within the request budget (nothing was sent), or, since v0.26.0, WhatsApp rate-limited the send (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven); those two answered 500 beforeRetry shortly. With an Idempotency-Key, a 429 or (since v0.27.0) a pre-send recipient lookup timeout frees the key and a 408 keeps it taken, so check the chat before sending again with a new key
Template text arrives with {{tokens}} unrenderedvars omitted a key the header, body or footer referencesProvide every token used in the template

Next steps​