Send a template message

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

Header	Value
`Authorization`	`Bearer <your-64-hex-token>`
`Content-Type`	`application/json` or `multipart/form-data`
`Accept`	`application/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

string

required

Your workspace subdomain.

Body parameters

string

required

Recipient phone number. 8–15 characters.

string

required

Name of the template (as registered with Meta).

string

required

Template language code. 2–10 characters (e.g. en_US).

string

Meta phone-number id to send from. Defaults to the workspace’s primary number.

Header media (pick one pair)

string

URL of a hosted image. Used when the template header type is IMAGE.

file

Upload an image. Max 5120 KB.

string

URL of a hosted video.

file

Upload a video. Max 16384 KB.

string

URL of a hosted document.

file

Upload a document. Max 102400 KB.

string

Display filename for the header document. Max 255 characters.

Variable substitution

string

Value for {{1}} in a text header.

string

Value for {{1}} in the body.

string

Value for {{2}} in the body.

string

Value for {{3}} in the body.

string

Value for {{4}} in the body.

string

Value for {{5}} in the body.

string

Value for {{6}} in the body.

string

Value for {{7}} in the body.

string

Value for {{8}} in the body.

string

Value for {{9}} in the body.

string

Value for {{10}} in the body.

string

Button 0 dynamic parameter.

string

Button 1 dynamic parameter.

string

Button 2 dynamic parameter.

string

One-time password for OTP templates. Max 100 characters.

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 <your_token>" \
  -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"
  }'

const res = await fetch(
  "https://dash.xobito.com/api/v1/acme/messages/template",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <your_token>",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      phone_number: "+14155551234",
      template_name: "order_confirmation",
      template_language: "en_US",
      field_1: "John",
      field_2: "#A1027",
    }),
  }
);
const body = await res.json();

import requests

r = requests.post(
    "https://dash.xobito.com/api/v1/acme/messages/template",
    headers={
        "Authorization": "Bearer <your_token>",
        "Accept": "application/json",
    },
    json={
        "phone_number": "+14155551234",
        "template_name": "order_confirmation",
        "template_language": "en_US",
        "field_1": "John",
        "field_2": "#A1027",
    },
)
body = r.json()

<?php
$ch = curl_init('https://dash.xobito.com/api/v1/acme/messages/template');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <your_token>',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone_number'      => '+14155551234',
        'template_name'     => 'order_confirmation',
        'template_language' => 'en_US',
        'field_1'           => 'John',
        'field_2'           => '#A1027',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

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

Status	When	Example body
`401`	Missing / invalid token	`{"status":"error","message":"Invalid API token"}`
`403`	Missing ability	`{"status":"error","message":"Token does not have the required ability: messages.send"}`
`404`	Template does not exist in your workspace	`{"status":"error","message":"Template not found"}`
`422`	Validation, or template is not `APPROVED`	`{"status":"error","message":"Validation failed","errors":{"template_name":["Template is not APPROVED."]}}`
`429`	Rate limit	`{"message":"Too many requests","retry_after":45}`
`500`	Send 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.

Introduction

API Reference

Webhooks

Data Types

Send a template message

Endpoint

Headers

Path parameters

Body parameters

Header media (pick one pair)

Variable substitution

Example request

Example response

Error responses

​Endpoint

​Headers

​Path parameters

​Body parameters

​Header media (pick one pair)

​Variable substitution

​Example request

​Example response

​Error responses

Endpoint

Headers

Path parameters

Body parameters

Header media (pick one pair)

Variable substitution

Example request

Example response

Error responses