# Creating a template via API Creating a template is described in the[ API documentation](https://my.1msg.io/documentation/1msg) in the /addTemplate method. You can also create a template from the 'Dev Toolkit →[ 'Test Requests'](https://my.1msg.io/testing/test-requests) section in your personal account. General part of the request:
nameThe name of the template. Name can only contain lower case letters, digits and underscores.
allow_category_changeThe 'Allow category changes' checkbox. Instead of rejecting the template, we will automatically change its category type.
categoryTemplate type: MARKETING, UTILITY or AUTHENTICATION
languageTemplate language. The selected language must match the text in the template being created. Otherwise, the meta template may be rejected.
componentsArray of Template components
Example: ```json { "token": "{{token}}", "name": "test_marketing_2024", "allow_category_change": false, "category": "MARKETING", "language": "ru", "components": [ //objects of the template body ] } ``` Let's look at the structure of the template category. ## Marketing and Services Templates
### HEADER Headers are optional components that appear at the top of template messages. Headers support `TEXT`, media (`IMAGE`, `VIDEO` или `DOCUMENT`). Templates are limited to one header component. Each type is described in the table below. {% tabs %} {% tab title="TEXT" %} Set 'format' to 'TEXT' to define the header as text. Rules for filling: * Text may have a maximum of 60 characters. * Text can contain only one variable. * If the header contains a variable, it is required to specify an example in `header_text.` Example of text without a variable: 
{
    "type": "HEADER",
    "format": "TEXT",
    "text": "Hello"
}
Example of text with a variable: ```json { "type": "HEADER", "format": "TEXT", "text": "Our {{1}} is on!", "example": { "header_text": [ "Summer Sale" // example variable {{1}} ] } } ``` {% endtab %} {% tab title="IMAGE " %} Set `'format': 'IMAGE'` to output an image in the header. Make sure you output the 'example' object with a link to the image in the 'header\_handle'. ```json { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": [ "https://img-example-link.com/delicious-orange-23.jpg" ] } } ``` {% endtab %} {% tab title="VIDEO" %} Set `'format': 'VIDEO'` to output an image in the header. Make sure you output the 'example' object with a link to the video in the 'header\_handle'. ```json { "type": "HEADER", "format": "VIDEO", "example": { "header_handle": [ "https://video-example-link.com//banner.mp4" ] } } ``` {% endtab %} {% tab title="DOCUMENT" %} Set `'format': 'DOCUMENT'` to output an image in the header. Make sure you output the 'example' object with a link to the document in the 'header\_handle'. ```json { "type": "HEADER", "format": "DOCUMENT", "example": { "header_handle": [ "https://doc-example-link.com/reyshi.pdf" ] } } ``` {% endtab %} {% endtabs %} ### BODY Body components are text-only components and are required by all templates. Templates are limited to one body component. Rules for filling: * Body component is required. * Propetry 'text' can contain a maximum of 1024 characters. * If there are variables in the text, it is required to specify examples of the variables in the `'example'` section of the `'body_text'` array. The number of lines in `body_text` must be equal to the number of variables in the text line. * The number of variables is not limited by Meta. * You cannot specify only a variable in the text. For example, Meta will not accept the format of the text "text": "{{1}}". ```json { "type": "BODY", "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.", "example": { // does not need to be specified if there are no variables in text "body_text": [ [ "the end of August", // example of the first variable "25OFF", // example of a second variable "25%" // example of a third variable ] ] } } ``` ### FOOTER Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component ```json { "type": "FOOTER", "text": "text for footer" } ``` ### 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. **What kind of buttons:** * **Quick Reply.** Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. The text on the button can be written in any way you like. * **URL Button.** URL buttons load the specified URL in the device's default web browser when tapped by the app user. * **Phone Number Button.** Phone number buttons call the specified business phone number when tapped by the app user. * **Catalog Button** (only available in the Marketing category). When a customer taps the **View catalog** button in a catalog template message, your product catalog appears within WhatsApp. The **URL** and **Phone** button does not send a reply to the chat like the quick reply button. #### Quantity limitation: * Templates are limited to 10 quick reply buttons. * Templates are limited to 2 URL buttons. * Templates are limited to 1 Phone Number button. * Only the Catalog button can be used in the Catalog template. * Templates can have a mixture of up to 10 button components total
Examples of valid groupings:Examples of invalid groupings:
  • Quick Reply, Quick Reply, Quick Reply
  • Quick Reply, Quick Reply, Quick Reply, URL, Phone
  • URL, Phone, Quick Reply, Quick Reply
  • Quick Reply, URL, Quick Reply
  • URL, Quick Reply, URL
