WhatsApp Templates

WhatsApp templates are messages pre-approved by Meta that can be sent at any time, even outside the 24-hour window. They are required to initiate a conversation with a user.

Endpoint

Method	Path	Description
GET	/api/message-server/whatsapp/templates	List templates
GET	/api/message-server/whatsapp/templates/{id}	Template details
POST	/api/message-server/whatsapp/templates?phoneNumberId={id}	Create template
PATCH	/api/message-server/whatsapp/templates/{id}	Update template
DELETE	/api/message-server/whatsapp/templates/{id}	Delete template

The phoneNumberId query parameter in the creation request specifies which WhatsApp Business number to associate the template with.

Template creation fields

Field	Type	Req.	Description
name	string	Yes	Template name (snake_case, lowercase letters, numbers, and underscores only)
lang	string	Yes	Language code (e.g. it, en, es)
category	string	Yes	Category: MARKETING, UTILITY, AUTHENTICATION
body	string	Yes	Body text with placeholders {placeholderName}
headerText	string	No	Header text (exclusive with headerFormat)
headerFormat	string	No	Media header format: IMAGE, VIDEO, DOCUMENT
headerMediaUrl	string	No	Media URL for the header
footer	string	No	Footer text
buttons	array	No	List of interactive buttons
placeholderFields	object	No	Tracked link definition
trackButtonLinks	boolean	No	Track clicks on URL buttons

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

Template statuses

Status	Meaning
APPROVED	Approved by Meta, available for sending
PENDING	Awaiting review by Meta
REJECTED	Rejected by Meta (check the guidelines)
PAUSED	Paused
DISABLED	Disabled

Buttons

Field	Type	Req.	Description
type	string	Yes	Type: URL, PHONE_NUMBER, QUICK_REPLY
text	string	Yes	Displayed text
url	string	URL only	URL to open
phoneNumber	string	PHONE_NUMBER only	Number to call

Tracked links

Tracked links allow you to monitor user clicks.

In the template body

Insert the {shortLinkT1} placeholder in the text and define the actual URL in placeholderFields:

{
  "body": "Ciao {firstName}, clicca qui {shortLinkT1} per la tua offerta.",
  "placeholderFields": {
    "WHATSAPP": {
      "shortLinkT1": "https://example.com/offerta"
    }
  }
}

In buttons

Add "trackButtonLinks": true to the request:

{
  "buttons": [
    { "type": "URL", "text": "Apri offerta", "url": "https://example.com/offerta" }
  ],
  "trackButtonLinks": true
}

Examples

Simple text template

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerText": "Welcome",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi",
  "footer": "Per info visita il sito"
}

Template with buttons

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerText": "Welcome",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi",
  "footer": "Per info visita il sito",
  "buttons": [
    { "type": "URL", "text": "Apri il sito", "url": "https://agiletelecom.com/" },
    { "type": "PHONE_NUMBER", "text": "Chiamaci", "phoneNumber": "+39 123123123" },
    { "type": "QUICK_REPLY", "text": "Voglio essere contattato" }
  ]
}

Template with image header

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi",
  "footer": "Per info visita il sito"
}

Template with tracked link in body

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi. Clicca qui {shortLinkT1} per accedere all'area riservata.",
  "footer": "Per info visita il sito",
  "placeholderFields": {
    "WHATSAPP": {
      "shortLinkT1": "https://www.example.com/landing-page"
    }
  }
}

Template with tracked link in button

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi.",
  "footer": "Per info visita il sito",
  "buttons": [
    { "type": "URL", "text": "Apri il sito", "url": "https://agiletelecom.com/" }
  ],
  "trackButtonLinks": true
}

Template list filters

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

Updating

With PATCH /templates/{id} you can update only the fields you want to modify. The template will return to PENDING status for re-approval by Meta.