# WhatsApp Templates API Management

<p class="callout info">The template APIs allow you to create, delete, and fetch templates</p>

#### The templates API supports the following methods and are client specific

- GET
- POST
- DELETE

##### <span style="background-color: rgb(191, 237, 210);">Get all templates</span>

```bash
curl --location 'https://api.versal.one/<client-id>/templates' \
--header 'Authorization: Bearer <client-token>'
```

##### <span style="background-color: rgb(191, 237, 210);">Get a template by name</span>

```bash
curl --location 'https://api.versal.one/<client-id>/templates?name=order_delivery_1' \
--header 'Authorization: Bearer <client-token>'
```


##### <span style="background-color: rgb(191, 237, 210);">Create a template</span>

To create a template - the following components are required

> - name - template name <span style="background-color: rgb(248, 202, 198);">\[cannot contain Upper case, space, special characters\]</span> can contain underscore "\_" and a max of 25 characters
> - language - en \[English\], en\_US \[English US\]. [Click here](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages/) for the complete list
> - category - Marketing/Utility
> - components - Header, Body, Footer
> 
> for more details [check the official documentation](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/) on the META website

```bash
curl --location 'https://api.versal.one/<client-id>/templates' \
--header 'Authorization: Bearer <client-token>' \
--data '{
    "name": "order_delivery_1",
    "language": "en_US",
    "category": "Marketing",
    "components": [
        {
            "type": "HEADER",
            "format": "Text",
            "text": "header text"
        },
        {
            "type": "BODY",
            "text": "This is a {{1}}",
            "example": {
                "body_text": [
                    [
                        "random text"
                    ]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "lasadoasi"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "PHONE_NUMBER",
                    "text": "Call",
                    "phone_number": "+918897229166"
                }
            ]
        }
    ]
}'
```

```bash
{
    "message": "Template created successfully",
    "response_text": "{\"id\":\"1179134613392693\",\"status\":\"APPROVED\",\"category\":\"MARKETING\"}",
    "status": "200"
}
```

# Template Components

Templates are made up of four primary components which you define when you create a template: header, body, footer, and buttons. The components you choose for each of your templates should be based on your business needs. The only required component is the body component.

Some components support variables, whose values you can supply when using the Cloud API or On-Premises API to send the template in a template message. If your templates use variables, you must include sample variable values upon template creation.

## Headers

Headers are optional components that appear at the top of template messages. Headers support text, media (images, videos, documents), and locations.

All templates are limited to one header component

### Text Headers

You can choose to add header text to your message template. The message text in the header component accepts parameters for programmatic configuration.

Text parameters can be configured in one of two formats:

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-positional%C2%A0%E2%80%94-pass-in"><div class="_4-u3 _588p">- **Positional** — Pass in an array of parameters that correspond to numeric positions in the body text with examples 
    - For example: `“Hello John, your account balance is {{1}}” | [ “$1,000” ]`
- **Named** — Pass in JSON objects that contain a parameter name and examples 
    - For example: `{ "param_name": "account_balance", "example": "$1,000" }`

  
</div></div>#### Component Syntax

Add this header component object into the `”components”[]` object array when calling the `POST <WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates` endpoint. Substitute the placeholder properties below using the properties table.

```
{
  "type": "HEADER",
  "format": "TEXT",
  "text": "<HEADER_TEXT>",

  "example": {
    "header_text": [
       // You must provide one of the inputs below when the <HEADER_TEXT> string contains parameters
       <POSITIONAL_PARAM_EXAMPLES>
       <BODY_TEXT_NAMED_PARAMS>
    ]
  }
}
```

#### Properties

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-placeholder-descript"><div class="_4-u3 _588p">  
<div class="_57-c"><table class="_4-ss _5k9x" style="width: 100.002%;"><thead><tr><th style="width: 15.9699%;">Placeholder</th><th style="width: 46.9607%;">Description</th><th style="width: 37.0598%;">Example Value</th></tr></thead><tbody class="_5m37" id="bkmrk-%3Cheader_text%3E-string"><tr class="row_0"><td style="width: 15.9699%;">`<HEADER_TEXT>`

</td><td style="width: 46.9607%;">*`String`* | **Required**

Plain text string. Can support 1 parameter.

If this string contains parameters, you must include the `example` property and example parameter values as shown in `<POSITIONAL_PARAM_EXAMPLES>` and `<HEADER_TEXT_NAMED_PARAMS>` below.

60 character maximum.

</td><td style="width: 37.0598%;">`“Our Holiday sale starts December 1st!”`

`“Our new sale starts {{1}}”`

`“Our new sale starts {{sale_start_date}}!”`

</td></tr><tr class="row_1 _5m29"><td style="width: 15.9699%;">`<POSITIONAL_PARAM_EXAMPLES>`

</td><td style="width: 46.9607%;">*`[String]`* | *Optional*

Required when using positional parameters in your header text.

Array of `String` in which each string is meant to illustrate the text likely to be passed in as a parameter during message send time, for example a bank account balance, or a customer name.

