Create a new WhatsApp template

Submits the template to Meta's WhatsApp Business API and stores it locally. The returned status is whatever Meta gave back — typically PENDING for newly submitted templates (approval is async on Meta's side, usually within minutes). Use POST /api/v1/whatsapp/templates/{uuid}/sync to refresh status later. Body components must follow Meta's component spec — see https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates. The `examples` section below shows 12 ready-to-copy bodies covering every combination — text-only, variables in header/body, IMAGE/VIDEO/DOCUMENT headers, footer, all four button types, and a full-feature template. **Variables ({{1}}, {{2}}, ...):** Whenever a component's `text` contains a `{{n}}` placeholder you MUST provide an `example` payload — Meta uses it to render a preview during approval review. - BODY variables → `example.body_text` is a NESTED array: `[['John','12345']]`. The outer array is per-language; we always pass a single inner row. - HEADER (TEXT) variables → `example.header_text` is a flat array: `['John']`. A TEXT header can have at most one `{{1}}` placeholder. - HEADER (IMAGE/VIDEO/DOCUMENT) → no variables. Provide `example.header_handle = ['<handle>']` from /upload-media. **Media headers (IMAGE/VIDEO/DOCUMENT):** Two-step flow — POST /upload-media first to get a `handle`, then put that handle in `components[i].example.header_handle[0]`. The component itself uses `type='HEADER'` with `format='IMAGE'|'VIDEO'|'DOCUMENT'` and no `text` field. **Footer:** Single component `{ type:'FOOTER', text:'...' }`. Plain text only — no variables, no formatting, max 60 chars. Common use: 'Reply STOP to unsubscribe.' **Buttons:** Single `{ type:'BUTTONS', buttons:[...] }` component. Up to 10 buttons. Four supported types: - QUICK_REPLY — `{ type:'QUICK_REPLY', text:'Yes' }`. Inbound reply arrives as a button click event. - URL — `{ type:'URL', text:'Track order', url:'https://example.com/{{1}}' }`. Supports one `{{1}}` placeholder in the URL. - PHONE_NUMBER — `{ type:'PHONE_NUMBER', text:'Call us', phone_number:'[phone]' }`. E.164 format. - COPY_CODE — `{ type:'COPY_CODE', example:'WELCOME10' }`. No `text` — WhatsApp renders the code as the button label. **Status after create:** Always PENDING for new submissions. Approval is async on Meta's side (usually under 5 minutes for clean templates, hours for borderline content). Poll with POST /templates/{uuid}/sync, or wait for the webhook.

POST /api/v1/whatsapp/templates

cURL

text-only-no-vars

curl --request POST \
  --url https://{subdomain}.mihu.ai/api/v1/whatsapp/templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "welcome_message",
  "language": "en_US",
  "category": "MARKETING",
  "waba_id": "123456789012345",
  "components": [
    {
      "type": "BODY",
      "text": "Welcome to our service! We're glad to have you."
    }
  ]
}
EOF

201

{
  "success": true,
  "message": "Template created successfully",
  "data": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "language": "en_US",
    "category": "MARKETING",
    "status": "APPROVED",
    "content": "<string>",
    "components": [
      {}
    ],
    "template_id": "<string>",
    "waba_id": "<string>",
    "phone_number": "<string>",
    "type": "whatsapp",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization · string · header · required

Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}"

Body

application/json

name · string · required

Template name. Must be lowercase snake_case, unique per (name, language) within the WABA. 1-512 chars.

Example:

"order_confirmation"

language · string · required

ISO language tag accepted by Meta (en_US, tr, es_ES, pt_BR, etc.).

Example:

"en_US"

category · enum<string> · required

Meta category. Determines pricing and approval requirements.

Available options: MARKETING, UTILITY, AUTHENTICATION

Example:

"UTILITY"

waba_id · string · required

The WhatsApp Business Account id this template belongs to. The template will be submitted under this WABA.

Example:

"123456789012345"

components · object[] · required

Meta components array. Must contain exactly one BODY. May contain at most one HEADER (text/image/video/document), one FOOTER, and one BUTTONS group (max 10 buttons). Each item is a WaComponent — see oneOf variants for the exact shape required per type.

Minimum array length: 1

TEXT header. Up to 60 chars. May contain at most one {{1}} placeholder; if present, example.header_text is required.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Show child attributes

Response

201

application/json

Template submitted to Meta and stored locally. data.status is typically PENDING.

success · boolean

Example:

true

message · string

Example:

"Template created successfully"

data · object

WhatsApp message template stored locally and synced with Meta. Status reflects Meta's approval state.

Show child attributes