Skip to main content
Send an approved WhatsApp template to a phone number. Template messages are the only way to initiate a WhatsApp conversation outside the 24-hour session window.

​
Endpoint

POST /api/v1/{subdomain}/messages/template
Required ability: messages.send.

​
Headers

HeaderValue
AuthorizationBearer apitk_...
Content-Typeapplication/json or multipart/form-data
Acceptapplication/json
Use multipart/form-data if you upload a header image, video, or document directly (header_image_file, header_video_file, header_document_file).

​
Path parameters

​
subdomain
string
required
Your workspace subdomain.

​
Body parameters

​
phone_number
string
required
Recipient phone number. 8–15 characters.
​
template_name
string
required
Name of the template (as registered with Meta).
​
template_language
string
required
Template language code. 2–10 characters (e.g. en_US).
​
from_phone_number_id
string
Meta phone-number id to send from. Defaults to the workspace’s primary number.

​
Header media (pick one pair)

​
header_image_url
string
URL of a hosted image. Used when the template header type is IMAGE.
​
header_image_file
file
Upload an image. Max 5120 KB.
​
header_video_url
string
URL of a hosted video.
​
header_video_file
file
Upload a video. Max 16384 KB.
​
header_document_url
string
URL of a hosted document.
​
header_document_file
file
Upload a document. Max 102400 KB.
​
header_document_name
string
Display filename for the header document. Max 255 characters.

​
Variable substitution

​
header_field_1
string
Value for {{1}} in a text header.
​
field_1
string
Value for {{1}} in the body.
​
field_2
string
Value for {{2}} in the body.
​
field_3
string
Value for {{3}} in the body.
​
field_4
string
Value for {{4}} in the body.
​
field_5
string
Value for {{5}} in the body.
​
field_6
string
Value for {{6}} in the body.
​
field_7
string
Value for {{7}} in the body.
​
field_8
string
Value for {{8}} in the body.
​
field_9
string
Value for {{9}} in the body.
​
field_10
string
Value for {{10}} in the body.
​
button_0
string
Button 0 dynamic parameter.
​
button_1
string
Button 1 dynamic parameter.
​
button_2
string
Button 2 dynamic parameter.
​
copy_code
string
One-time password for OTP templates. Max 100 characters.
​
contact
object
Optional contact payload for creating or updating the contact record behind this send.

​
Example request

curl -X POST https://dash.xobito.com/api/v1/acme/messages/template \
  -H "Authorization: Bearer apitk_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "template_name": "order_confirmation",
    "template_language": "en_US",
    "field_1": "John",
    "field_2": "#A1027"
  }'

​
Example response

200 OK
{
  "status": "success",
  "message": "Template message sent successfully",
  "data": {
    "message_id": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBI5QUQ1N...",
    "contact_id": 451,
    "phone": "+14155551234",
    "status": "sent",
    "sent_at": "2026-04-16T12:00:00.000000Z",
    "chat_id": 88,
    "contact_created": false
  }
}

​
Error responses

StatusWhenExample body
401Missing / invalid token{"status":"error","message":"Invalid API token"}
403Missing ability{"status":"error","message":"Token does not have the required ability: messages.send"}
404Template does not exist in your workspace{"status":"error","message":"Template not found"}
422Validation, or template is not APPROVED{"status":"error","message":"Validation failed","errors":{"template_name":["Template is not APPROVED."]}}
429Rate limit{"message":"Too many requests","retry_after":45}
500Send failure{"status":"error","message":"Failed to send template message"}
Xobito enforces Meta’s approval rule strictly: only templates with status: "APPROVED" can be sent. Use GET /templates to check status before sending.