Message Template Management with WhatsApp Business API

WhatsApp Business Platform mandates that a you must use a pre-approved message template to send a message to a user to start a Business Initiated Conversation (BIC), There is no further restriction in messaging. Any message can be send to a user once responded by the user or in response to User Initiated Conversation (UIC).

Overview

Templates are pre-defined messages that have been approved by Meta for use in business messaging. They can be of different types and are used to send messages directly to users, in batches as part of a campaign, or as part of an interactive business application workflow.

Templates need to be approved by Meta before the use. This usually happens quickly, within a few minutes of submission. It is important to note that only approved templates can be used to send message to start a Business Initiated Conversation.

To know more on templates, click here.

Create Template API

To create a Template with different type of content, a request is posted to WhatsApp using API Call. Subsequently the Template gets approved and you get notified over Webhook.

Note that each template needs to have a name, a template category and language code. A template name must bee unique within a given language code. It also means that 2 templates can be created using same name and different language code.

Template with Text Contents

This is to submit request for a new Template with Text Content.

  • API Route: https://api.enablex.io/whatsapp/v1/templates
  • Request: POST
  • Authorization: Bearer Token / Basic
  • JSON Payload:
{
"name": "{template name}",
"category": "{template category}",
"language": "{lang code}",
"components": [
{
"type": "BODY",
"text": "Hello {{1}}, this is a template with header and footer text.",
"example": {
"body_text": [
[
"John"
]
]
}
},
{
"type": "FOOTER",
"text": "{header text}"
}
]
}

JSON Payload

Common Key/Objects doe all type of Templates

Key/ObjectData TypeConstraintsDescription
nameStringRequiredUnique template name. Used to refer in other APIs
languageEnumeratedRequiredUse one given in the Language Code List
categoryEnumeratedRequiredUse one among 3 categories listed here.
componentsObjectRequiredUse components header, footer, body, buttons to define different type of templates. For Text Templates, use body and footer.

Component Object Explanation: For Template with Text Contents only

Key/ObjectData TypeConstraintsDescription
bodyObjectRequiredIt defines a textual body content
body.textStringRequiredText Contents. May have {{placeholder}} variables numbered by instances as {{1}}, {{2}} and so on.
body.exampleArray of StringsOptionalData Example for each Placeholder variable in the same order they appear in body.text. Its required if placeholders are used in body.text
footerObjectOptionalIt defines a textual footer content
footer.textStringOptionalText Contents. May have {{placeholder}} variables numbered by instances as {{1}}, {{2}} and so on.
footer.exampleArray of StringsOptionalData Example for each Placeholder variable in the same order they appear in footer.text. Its required if placeholders are used in footer.text

JSON Response

Response JSON Example# 1: Template Request is accepted and pending for approval.

{
"id": "755147549669633",
"status": "PENDING",
"category": "MARKETING"
}

Response JSON Example# 1: Template Request is rejected. Not accepted.

{
"id": "1179591852722215",
"status": "REJECTED",
"category": "MARKETING"
}

Response JSON Explanation

KeyData TypeDescription
idStringTemplate ID. Notifications will be received at Webhook using this ID.
statusStringStatus. e.g. PENDING, REJECTED.
categoryStringTemplate Category

Error Response: Error in JSON Payload found

{
"message": "Invalid parameter",
"type": "OAuthException",
"code": 100,
"error_subcode": 2388024,
"is_transient": false,
"error_user_title": "",
"error_user_msg": "",
"fbtrace_id": "AiDnfOO7tdoa9WydqsXJPCm"
}

How to use data example ?

If body.text or footer.text has {{placeholder}} variable(s), data example must be given for each placeholder. WhatsApp Template Approval is always based on a complete readable contents with merged data given in example.

The example array should contain as many “quoted strings” as the number of placeholders used in the same order. E.g. The first example “string” will be used for {{1}} placeholder and 2nd string will be used for {{2}} placeholder and so on.

{
"body": {
"text": "Hi {{1}}. Your Account is being migrated to {{2}}",
"example": [
"John",
"AWS"
]
}
}

In the Code sample above, “John” will be used in place of {{1}} and “AWS” will be used for {{2}}.

Template with Text Contents & Header

