Create a Template

Submit a new WhatsApp message template for Meta approval - header, body, footer and buttons, the same as the dashboard template builder.

Last updated 14 Aug 2026

Endpoint

POST /templates-create.php

Requires the Authorization: Bearer header described in Authentication, and the account maintenance fee for this number to be paid (the same requirement as the dashboard template builder).

Request body

Field	Type	Required	Description
`number`	string	yes	Your own connected WhatsApp number, digits only.
`name`	string	yes	Lowercase letters, numbers and underscores only.
`category`	string	yes	`MARKETING`, `UTILITY`, or `AUTHENTICATION`.
`language`	string	yes	Meta template language/locale code, e.g. `en_US`.
`header_type`	string	no	`NONE` (default), `TEXT`, `IMAGE`, `VIDEO`, or `DOCUMENT`.
`header_text`	string	if header_type is TEXT	Up to 60 characters, may contain one `{{1}}` variable.
`header_example`	string	if header_text has {{1}}	Sample value for the header variable.
`header_link`	string	if header_type is IMAGE/VIDEO/DOCUMENT	Public HTTPS URL of a JPG, PNG, MP4 or PDF sample, up to 16 MB. Riffre downloads it and forwards it to Meta - there is no separate upload step.
`body`	string	yes	Up to 1024 characters, may contain sequential variables `{{1}}`, `{{2}}`, ...
`body_examples`	array of strings	if body has variables	One sample value per variable, in order.
`footer`	string	no	Up to 60 characters.
`buttons`	array	no	Up to 10 buttons - see below.

Buttons

Each button is {"type": "QUICK_REPLY" | "URL" | "PHONE_NUMBER", "text": "..."}, plus url for URL buttons or phone_number for PHONE_NUMBER buttons.

Button text must be plain text, 25 characters or fewer - no variables, line breaks or emoji are allowed in button text, even though the header or body may use them freely. Meta rejects the whole template otherwise (subcode 2388060).

Example request

curl -X POST "https://your-riffre-domain.com/api/v1/templates-create.php" \
  -H "Authorization: Bearer rf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "911234567890",
    "name": "order_update",
    "category": "UTILITY",
    "language": "en_US",
    "body": "Hi {{1}}, your order {{2}} is ready.",
    "body_examples": ["Asha", "#4471"],
    "buttons": [{"type": "QUICK_REPLY", "text": "Track order"}]
  }'

Success response

200 OK:

{
  "id": "1234567890123456",
  "name": "order_update",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING"
}

Approval is not immediate - poll Get Template Status (status changes arrive by webhook on Riffre's side, so this reflects Meta's decision as soon as it happens).

Errors specific to this endpoint

`error` slug	HTTP status	Cause
`a_json_request_body_is_required`	422	The request body is missing or not valid JSON.
`header_link_must_be_a_valid_https_url_when_header_type_is_image,_video_or_document`	422	`header_type` is a media type but `header_link` is missing or not a valid HTTPS URL.

Every other validation rule (name format, body length, button text rules, and so on) also returns 422 with a specific message. See Errors for the full error response shape, and 402 Payment Required if the account maintenance fee for this number is unpaid.

Riffre API Reference