UC-013 — WhatsApp Template Lifecycle

Field	Value
ID	UC-013
Goal	Manage the full WhatsApp template lifecycle: creation, Meta approval, sending, editing, deletion
Channel	WhatsApp
Complexity	⭐⭐⭐ Advanced
Estimated time	25 minutes
APIs involved	`POST /api/message-server/whatsapp/templates`, `GET /whatsapp/templates`, `PATCH /whatsapp/templates/{id}`, `DELETE /whatsapp/templates/{id}`, `POST /api/message-server/whatsapp/send`

Real-world scenarios

TechStore — Welcome template: The CRM team creates a template to greet new customers with a personalized message, discount code and action buttons.
FashionOutlet — Marketing promo with tracked links: A promotional template with tracked clickable links to measure Black Friday campaign conversions.
Studio Dentistico Bianchi — Appointment reminder with buttons: A UTILITY template with buttons to confirm, reschedule or call the office directly.

Prerequisites

Before you begin, make sure you have:

Active API Key → How to get one
Sufficient credit → Check in the Qlara Dashboard
WhatsApp phoneNumberId configured

Test without costs

Add "simulation": true in the request body to validate the flow without actually sending messages and without consuming credit.

Template lifecycle

Meta approval times

Meta approval can take from a few minutes up to 24 hours. Plan template creation well in advance of your campaign.

Step-by-step guide

Step 1 — Create a template

Create a welcome template with a text header, body with placeholders, footer and buttons:

curl -X POST "https://api.qlara.ai/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "benvenuto_nuovo_cliente",
    "lang": "it",
    "category": "MARKETING",
    "headerText": "Benvenuto in TechStore!",
    "body": "Ciao {firstName}, siamo felici di averti con noi! Scopri le offerte riservate ai nuovi clienti e approfitta del codice sconto {codiceSconto} valido fino al {dataScadenza}.",
    "footer": "TechStore - Tecnologia per tutti",
    "buttons": [
      {
        "type": "URL",
        "text": "Vai alle offerte",
        "url": "https://techstore.it/offerte-benvenuto"
      },
      {
        "type": "PHONE_NUMBER",
        "text": "Chiamaci",
        "phoneNumber": "+390212345678"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Non mi interessa"
      }
    ]
  }'

Available categories:

Category	When to use	Examples
`MARKETING`	Promotions, offers, newsletters	Sales, new products, events
`UTILITY`	Transactional communications	Order confirmation, tracking, reminders
`AUTHENTICATION`	Identity verification	OTP, verification codes

Allowed placeholders

Placeholders must be contact fields: standard ones such as {firstName}, {lastName} or {city}, or the custom contact fields defined for your account, like codiceSconto and dataScadenza here. Tracked links use {shortLinkT1}–{shortLinkT4}. Any other name is rejected with 400 and INVALID_PLACEHOLDER.

Step 1b — Template with image header and tracked links

curl -X POST "https://api.qlara.ai/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo_primavera_2026",
    "lang": "it",
    "category": "MARKETING",
    "headerFormat": "IMAGE",
    "headerMediaUrl": "https://cdn.techstore.it/img/promo-primavera.jpg",
    "body": "Ciao {firstName}, i saldi di primavera sono arrivati! Fino al 30% di sconto su tutta la collezione. Clicca qui {shortLinkT1} per scoprire le offerte.",
    "footer": "Offerta valida fino al 30 aprile 2026",
    "placeholderFields": {
      "WHATSAPP": {
        "shortLinkT1": "https://techstore.it/saldi-primavera"
      }
    }
  }'

Tracked links

The {shortLinkT1} placeholder in the body is automatically replaced with a tracked short link. Define the destination URL in placeholderFields, and pass it in the placeholders of each send too (see Step 4). To track clicks on URL buttons, add "trackButtonLinks": true.

Step 1c — Reminder template with buttons

curl -X POST "https://api.qlara.ai/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promemoria_appuntamento",
    "lang": "it",
    "category": "UTILITY",
    "headerText": "Promemoria appuntamento",
    "body": "Gentile {firstName}, le ricordiamo il suo appuntamento del {dataAppuntamento} alle ore {oraAppuntamento} presso {nomeStudio}, {indirizzo}.",
    "footer": "Per modifiche, contattaci almeno 24h prima",
    "buttons": [
      {
        "type": "QUICK_REPLY",
        "text": "Confermo"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Devo spostare"
      },
      {
        "type": "PHONE_NUMBER",
        "text": "Chiama lo studio",
        "phoneNumber": "+390276543210"
      }
    ]
  }'