This is to submit request for a new Template with Text Content and Header Text

  • API Route: https://api.enablex.io/whatsapp/v1/templates
  • Request: POST
  • Authorization: Bearer Token / Basic
  • JSON Payload:
{
"name": "{template name}",
"category": "{template category}",
"language": "{lang code}",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "{header text}"
},
{
"type": "BODY",
"text": "Hello {{1}}, this is a template with header and footer text.",
"example": {
"body_text": [
[
"John"
]
]
}
},
{
"type": "FOOTER",
"text": "{header text}"
}
]
}

JSON Payload

For common Key/Objects for all type of Templates, refer explanation given above against "Template with Text Contents"

Header Component Object Explanation

Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse HEADER
formatStringRequiredUse TEXT
textStringRequiredHeader Text Content

Body Component Object Explanation:

Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse BODY
textStringRequiredText Contents. May have {{placeholder}} variables numbered by instances as {{1}}, {{2}} and so on.
exampleObjectRequiredRequired if placeholder variables are used
body_textArrayRequiredRequired if placeholder variables are used in body

Footer Component Object Explanation:

Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse FOOTER
textStringRequiredText Contents. May have {{placeholder}} variables numbered by instances as {{1}}, {{2}} and so on.
exampleobjectRequiredRequired if placeholder variables are used
footer_textArrayRequiredRequired if placeholder variables are used in footer

How to use data example?

If text in body and footer has {{placeholder}} variable(s), data example must be given for each placeholder. WhatsApp Template Approval is always based on a complete readable contents with merged data given in example.

The example array should contain as many “quoted strings” as the number of placeholders used in the same order. E.g. The first example “string” will be used for {{1}} placeholder and 2nd string will be used for {{2}} placeholder and so on.

{ "example": {
"body_text": [
[
"John"
]
]
}
}

In the Code sample above, “John” will be used in place of {{1}} and “AWS” will be used for {{2}}.

Template with Rich Media Contents

This is to submit request for a new Template with Rich Media Contents, i.e. Template with Image, Video and Document.

{
"name": "{template name}",
"category": "{template category}",
"language": "{lang code}",
"components": [
{
"type": "HEADER",
"format": "IMAGE/VIDEO/DOCUMENT",
"example": {
"header_handle": [
{sample media url}
]
}
},
{
"type": "BODY",
"text": "Your physics course {{1}}, is now available in preview?",
"example": {
"body_text": [
[
"Gravity"
]
]
}
},
{
"type": "FOOTER",
"text": "{footer text}"
}
]
}

JSON Payload

For common Key/Objects for all type of Templates, refer explanation given above against "Template with Text Contents"

Component Object Explanation: For Template with Rich Media Contents only. The header component defines type of rich media and a example given with publicly hosted https URL related to the same type of media.

Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse HEADER
formatEnumeratedRequiredType of Rich Media. Use either IMAGE, VIDEO or DOCUMENT as String for Rich Media Content.
exampleObjectRequiredMedia Example. Use publicly accessible related media content URL over https. Rich media must comply with the specification.
header_handleArrayRequiredOne or more Public URL for the Media File

Note:

  • Response JSON is similar to the example given above against Text Templates.
  • Status Updates will be notified through Webhook.

How to use data example for Rich Media?

For a Template with Rich Media Content, you must give an example of related type of media file, i.e. profile Image URL for image, Video URL for video type of rich media templates.

The example file must be hosted on a publicly accessible https URL and must conform to allowed Rich Media Specification.

{
"header": {
"type": "image",
"example": "https://public-url/image.jpg"
}
}

Interactive Template with Quick Reply Buttons

This is to submit request for a new Template for with interactive button for quick reply. When a messages is set using these buttons, customer/user can click on any of the buttons to respond.

  • API Route: https://api.enablex.io/whatsapp/v1/templates
  • Request: POST
  • Authorization: Bearer Token / Basic
  • JSON Payload:
{
"name": "{template name}",
"category": "{template category}",
"language": "{lang code}",
"components": [
{
"type": "BODY",
"text": "Hello dear Mr. {{1}}, would you like to renew your membership?",
"example": {
"body_text": [
[
"John"
]
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "{button label}"
},
{
"type": "QUICK_REPLY",
"text": "{button label}"
}
]
}
]
}

JSON Payload

For common Key/Objects for all type of Templates, refer explanation given above against "Template with Text Contents"

Component Object Explanation: For Template with Quick Reply Buttons only. The button component defines one or more quick reply button.

Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse BUTTONS
buttonsArrayRequiredIt defines one or more quick reply button. Each object in is a button definition