The number of strings must match the number of variables included in the string.

</td><td style="width: 37.0598%;">`["December 1st"]`

</td></tr><tr class="row_2"><td style="width: 15.9699%;">`<HEADER_TEXT_NAMED_PARAMS>`

</td><td style="width: 46.9607%;">*`[JSON Object]`* | *Optional*

Required when using named variables in your header text.

Array of JSON objects that contain `param_name` and `example` strings.

- `“param_name”` — Your custom parameter name. Must be lowercase letters and underscores only.
- `“example”` — The illustrative sample text for the parameter.

</td><td style="width: 37.0598%;">```
[{
 "param_name": "sale_start_date",
 "example": "December 1st"
}]
          
```

</td></tr></tbody></table>

</div>  
</div></div>#### Positional Parameter Example

```
{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our new sale starts {{1}}!",
  "example": {
    "header_text": [
      "December 1st"
    ]
  }
}
```

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-"><div class="_4-u3 _588p">  
</div></div>#### Named Parameter Example

```
{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our new sale starts {{sale_start_date}}!",
  "example": {
    "header_text_named_params": [
      {
        "param_name": "sale_start_date",
        "example": "December 1st"
      }
    ]
  }
}
```

### Media Headers

Media headers can be an image, video, or a document such as a PDF. All media must be uploaded with the [Resumable Upload API](https://developers.facebook.com/docs/graph-api/guides/upload). The syntax for defining a media header is the same for all media types.

#### Syntax

```
{
  "type": "HEADER",
  "format": "<FORMAT>",
  "example": {
    "header_handle": [
      "<HEADER_HANDLE>"
    ]
  }
}
```

#### Properties

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-placeholder-descript-1"><div class="_4-u3 _588p">  
<div class="_57-c"><table class="_4-ss _5k9x"><thead><tr><th>Placeholder</th><th>Description</th><th>Example Value</th></tr></thead><tbody class="_5m37" id="bkmrk-%3Cformat%3E-indicates-m"><tr class="row_0"><td>`<FORMAT>`

</td><td>Indicates media asset type. Set to `IMAGE`, `VIDEO`, or `DOCUMENT`.

</td><td>`IMAGE`

</td></tr><tr class="row_1 _5m29"><td>`<HEADER_HANDLE>`

</td><td>Uploaded media asset handle. Use the [Resumable Upload API](https://developers.facebook.com/docs/graph-api/guides/upload) to generate an asset handle.

</td><td>`4::aW...`

</td></tr></tbody></table>

</div></div></div>#### Example

```
{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": [
      "4::aW..."
    ]
  }
}
```

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk--1"><div class="_4-u3 _588p">  
</div></div>## Body

The body component represents the core text of your message template and is a text-only template component. It is required for all templates.

The message text in the body component accepts parameters for programmatic configuration.

Text parameters can be configured in one of two formats:

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-positional%C2%A0%E2%80%94-pass-in-1"><div class="_4-u3 _588p">- **Positional** — Pass in an array of numbered positional parameters that correspond to numeric positions in the body text with examples 
    - For example: `“Hello {{1}}, your account balance is {{2}}” | [ “John”, “$1,000” ]`
- **Named** — Pass in JSON objects that contain a parameter name and examples 
    - For example: `{ "param_name": "order_id", "example": "335628"}`

</div></div>All templates are limited to one body component.

### Component Syntax

Add this body component object into the `”components”[]` object array when calling the `POST <WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates` endpoint. Substitute the placeholder properties below using the properties table.

```
{
  "type": "body",
  "text": "<BODY_TEXT>",
  "example": {
    "body_text": [
      [
       // You must provide one of the inputs below when the <BODY_TEXT> string contains parameters
       <POSITIONAL_PARAM_EXAMPLES>
       <BODY_TEXT_NAMED_PARAMS>
      ]
    ]
  }
}
```

### Properties

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-placeholder-descript-2"><div class="_4-u3 _588p"><div class="_57-c"><table class="_4-ss _5k9x" style="width: 100.002%;"><thead><tr><th style="width: 18.1129%;">Placeholder</th><th style="width: 43.8598%;">Description</th><th style="width: 38.0178%;">Example Value</th></tr></thead><tbody class="_5m37" id="bkmrk-%3Cheader_text%3E-string-1"><tr class="row_0"><td style="width: 18.1129%;">`<HEADER_TEXT>`

</td><td style="width: 43.8598%;">*`String`* | **Required**

Plain text string. Can support multiple parameters.

If this string contains parameters, you must include the `example` property and example parameter values as shown in `<POSITIONAL_PARAM_EXAMPLES>` and `<BODY_TEXT_NAMED_PARAMS>` below.

1024 character maximum.

</td><td style="width: 38.0178%;">`“Shop our Holiday sale now!”`

`“Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.”`

`“Your {{order_id}}, is ready {{customer_name}}”`

</td></tr><tr class="row_1 _5m29"><td style="width: 18.1129%;">`<POSITIONAL_PARAM_EXAMPLES>`

</td><td style="width: 43.8598%;">*`[String]`* | *Optional*

Required when using positional parameters in your body text.

Array of string in which each string is meant to illustrate the text likely to be passed in as a parameter during message send time, for example a bank account balance, or a customer name.

The number of strings must match the number of variables included in the string.

</td><td style="width: 38.0178%;">`["the end of August","25OFF","25%"]`

</td></tr><tr class="row_2"><td style="width: 18.1129%;">`<BODY_TEXT_NAMED_PARAMS>`

</td><td style="width: 43.8598%;">*`[JSON Object]`* | *Optional*

Required when using named variables in your body text.

Array of JSON objects that contain `param_name` and `example` strings.

- `“param_name”` — Your custom parameter name. Must be lowercase letters and underscores only.
- `“example”` — The illustrative sample text for the parameter.

</td><td style="width: 38.0178%;">```
[{
 "param_name": "order_id",
 "example": "335628"
},
{
 "param_name": "customer_name",
 "example": "Shiva"
}]
          
```

</td></tr></tbody></table>

</div>  
</div></div>#### Positional Parameter Example

```
{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
  "example": {
    "header_text": [
      "the end of August","25OFF","25%"
    ]
  }
}
```

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk--2"></div>#### Named Parameter Example

```
{
  "type": "BODY",
  "text": "Your {{order_id}}, is ready {{customer_name}}.",
  "example": {
    "header_text_named_params": [
      {
        "param_name": "order_id",
        "example": "335628"
      },
      {
        "param_name": "customer_name",
        "example": "Shiva"
      }
    ]
  }
}
```

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk--3"><div class="_4-u3 _588p"><div data-click-area="to_top_nav">  
</div></div></div>## Footer

Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component.

### Syntax

```
{
  "type": "FOOTER",
  "text": "<TEXT>"
}
```

### Properties

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-placeholder-descript-3"><div class="_4-u3 _588p">  
<div class="_57-c"><table class="_4-ss _5k9x"><thead><tr><th>Placeholder</th><th>Description</th><th>Example Value</th></tr></thead><tbody class="_5m37" id="bkmrk-%3Ctext%3E-text-to-appea"><tr class="row_0"><td>`<TEXT>`

</td><td>Text to appear in template footer when sent.

  
60 characters maximum.

</td><td>`Use the buttons below to manage your marketing subscriptions`

</td></tr></tbody></table>

</div></div></div>### Example

```
{
  "type": "FOOTER",
  "text": "Use the buttons below to manage your marketing subscriptions"
}
```

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk--4"><div class="_4-u3 _588p"><div data-click-area="to_top_nav">  
</div></div></div>## Buttons

Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits. These limits are described below.

Buttons are defined within a single buttons component object, packed into a single `buttons` array. For example, this template uses a phone number button and a URL button:

```
{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "PHONE_NUMBER",
      "text": "Call",
      "phone_number": "15550051310"
    },
    {
      "type": "URL",
      "text": "Shop Now",
      "url": "https://www.luckyshrub.com/shop/"
    }
  ]
}
```

If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a **See all options** button. Tapping the **See all options** button reveals the remaining buttons.

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk--5"><div class="_4-u3 _588p"><div>![](https://scontent.fblr24-2.fna.fbcdn.net/v/t39.2365-6/362692024_651522560374555_6131765669860446689_n.png?stp=dst-webp&_nc_cat=111&ccb=1-7&_nc_sid=e280be&_nc_ohc=nFisgvxiIuUQ7kNvgFOoahz&_nc_zt=14&_nc_ht=scontent.fblr24-2.fna&_nc_gid=A1GvJeovemXNsxIqfmPNETy&oh=00_AYBItmu-yevxCiEufYeE7Q6yJkvgKJkmN8lKw-QfJ58lsQ&oe=676E1D3B)</div></div></div>### Copy Code Buttons

Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. Templates are limited to one copy code button.

#### Syntax

```
{
  "type": "COPY_CODE",
  "example": "<EXAMPLE>"
}
```

#### Properties

<div class="_4-u2 _57mb _1u44 _3fw6 _4-u8 _3la3" id="bkmrk-placeholder-descript-4"><div class="_4-u3 _588p">  
<div class="_57-c"><table class="_4-ss _5k9x"><thead><tr><th>Placeholder</th><th>Description</th><th>Example Value</th></tr></thead><tbody class="_5m37" id="bkmrk-%3Cexample%3E-string-to-"><tr class="row_0"><td>`<EXAMPLE>`

</td><td>String to be copied to device's clipboard when tapped by the app user.

  
Maximum 15 characters.

</td><td>`250FF`

</td></tr></tbody></table>

</div></div></div>#### Example

```
{
  "type": "COPY_CODE",
  "example": "250FF"
}
```

##### <span style="background-color: rgb(191, 237, 210);">Delete a template</span>

```bash
curl --location --request DELETE 'https://api.versal.one/<client-id>/templates?name=harsh45021279' \
--header 'Authorization: Bearer <client-token>'
```