Step 2 — Wait for Meta approval

After creation, the template enters the PENDING state. Meta reviews it to verify compliance with its policies.

Possible statuses:

Status	Meaning
`PENDING`	Awaiting review by Meta
`APPROVED`	Approved, available for sending
`REJECTED`	Rejected (check Meta guidelines): `rejectedReason` gives Meta's reason
`PAUSED`	Paused by Meta
`DISABLED`	Disabled
`FLAGGED`	Negative feedback from recipients: at risk of being disabled
`REINSTATED`	No longer flagged or disabled
`IN_APPEAL`	Rejection under appeal
`LIMIT_EXCEEDED`	The WhatsApp Business account has reached its template limit
`LOCKED`	Locked: it cannot be edited
`ARCHIVED`	Archived
`PENDING_DELETION`, `DELETED`	Being deleted, deleted

Only APPROVED templates can be sent.

Step 3 — Check the template status

Periodically check the status:

curl -X GET "https://api.qlara.ai/api/message-server/whatsapp/templates?status=PENDING&phoneNumberId=5&page=0&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

For details on a specific template:

curl -X GET "https://api.qlara.ai/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY"

Filter parameter	Description
`category`	`MARKETING`, `UTILITY`, `AUTHENTICATION`; several values comma-separated
`status`	One or more of the statuses above, comma-separated (e.g. `PENDING,REJECTED`)
`templateId`	Up to 25 template IDs, comma-separated
`phoneNumberId`	Filter by associated phone number
`page`	Page number (0-based)
`limit`	Items per page (default 10)

The response is a page: the templates in data, plus page, limit, totalCount and totalPages.

Step 4 — Send a message with the approved template

Once the status is APPROVED, use the template to send:

curl -X POST "https://api.qlara.ai/api/message-server/whatsapp/send" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+393471234567",
    "phoneNumberId": 5,
    "template": {
      "id": 142,
      "mediaUrl": "https://cdn.techstore.it/img/promo-primavera.jpg"
    },
    "placeholders": {
      "firstName": "Marco",
      "shortLinkT1": "https://techstore.it/saldi-primavera"
    },
    "enableNotification": true,
    "campaignId": "promo-primavera-2026"
  }'

Response:

{
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": true
    }
  }
}

The API answers 202 Accepted. A template that is not APPROVED gives 400 with code 33 (WhatsApp Template not found).

Templates with tracked links in buttons

For templates with URL buttons and tracking enabled, add "trackButtonLinks": true when creating the template. The system will automatically generate a tracked link for each URL button.

Step 5 — Update a template

Edit an existing template with PATCH. The template will return to PENDING status for a new Meta review. The request replaces the whole content: send again the header and the buttons you want to keep, or they are removed:

curl -X PATCH "https://api.qlara.ai/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headerFormat": "IMAGE",
    "headerMediaUrl": "https://cdn.techstore.it/img/promo-primavera.jpg",
    "body": "Ciao {firstName}, i super saldi di primavera sono arrivati! Fino al 40% di sconto su tutta la collezione. Non perdere questa occasione!",
    "footer": "Offerta valida fino al 15 maggio 2026"
  }'

Response: 200 OK with the updated template, in PENDING status.

Re-approval

Any modification to the template resets it to PENDING status. You will need to wait for a new approval from Meta before you can use it again. Plan modifications in advance: an APPROVED template cannot be edited again within 24 hours of its last update, and its category can no longer be changed.

Step 6 — Delete a template

When a template is no longer needed:

curl -X DELETE "https://api.qlara.ai/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY"

Template fields

