Skip to content
Templates

Create a template

POST
/{phone_number_id}/templates
const url = 'https://api.kirimdev.com/v1/106540352242922/templates';
const options = {
method: 'POST',
headers: {
'Idempotency-Key': 'order-20260910-0001',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: '{"name":"order_confirmation","category":"MARKETING","language":"en","components":[{"type":"HEADER","format":"TEXT","text":"example","example":{"header_text":["example"],"header_handle":["example"],"header_url":["https://example.com"],"body_text":[["example"]]},"buttons":[{"type":"URL","text":"example","url":"https://example.com","phone_number":"example","otp_type":"COPY_CODE","autofill_text":"example","supported_apps":[{"package_name":"example","signature_hash":"example"}],"example":["example"]}],"cards":[{"components":[{"type":"HEADER","format":"IMAGE","text":"example","example":{"header_handle":["example"],"header_url":["https://example.com"],"body_text":[["example"]]},"buttons":[{"type":"URL","text":"example","url":"https://example.com","phone_number":"example","otp_type":"COPY_CODE","autofill_text":"example","supported_apps":[{"package_name":"example","signature_hash":"example"}],"example":["example"]}]}]}],"add_security_recommendation":true,"code_expiration_minutes":1}],"variables":["example"],"messageSendTtlSeconds":1}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

Create a new message template and submit it to Meta for review. The request body is components-only (mirrors Meta’s message_templates create shape). For IMAGE/VIDEO/DOCUMENT headers, supply example.header_url with a public https:// URL — Kirimdev uploads the sample to Meta on your behalf — or a Meta asset handle in example.header_handle. On success the template is persisted with status: "pending"; Meta reviews asynchronously, so poll GET /{phone_number_id}/templates/{name} (or re-run POST .../templates/sync) for the eventual approved / rejected transition. A duplicate name+language pair returns 409 template_already_exists.

phone_number_id
required

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

string
/^\d{6,20}$/
Example
106540352242922

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

Idempotency-Key

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

string
Example
order-20260910-0001

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

Media type application/json
object
name
required
string
>= 1 characters <= 512 characters /^[a-z0-9_]+$/
Example
order_confirmation
category
required
string
Allowed values: MARKETING UTILITY AUTHENTICATION
Example
UTILITY
language
string
default: en >= 2 characters <= 10 characters /^[a-z]{2,3}(_[A-Z]{2})?$/
Example
id
components
required
Array<object>
>= 1 items
object
type
required
string
Allowed values: HEADER BODY FOOTER BUTTONS CAROUSEL
format
string
Allowed values: TEXT IMAGE VIDEO DOCUMENT LOCATION
text
string
example
object
header_text
Array<string>
header_handle
Array<string>
header_url
Array<string>
body_text
Array<Array<string>>
buttons
Array<object>
object
type
required
string
Allowed values: URL PHONE_NUMBER QUICK_REPLY COPY_CODE OTP VOICE_CALL
text
string
>= 1 characters <= 25 characters
url
string format: uri
<= 2000 characters
phone_number
string
/^\+[1-9]\d{7,14}$/
otp_type
string
Allowed values: COPY_CODE ONE_TAP ZERO_TAP
autofill_text
string
supported_apps
Array<object>
object
package_name
required
string
signature_hash
required
string
example
Array<string>
cards
Array<object>
object
components
required
Array<object>
>= 1 items
object
type
required
string
Allowed values: HEADER BODY BUTTONS
format
string
Allowed values: IMAGE VIDEO
text
string
example
object
header_handle
Array<string>
header_url
Array<string>
body_text
Array<Array<string>>
buttons
Array<object>
object
type
required
string
Allowed values: URL PHONE_NUMBER QUICK_REPLY COPY_CODE OTP VOICE_CALL
text
string
>= 1 characters <= 25 characters
url
string format: uri
<= 2000 characters
phone_number
string
/^\+[1-9]\d{7,14}$/
otp_type
string
Allowed values: COPY_CODE ONE_TAP ZERO_TAP
autofill_text
string
supported_apps
Array<object>
object
package_name
required
string
signature_hash
required
string
example
Array<string>
add_security_recommendation
boolean
code_expiration_minutes
integer
>= 1 <= 60
variables
Array<string>
messageSendTtlSeconds
integer
>= 30 <= 2592000

Template created (pending Meta review)

Media type application/json
object
data
required
object
id
required
string
object
required
string
Allowed values: template
name
required
string
language
required
string
status
required
string
Allowed values: pending approved rejected
category
required

Meta template category. null for templates synced before this field was recorded — a subsequent sync backfills it from Meta.

string | null
Allowed values: MARKETING UTILITY AUTHENTICATION
content
required
string
variables
required
Array<string>
components
whatsapp_account
required
object
phone_number
required
string | null
phone_number_id
required

Meta business_phone_number_id — use as the {phone_number_id} path segment in /v1/{phone_number_id}/... endpoints.

string | null
customer
required

End-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts.

object
id
required
string
name
required
string
provider_template_id
required
string | null
created_at
required
string format: date-time
updated_at
required
string format: date-time
request_id
required

Unique request identifier to include when contacting support.

string
Example
{
"data": {
"id": "tmpl_01HXYZABCDEFGHJKMNPQRSTVWX",
"object": "template",
"status": "pending",
"category": "MARKETING",
"whatsapp_account": {
"phone_number_id": "106540352242922",
"customer": {
"id": "cus_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}
},
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

Validation failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

A field value is invalid.

{
"error": {
"type": "invalid_request_error",
"code": "invalid_field_value",
"message": "A field value is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Authentication failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The provided API key is invalid.

{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Resource not found

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Resource not found.

{
"error": {
"type": "not_found",
"code": "resource_not_found",
"message": "Resource not found.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Conflict (e.g. template already exists, webhook subscription disabled, setup link inactive)

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

A template with this name and language already exists for this WhatsApp account.

{
"error": {
"type": "conflict",
"code": "template_already_exists",
"message": "A template with this name and language already exists for this WhatsApp account.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.

{
"error": {
"type": "invalid_request_error",
"code": "whatsapp_number_not_verified",
"message": "The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Rate limit exceeded

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Rate limit exceeded.

{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Internal server error

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

An unexpected error occurred.

{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "An unexpected error occurred.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Upstream WhatsApp error

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Upstream WhatsApp API failed; please retry.

{
"error": {
"type": "api_error",
"code": "whatsapp_upstream_error",
"message": "Upstream WhatsApp API failed; please retry.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}