Message Templates

A message template is a pre-approved WhatsApp message. It is the only way to start a conversation with someone outside the 24-hour customer-service window — order updates, appointment reminders, one-time passcodes.

The 24-hour window

Meta lets you send free-form messages to a person only within 24 hours of their last message to you. Outside that window, free-form sends are refused and a template is the only route.

This is exactly what the freeformAlways capability reports: true on Baileys (no window at all), false on Meta. Check it rather than guessing:

curl https://api.yourdomain.com/workspaces/{workspaceId}/proxy/api/sessions/notifications/capabilities \
  -H "Authorization: Bearer wsk_your_key"

Listing approved templates

WaSphere pulls your approved templates straight from WhatsApp Manager, so there is nothing to keep in sync:

curl https://api.yourdomain.com/workspaces/{workspaceId}/proxy/api/sessions/notifications/templates \
  -H "Authorization: Bearer wsk_your_key"

Baileys sessions return an empty list. In the dashboard, the composer's template picker shows the same list.

Sending a template

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/proxy/api/messages/template \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "447700900123",
    "name": "order_update",
    "languageCode": "en_US",
    "bodyParams": ["Ali", "A123", "shipped"]
  }'

Field	Required	Notes
to	yes	Recipient phone number or JID
name	yes	The approved template's name
languageCode	yes	Language code, e.g. en_US
bodyParams	no	Values for {{1}}, {{2}}, … in body order. Up to 20.

bodyParams is positional — the first entry fills {{1}}, the second {{2}}, and so on. A template body of Hi {{1}}, your order {{2}} is {{3}}. with the params above sends "Hi Ali, your order A123 is shipped."

Creating a template

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/proxy/api/sessions/notifications/templates \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_update",
    "category": "UTILITY",
    "language": "en_US",
    "headerText": "Order update",
    "body": "Hi {{1}}, your order {{2}} is {{3}}.",
    "bodyExamples": ["Ali", "A123", "shipped"],
    "footer": "Reply STOP to opt out"
  }'

Field	Required	Rules
name	yes	Lowercase letters, numbers and underscores only
category	yes	UTILITY, MARKETING, or AUTHENTICATION
language	yes	en or en_US form
body	yes	1–1024 characters. Use {{1}}, {{2}}, … for variables
bodyExamples	conditional	One example value per variable — Meta requires these when the body has variables
headerText	no	Up to 60 characters
footer	no	Up to 60 characters

The response returns the template id and its initial status, normally PENDING.

Choosing a category

Category matters — Meta prices and polices templates by it, and submitting marketing content as UTILITY is a reliable way to get rejected.

• UTILITY — transactional messages about an existing order or account: shipping updates, receipts, appointment reminders.
• MARKETING — promotions, offers, re-engagement, anything selling.
• AUTHENTICATION — one-time passcodes and verification codes.

Approval

Meta reviews every submitted template. Approval typically takes minutes to a few hours, but a template stays PENDING until Meta says otherwise and cannot be sent before it is approved. Rejections usually come down to a mismatched category, missing example values, or promotional content in a non-marketing template.

Related

• Meta Cloud API — enabling the provider templates require
• Contacts — the recipients you are templating to
• Send messages — the rest of the send API