Button Object Explanation: For each button only.

Key/ObjectData TypeConstraintsDescription
typeStringRequiredType of button. Use QUICK_REPLY
textStringRequiredLabel for the Button

Note:

  • Response JSON is similar to the example given above against Text Templates.
  • Status Updates will be notified through Webhook.

Interactive Template with Call-to-Action Buttons

This is to submit request for a new Template for Call-to-Action interactive buttons with multiple components. These buttons are executed on the phone itself, e.g. Click to go to a Website, Click to dial-out a Phone number.

  • API Route: https://api.enablex.io/whatsapp/v1/templates
  • Request: POST
  • Authorization: Bearer Token / Basic
  • JSON Payload:
{
"name": "{template name}",
"category": "{template category}",
"language": "{lang code}",
"components": [
{
"type": "BODY",
"text": "Hello dear Mr. {{1}}, would you like to renew your membership?",
"example": {
"body_text": [
[
"John"
]
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "PHONE_NUMBER",
"text": "{button label}",
"phone_number": "{phone number}"
},
{
"type": "URL",
"text": "{button label}",
"url": "{url with placeholder i.e. https://yoursite.com/{{1}} }",
"example": [
"{example url}"
]
}
]
}
]
}

JSON Payload

For common Key/Objects for all type of Templates, refer explanation given above against "Template with Text Contents"

Component Object Explanation: For Template with Call to Action Buttons only. The button component defines one or more action buttons.

Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse BUTTONS
buttonsArrayRequiredIt defines one or more quick reply button. Each object in is a button definition

Phone Call Button Object Explanation: For Dial-Out a Phone Number

{
"type": "PHONE_NUMBER",
"text": "{button label}",
"phone_number": "{phone number}"
}
Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse PHONE_NUMBER
textStringRequiredLabel for the button
phone_numberStingRequiredPhone number to to dial on click of the the button. Use with Country Code (Without leading + or 00)

URL Button Object Explanation: For Click to visit a Website

{
"type": "URL",
"text": "{button label}",
"url": "{url with placeholder i.e. https://yoursite.com/{{1}} }",
"example": [
"{placeholder content}"
]
}
Key/ObjectData TypeConstraintsDescription
typeStringRequiredUse URL
textStringRequiredLabel for the Button
urlStringRequiredURL. Placeholder may be used for whole URL or to cover part of it
exampleArrayOptionalRequired if placeholder is used in URL. One or may “Strings” may be used separated by Comma.

Note:

  • Response JSON is similar to the example given above against Text Templates.
  • Status Updates will be notified through Webhook.

Get list of Templates

This request retrieves a list of templates using the specified API routes, which support filtering options through query string parameters.

  • API Route: https://api.enablex.io/whatsapp/v1/templates
  • Request: GET
  • Authorization: Bearer Token / Basic
  • Query String Parameters: Used as filter. API Returns full list if called without filter.
ParameterData TypeDescription
nameStringTemplate name. Returns single Template
categoryStringTemplate Category. Enumerated values. Returns multiple Templates for given category
template_idStringTemplate ID. Returns single Template.
statusStringTemplate Status. Enumerated values: PENDING, APPROVED, REJECTED. Returns multiple Templates for given status

Request Example: To get all templates with APPROVED status, using a Query String parameter.

GET https://api.enablex.io/whatsapp/v1/templates?status=APPROVED
Authorization: Bearer Token / Basic
Content-Type: application/json

Response Example: Returns in Array of Objects (Each object is a Template) even if it finds a single template to return.

[
{
"status": "APPROVED",
"business_phone": "918800899287",
"wa": {
"template_id": "558534749704350"
},
"template": { /*The Payload used to create the Template */ },
"track": {
"posted": {
"date": "2023-03-23T09:10:26.974Z"
},
"approved": {
"date": "2023-03-23T09:18:34.055Z"
}
}
}
]

Delete Template

This request deletes a a given Template name. The API call deletes all templates with the same name across all languages.

  • API Route: https://api.enablex.io/whatsapp/v1/templates/:template_name
  • Request: DELETE
  • Authorization: Bearer Token / Basic
  • URL Embedded Template Name
DELETE https://api.enablex.io/whatsapp/v1/templates/423432324424
Authorization: Bearer Token / Basic
Content-Type: application/json
{
"success": true
}