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/Object | Data Type | Constraints | Description |
---|---|---|---|
name | String | Required | Unique template name. Used to refer in other APIs |
language | Enumerated | Required | Use one given in the Language Code List |
category | Enumerated | Required | Use one among 3 categories listed here. |
components | Object | Required | Use 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/Object | Data Type | Constraints | Description |
---|---|---|---|
body | Object | Required | It defines a textual body content |
body.text | String | Required | Text Contents. May have {{placeholder}} variables numbered by instances as {{1}} , {{2}} and so on. |
body.example | Array of Strings | Optional | Data Example for each Placeholder variable in the same order they appear in body.text . Its required if placeholders are used in body.text |
footer | Object | Optional | It defines a textual footer content |
footer.text | String | Optional | Text Contents. May have {{placeholder}} variables numbered by instances as {{1}} , {{2}} and so on. |
footer.example | Array of Strings | Optional | Data 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
Key | Data Type | Description |
---|---|---|
id | String | Template ID. Notifications will be received at Webhook using this ID. |
status | String | Status. e.g. PENDING, REJECTED. |
category | String | Template 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/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use HEADER |
format | String | Required | Use TEXT |
text | String | Required | Header Text Content |
Body Component Object Explanation:
Key/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use BODY |
text | String | Required | Text Contents. May have {{placeholder}} variables numbered by instances as {{1}} , {{2}} and so on. |
example | Object | Required | Required if placeholder variables are used |
body_text | Array | Required | Required if placeholder variables are used in body |
Footer Component Object Explanation:
Key/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use FOOTER |
text | String | Required | Text Contents. May have {{placeholder}} variables numbered by instances as {{1}} , {{2}} and so on. |
example | object | Required | Required if placeholder variables are used |
footer_text | Array | Required | Required 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.
- 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": "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/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use HEADER |
format | Enumerated | Required | Type of Rich Media. Use either IMAGE , VIDEO or DOCUMENT as String for Rich Media Content. |
example | Object | Required | Media Example. Use publicly accessible related media content URL over https. Rich media must comply with the specification. |
header_handle | Array | Required | One 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/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use BUTTONS |
buttons | Array | Required | It defines one or more quick reply button. Each object in is a button definition |
Button Object Explanation: For each button only.
Key/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Type of button. Use QUICK_REPLY |
text | String | Required | Label 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/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use BUTTONS |
buttons | Array | Required | It 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/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use PHONE_NUMBER |
text | String | Required | Label for the button |
phone_number | Sting | Required | Phone 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/Object | Data Type | Constraints | Description |
---|---|---|---|
type | String | Required | Use URL |
text | String | Required | Label for the Button |
url | String | Required | URL. Placeholder may be used for whole URL or to cover part of it |
example | Array | Optional | Required 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.
Parameter | Data Type | Description |
---|---|---|
name | String | Template name. Returns single Template |
category | String | Template Category. Enumerated values. Returns multiple Templates for given category |
template_id | String | Template ID. Returns single Template. |
status | String | Template 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=APPROVEDAuthorization: Bearer Token / BasicContent-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/423432324424Authorization: Bearer Token / BasicContent-Type: application/json
{"success": true}