Field	Type	Required	Description
`name`	`string`	Yes	Template name, 3–512 characters: Meta receives it in lowercase, with every character other than letters, digits and underscores turned into `_` (`slug`)
`lang`	`string`	Yes	Language code (`it`, `en`, `es`, etc.)
`category`	`string`	Yes	`MARKETING`, `UTILITY`, `AUTHENTICATION`
`body`	`string`	Yes*	Text with `{fieldName}` placeholders, max 1028 characters (*not allowed for `AUTHENTICATION`)
`headerText`	`string`	No	Header text, max 60 characters
`headerFormat`	`string`	No	`TEXT`, or a media header: `IMAGE`, `VIDEO`, `DOCUMENT`
`headerMediaUrl`	`string`	No	Media URL for the header
`headerMediaGalleryId`	`integer`	No	Media of your media gallery for the header (alternative to `headerMediaUrl`)
`footer`	`string`	No	Footer text, max 60 characters
`buttons`	`array`	No	Interactive buttons
`otpExpirationMinutes`	`integer`	`AUTHENTICATION` only	Code validity in minutes
`placeholderFields`	`object`	No	Tracked link definitions
`trackButtonLinks`	`boolean`	No	Track clicks on URL buttons

Button types

Type	Fields	Description
`URL`	`text`, `url`	Opens a URL in the browser
`PHONE_NUMBER`	`text`, `phoneNumber`	Initiates a phone call
`QUICK_REPLY`	`text`	Predefined quick reply

Behind the scenes

The WhatsApp template approval flow involves both the Qlara platform and Meta:

Creation -- The template is sent to Meta via the Business API. Meta takes it in for review.
Meta Review -- Meta verifies that the template complies with its policies (no misleading content, spam, or terms violations). The review can be automatic (minutes) or manual (up to 24h).
Status notification -- The Qlara platform receives the status update from Meta and makes it available through the API.
Sending -- When the template is APPROVED, you can use it to start conversations or send messages outside the 24h window. Placeholders are replaced at send time.
Update -- A PATCH modifies the template and resubmits it to Meta. The status returns to PENDING until the new approval.
Name rule -- Meta accepts only lowercase letters, numbers and underscores in the template name. The platform converts name into the slug sent to Meta (lowercase, with every other character turned into _), and rejects a name that already exists on the number or that leaves no letters or digits.
Phone number association -- The phoneNumberId in the creation query string associates the template with a specific WhatsApp Business number. Use GET /whatsapp/phone-numbers to get the list of available numbers.

Expected result

Aspect	Detail
Action completed	WhatsApp template created, approved by Meta, used for sending
Channel used	WhatsApp
Delivery confirmation	Via webhook (statusCode: 3) within 5-60 sec

Common errors

Problem	Probable cause	Solution
HTTP `401`	Missing or invalid API Key	Check `X-Api-Key` header
`accepted: false`	Invalid number (see `reasons`)	Verify E.164 format
Template `REJECTED` by Meta	Content violates Meta policies (`rejectedReason` gives Meta's reason)	Review Meta guidelines; avoid aggressive language, misleading content, or missing opt-out
HTTP `400` — `TEMPLATE_NAME_ALREADY_EXISTS` or `INVALID_TEMPLATE_NAME`	The converted name already exists on the number, or has no letters or digits	Choose another name
HTTP `400` — `INVALID_PLACEHOLDER`	A placeholder is not a contact field of your account	Use contact fields, or `{shortLinkT1}`–`{shortLinkT4}` for tracked links
HTTP `429`	The template limit of your subscription is reached	Delete unused templates or upgrade the subscription
Template stuck in `PENDING`	Meta review taking longer than expected	Wait up to 24 hours; if still pending, check Meta Business Manager for details

Next steps

WhatsApp Templates Guide -- Complete reference on WhatsApp templates
WhatsApp API Guide -- Sending messages and managing phone numbers
UC-012: RCS Template Workflow -- Compare with the RCS template flow (no external approval)
UC-009: Two-Way Conversation -- Handle replies to sent templates
UC-010: Scheduled Messages -- Schedule WhatsApp template sending

Real-world scenarios​

Prerequisites​

Template lifecycle​

Step-by-step guide​

Step 1 — Create a template​

Step 1b — Template with image header and tracked links​

Step 1c — Reminder template with buttons​

Step 2 — Wait for Meta approval​

Step 3 — Check the template status​

Step 4 — Send a message with the approved template​

Step 5 — Update a template​

Step 6 — Delete a template​

Template fields​

Button types​

Expected result​

Common errors​

Next steps​