WhatsApp Business API – Message Templates

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
Create Template
Get List of Templates
Delete Template

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.

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.

Templates need to be approved by Meta before the use. This usually happens quickly, within a few minutes. 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 with Basic 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]"
    }
  ]
}

Payload Explanation: Common Key/Objects for all type of Templates

Key/Object	Data Type	Constraints	Description
n`ame`	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`

Response JSON: Accepted and pending for approval.

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

Response JSON: 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}}.

Create Template with Text Contents with 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]"
    }
  ]
}

Payload Explanation: For common Key/Objects for all type of Templates, refer explanation given above.

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`	Array	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`	Array	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.

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

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

Create 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}"
    }
  ]
}

Payload Explanation: For common Key/Objects for all type of Templates, refer explanation given above.

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 media specification.

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

Create 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}"
        }
      ]
    }
  ]
}

Payload Explanation: For common Key/Objects for all type of Templates, refer explanation given above.

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	Data Type	Constraint	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.

Create 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}"
          ]
        }
      ]
    }
  ]
}

Payload Explanation: For common Key/Objects for all type of Templates, refer explanation given above.

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	Data Type	Constraint	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	Data Type	Constraint	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 – To get all 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=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.

API Route: https://api.enablex.io/whatsapp/v1/templates/:template_name – To delete templates ofall languages with the same name.
Request: DELETE
Authorization: Bearer Token / Basic
URL Embedded Template Name

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

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

{
  "success": true
}

Table of Contents

Overview

Create Template with Basic Text Contents

How to use data example?

Create Template with Text Contents with Header

How to use data example?

Create Template with Rich Media Contents

How to use data example for Rich Media?

Create Interactive Template with Quick Reply Buttons

Create Interactive Template with Call-to-Action Buttons

Get list of Templates

Delete Template