As you can see, you need to consider the order in which you enter the button type and the quantity of allowable buttons. For example, you can't add a Quick Reply button first, then a URL button, and then a Quick Reply button again. {% tabs %} {% tab title="QUICK REPLY" %} Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. The text on the button can be written in any way you like. There is a limit of 25 characters. ```json { "type": "QUICK_REPLY", "text": "Yes" } ``` {% endtab %} {% tab title="URL" %} Property "text" : button label text. Supports 1 variable. 25 characters maximum. If using a variable, must include the example property and a sample value. Property "url": URL of website that loads in the device's default mobile web browser when the button is tapped by the app user. Supports 1 variable, appended to the end of the URL string. 2000 characters maximum. The API does not accept Cyrillic characters in URLs within button elements. Please ensure your URLs contain only Latin characters If you specify a variable, you must specify an example in 'example'. ```json { "type": "URL", "text": "Shop Now", "url": "https://www.luckyshrub.com/shop?promo={{1}}", "example": [ // will be filled when a variable is added to the url. "summer2023" // variable {{1}} ] } ``` {% endtab %} {% tab title="PHONE NUMBER" %} Property **"**phone\_number": business phone number to be (display phone number) called when the user taps the button. 20 characters maximum. Property "text" : button label text. 25 characters maximum. Properties "phone\_number" and "text" are required. ```json { "type": "PHONE_NUMBER", "text": "my number", "phone_number": "77777777777" } ``` {% endtab %} {% tab title="Untitled" %} Only one button can be added to the 'Catalog' template. It is mandatory to write "View catalog" in the 'text'. Depending on the language of the template, the text of the button will be translated into the specified language. ```json { "type": "CATALOG", "text": "View catalog" } ``` {% endtab %} {% endtabs %}
Example Request An example request to create a marketing template with the following components: * a text header with a variable and sample value * a text body with variables and sample values * a text footer * two quick-reply buttons ```json { "token": "{{token}}", "name": "test_marketing_2024", "allow_category_change": false, "category": "MARKETING", "language": "ru", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Our {{1}} is on!", "example": { "header_text": [ "Summer Sale" ] } }, { "type": "BODY", "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.", "example": { "body_text": [ [ "the end of August","25OFF","25%" ] ] } }, { "type": "FOOTER", "text": "Use the buttons below to manage your marketing subscriptions" }, { "type":"BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Unsubscribe from Promos" }, { "type":"QUICK_REPLY", "text": "Unsubscribe from All" } ] } ] }' ```
## Authentication Template Authentication templates include optional add-ons like security disclaimers and expiry warnings. In addition, authentication templates must have a one-time password button (copy code or one-tap).
The `components` value in the request must be an array of objects that describes each component that makes up the template. Authentication templates must have the following components: * a single **body** component * a single **footer** component. **Footer** is not required . * a single **OTP Button** component {% tabs %} {% tab title="BODY" %} It consist of: * Fixed **preset text**: *\ is your verification code.* Don't fill the ‘text’ property. * An optional **security disclaimer**: *For your security, do not share this code.* If you want to add the text 'For your security, do not share this code', set `'add_security_recommendation': true`. Set to false to exclude the string. The selected template language determines the language of the text displayed to the user. ```json { "type": "BODY", "add_security_recommendation": true } ``` {% endtab %} {% tab title="FOOTER" %} **Footer** is not required . It consist of: * An optional **expiration warning**: *This code expires in \ minutes.* Specify an integer in 'code\_expiration\_minutes' to do this. You can enter minutes from 1 to 90. If omitted, the code expiration warning will not be displayed in the delivered message. ```json { "type": "FOOTER", "code_expiration_minutes": 5 } ``` {% endtab %} {% tab title="BUTTONS" %} Authentication templates must include either a copy code or one-tap autofill button. These buttons have ‘type’: ‘OTP’. Property "otp\_type" - indicates button type. Set to `COPY_CODE` if you want the template to use a copy code button, or `ONE_TAP` to have it use a one-tap autofill button. Only one button can be specified. Свойство "text" - copy code button text. **Note that even if your template is using a one-tap autofill button, this value must still be supplied.** If Meta's unable to validate your [handshake](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake) the authentication template message will display a copy code button with this text instead. Maximum 25 characters. For type ONE\_TAP, the following fields must also be filled in: * autofill\_text - one-tap button text. Maximum 25 characters. * package\_name - your Android app's package name. * signature\_hash - your app signing key hash. See Meta's Official documentation for [App Signing Key Hash](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#app-signing-key-hash). An example of a code copy button: ```json { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "COPY_CODE", "text": "Скопировать" } ] } ``` An example of a one-touch autofill button: ```json { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "ONE_TAP", "text": "Copy Code", "autofill_text": "Autofill", // One-tap buttons only "package_name": "com.example.myapplication", // One-tap buttons only "signature_hash": "K8a%2FAINcGX7" // One-tap buttons only } ] } ``` {% endtab %} {% endtabs %}
Full example of sending an Authentication template ```json { "token": "{{token}}", "name": "auth_2024", "allow_category_change": false, "category": "AUTHENTICATION", "language": "ru", "components": [ { "type": "BODY", "add_security_recommendation": true }, { "type": "FOOTER", "code_expiration_minutes": 5 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" } ] } ] } ```