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

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

Template lifecycle

:::warning 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://lora-api.agiletelecom.com/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

Step 1b — Template with image header and tracked links

curl -X POST "https://lora-api.agiletelecom.com/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"
      }
    }
  }'

:::tip Tracked links The {shortLinkT1} placeholder in the body is automatically replaced with a tracked short link. Define the destination URL in placeholderFields. To track clicks on URL buttons, add "trackButtonLinks": true. :::

Step 1c — Reminder template with buttons

curl -X POST "https://lora-api.agiletelecom.com/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)
`PAUSED`	Paused by Meta
`DISABLED`	Disabled

Step 3 — Check the template status

Periodically check the status:

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

For details on a specific template:

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

Filter parameter	Description
`category`	`MARKETING`, `UTILITY`, `AUTHENTICATION`
`status`	`APPROVED`, `PENDING`, `REJECTED`, `PAUSED`, `DISABLED`
`phoneNumberId`	Filter by associated phone number
`page`	Page number (0-based)
`size`	Items per page

Step 4 — Send a message with the approved template

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

curl -X POST "https://lora-api.agiletelecom.com/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",
      "codiceSconto": "SPRING20",
      "dataScadenza": "30 aprile 2026"
    },
    "enableNotification": true,
    "campaignId": "promo-primavera-2026"
  }'

Response:

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

:::info 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:

curl -X PATCH "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

:::warning 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. :::

Step 6 — Delete a template

When a template is no longer needed:

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

Template fields

Field	Type	Required	Description
`name`	`string`	Yes	Template name (snake_case, lowercase, numbers and underscores)
`lang`	`string`	Yes	Language code (`it`, `en`, `es`, etc.)
`category`	`string`	Yes	`MARKETING`, `UTILITY`, `AUTHENTICATION`
`body`	`string`	Yes	Text with `{fieldName}` placeholders
`headerText`	`string`	No	Header text (mutually exclusive with `headerFormat`)
`headerFormat`	`string`	No	Media header: `IMAGE`, `VIDEO`, `DOCUMENT`
`headerMediaUrl`	`string`	No	Media URL for the header
`footer`	`string`	No	Footer text
`buttons`	`array`	No	Interactive buttons
`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 -- The name field must be in snake_case with only lowercase letters, numbers and underscores. This is a Meta requirement.
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`	Insufficient credit or invalid number	Check credit; verify E.164 format
Template `REJECTED` by Meta	Content violates Meta policies	Review Meta guidelines; avoid aggressive language, misleading content, or missing opt-out
HTTP `400` — Invalid template name	Name contains uppercase or special characters	Use `snake_case` with only lowercase letters, numbers, and underscores
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​