Creating Operator Templates

Last updated: 7 October 2026

The api/message-matchers method is used to request the creation of an operator template.

Calling the api/message-matchers Method

To call the api/message-matchers method, send a POST request to the URL https://app.edna.io/api/message-matchers

If the request is successful, an operator template is created and the method returns a response with the code 200. If the request is unsuccessful, the method returns an error code.

Request Format

{
    "messageMatcher": {
        "id": 0,
        "name": "string",
        "channelType": "SMS",
        "language": "string",
        "content": {
            "attachment": {
                "id": 0,
                "fileUrl": "string",
                "originalFileName": "string",
                "size": 0
            },
            "action": "string",
            "caption": "string",
            "header": {
                "headerType": "TEXT",
                "text": "string",
                "attachment": {
                    "id": 0,
                    "fileUrl": "string",
                    "originalFileName": "string",
                    "size": 0
                },
                "headerExampleTextParam": "string",
                "headerExampleMediaUrl": "string"
            },
            "text": "string",
            "footer": {
                "text": "string"
            },
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "string",
                                "buttonType": "PHONE",
                                "otpType": "COPY_CODE",
                                "url": "string",
                                "urlPostfix": "string",
                                "phone": "string",
                                "payload": "string",
                                "urlTextExample": "string",
                                "color": "string",
                                "requestContact": true,
                                "requestLocation": true,
                                "autofillText": "string",
                                "packageName": "string",
                                "hash": "string",
                                "appId": 0,
                                "ownerId": 0
                            }
                        ]
                    }
                ]
            },
            "securityRecommendation": true,
            "codeExpirationMinutes": 0,
            "textExampleParams": [
                "string"
            ]
        }
    }
}

General Request Parameters

Parameter	Data type	Character	Description
name	string	Required	Template name. It can only contain Latin letters, numbers, and the underscore _. The maximum number of characters is 60.
channelType	string	Required	The type of channel for which you need to create an operator template: WHATSAPP, VIBER
subjectIds	array of numbers	Required	The IDs of the channels for which the operator template is being created. To find a channel ID, use the API method to retrieve a list of channels—the subjectId parameter. Receiving List of Channels

Request Parameters for WhatsApp Channel

Parameter	Data Type	Character	Description
language	string	Required	Template language in WhatsApp Business Platform format. WhatsApp The supported languages are listed in the Meta documentation. developers.facebook.com
content	object	Required	An object with the contents of the template.
content.attachment	object	Optional	An object with information about the attachment.
content.attachment.fileUrl	string	Optional	File URL.
content.attachment.originalFileName	string	Optional	File name.
content.header	object	Optional	An object with header information.
content.header.headerType	string	Required if content.header is passed	Header type: TEXT' — text, IMAGE' — image, VIDEO — video, DOCUMENT — file.
content.header.text	string	Optional	Header text.
content.header.attachment	object	Optional	An object with information about the file in the header.
content.header.attachment.fileUrl	string	Optional	File URL in the header.
content.header.attachment.originalFileName	string	Optional	File name in the header.
content.header.headerExampleTextParam	string	Required if headerType=TEXT	An example of the title text.
content.header.headerExampleMediaUrl	string	Required if headerType=IMAGE, VIDEO, or DOCUMENT	The URL of the sample header file.
content.text	string	Required	Message text.
content.footer	object	Optional	Object with signature information.
content.footer.text	string	Optional	Signature text.
content.keyboard.rows.buttons	array of objects	Optional	Array of objects with information about buttons. The maximum allowed number of buttons in the template is 10.
content.keyboard.rows.buttons.text	string	Optional	Button name.
content.keyboard.rows.buttons.buttonType	string	Optional	Button type. Possible values: - PHONE — call button; - URL — link button; - QUICK_REPLY — quick response button. The maximum allowed number of link buttons in the template is 2. The maximum allowed number of call buttons in the template is 1.
content.keyboard.rows.buttons.url	string	Required if buttonType = URL	is the URL that opens when the button is clicked.
content.keyboard.rows.buttons.urlPostfix	string	Optional	Dynamic part of the link of the button URL.
content.keyboard.rows.buttons.phone	string	Required if buttonType = PHONE	The phone number that is dialed when the button is pressed.
content.keyboard.rows.buttons.payload	string	Required if buttonType = QUICK_REPLY	The code or text of the quick response button. The maximum number of characters is 128.
content.keyboard.rows.buttons.urlTextExample	string	Required if buttonType = URL	An example of a URL for a link button.
content.textExampleParams	array of strings	Required if ChannelType = WHATSAPP and content.text contain variables	Example for each variable in the content.text parameter.
contentType	string	Optional	Content type. - TEXT — text message; - IMAGE— image; - BUTTON — button; - DOCUMENT — file attached to the message; - LOCATION — message with coordinates, address and description of the place (coordinates are converted into a Google Maps snapshot); - AUDIO — message with audio; - VIDEO — message with video.
category	string	Required	Template category. - MARKETING — company news, offers with promotions and discounts, information about events and webinars; -UTILITY — information about account changes, order status or loyalty program, notification of payment receipt, confirmation of funds transfers, other transactions in the field of financial services.
type	string	Required	Template type. - OPERATOR — operator template registered with the telecom operator; - USER — user template created by the user based on the operator template. Only the OPERATOR template type is supported.
messageTtl	string, integer	Optional	WhatsApp message lifetime set in the template. Only for the UTILITY category template. Supported data types: - string or number to be written in seconds (for example, 3600); - string in the ISO 8601 durations date format (for example, "PT10H15M48S"). Possible values range from 30 seconds to 12 hours. The default value set on the Meta* side is 30 days. To apply it, leave the field empty. WhatsApp For more information about TTL for template messages, see the Meta documentation: developers.facebook.com

tip

If you register two or more templates with the same content, but with different TTL values, for one business account, then when sending messages from edna Pulse's personal account and using the api/cascade/schedule method, the messages will be compared with the template that was created before the others.

To avoid such situations, log into your Facebook Business Manager account and disable the unused template, or send a request to edna support to disable the template with an explanation of the reason.

Validation of WhatsApp Templates

When creating WhatsApp carrier templates, consider the following limitations:

Channels

The created template can be used on all channels linked to the selected WhatsApp Business account.

Template name

Only Latin letters, numbers, and the symbol (_) can be used in the name. Spaces and other symbols are not allowed.

Attachments

Possible types of attachments:

• image (JPEG, JPG, PNG);
• video (MP4, 3GPP, 3GPP);
• the document (PDF).

You can select only one type of attachment to send in the template.

Template message text

• The text field must be filled in.
• The maximum number of characters in the message text, taking into account the text in the character string, is 1024. In addition to the text, the use of variables is allowed.
• The text must not contain more than two newline characters (hyphens) in a row.
• The text must not contain 4 or more consecutive spaces.

Variables in the message text

• The variable must not contain a line break. When using migration, the changes are not saved.
• The maximum number of characters in a variable value is 512.
• Variables must be specified with two double curly braces at the beginning and at the end.
• The use of single brackets is not allowed.

Text header

• Fields with text and title type are required.
• The maximum number of characters in a text header is 60.
• You can add one variable to the text header.
• Spaces should not be used at the beginning and at the end of the title.

Signature

• The signature field must be filled in.
• The maximum number of characters in the signature is 60.
• The use of variables is not allowed.
• Spaces should not be used at the beginning and at the end of the signature.

Buttons

• The maximum number of characters in the button name is 25.
• When adding a button, its type must be specified, all fields must be filled in.

Quick Response button QUICK_REPLY

• The name of the button is consistent with the text of the template without the possibility of changing the settings.
• The maximum number of characters in the button code is 128. — There can be no more than 10 buttons of this type in one template.
• After clicking, a 24-hour window opens.
• Clicking is regarded as a reply message with the ability to open a conversation.
• The button can be pressed only once.

The Link URL button

• The maximum number of characters in a link is 2000.
• URL health check is available.
• When clicked, a pre-agreed link is clicked.
• Within a single template, this type of button is only compatible with Number type buttons.
• Clicking on the button is not considered as the user's response.
• The button can be used multiple times.

Number Button PHONE_NUMBER

• When pressed, the specified phone number is dialed.
• The phone number must be specified in the international format (the "+" symbol at the beginning), the allowed number of digits in the number is 10-19.
• You can only make calls through the WhatsApp mobile app.
• Within a single template, this type of button is compatible only with Link type buttons.
• Clicking on the button is not considered as the user's response.
• The button can be used multiple times.

Placeholder text

The maximum number of placeholder texts is 5.

Request Parameters for Viber channel

Parameter	Data Type	Character	Description
messageMatcher.language	string	Required	Template language in ISO 639-1 format. localizely.com
messageMatcher.content	object	Required	An object containing information about the message template’s content. Viber supports only text and text with variables in message templates. Other content types are not supported.
messageMatcher.content.text	string	Required	The text of the message template.
messageMatcher.type	string	Required	Template type. Possible values: - OPERATOR — an operator template registered with an operator or provider. Only the OPERATOR value is supported.
messageMatcher.variableNames	array of strings	Required if messageMatcher.content.text contains variables	Variables in the message template text.
messageMatcher.textExampleParams	array of strings	Required if messageMatcher.content.text contains variables	An example for each variable in the message template text.

Validating Viber templates

When creating a Viber operator template, keep the following restrictions in mind:

Message text

• Only text and text with variables can be used in an operator template. Buttons, images, and files are not supported.
• The maximum length of the template text is 1,000 characters.
• You cannot place a variable or the characters /, #, (, +, %, or ' at the beginning or end of the template text.
• A space must precede a variable.

Variables in message text

• Variables are denoted in the template as {1}, {2}, {3}, and so on.
• You can use no more than 8 variables in a single template.
• The recommended length of a value substituted for a variable is no more than 125 characters.
• It is not recommended to use links instead of variables.

Sample templates

WhatsApp HSM with variables in the template text

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "EN",
        "content": {
            "header": {
                "text": "Your company {{1}}",
                "headerType":"TEXT",
                "headerExampleTextParam": "edna"
            },
            "text": "Hello, {{1}}! Thanks for choosing {{2}}",
            "textExampleParams": [
                "David",
                "example"
            ],
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "website",
                                "buttonType": "URL",
                                "url": "https://edna.io/{{1}}",
                                "urlTextExample": "https://edna.io/test"
                            },
                            {
                                "text": "Call",
                                "buttonType": "PHONE",
                                "phone": "3570000000"
                            }
                        ]
                    }
                ]
            },
            "footer": {
                "text": "Thanks for interest"
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}

WhatsApp HSM with buttons

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "EN",
        "content": {
            "header": {
                "text": "Your edna chat",
                "headerType": "TEXT"
            },
            "text": "Hello! Thanks for choosing us.",
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Yes",
                                "buttonType": "QUICK_REPLY",
                                "payload": "1"
                            },
                            {
                                "text": "No",
                                "buttonType": "QUICK_REPLY",
                                "payload": "2"
                            },
                            {
                                "text": "Later",
                                "buttonType": "QUICK_REPLY",
                                "payload": "3"
                            }
                        ]
                    }
                ]
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}

WhatsApp HSM with TTL parameter

{
    "messageMatcher": {
        "name": "utility_test",
        "channelType": "WHATSAPP",
        "language": "EN",
        "content": {
            "text": "Hi! Pick up the order at the pick-up point"
        },
        "category": "UTILITY",
        "type": "OPERATOR",
        "messageTtl": 36000
    },
    "subjectIds": [
        145
    ]
}

Viber

{
    "messageMatcher": {
        "name": "viber_template",
        "channelType": "VIBER",
        "language": "EN",
        "content": {
        "text": "Hello, {{1}}. Your order {{2}} will be delivered on {{3}}. Thank you for choosing us!",
        "variableNames": ["name", "order", "date"],
        "textExampleParams": ["Alex", "56128793", "01.02"]
        },
        "type": "OPERATOR"
    },
    "subjectIds": [
        308
    ]
}

info

{1}, {2}, and {3} are variables in the template. They are used to pass variable values, such as the recipient's name, order number, or delivery date. The rules for using variables depend on the channel provider.

WhatsApp Operator TemplatesViber Operator Templates

Response Format

A JSON object containing the request execution code is returned in response to the request.

Response to a request to create a WhatsApp HSM operator template with the TTL parameter:

{
    "id": 10,
    "name": "utility_test",
    "channelType": "WHATSAPP",
    "language": "EN",
    "content": {
        "attachment": null,
        "action": null,
        "caption": null,
        "header": null,
        "text": "Hi! Pick up the order at the pick-up point",
        "footer": null,
        "keyboard": {
            "rows": []
        },
        "securityRecommendation": null,
        "codeExpirationMinutes": null,
        "textExampleParams": null,
        "vkAttachments": null,
        "vkTwoWayEnabled": null
    },
    "contentType": "TEXT",
    "category": "UTILITY",
    "status": "PENDING",
    "locked": false,
    "type": "OPERATOR",
    "createdAt": null,
    "updatedAt": null,
    "messageTtl": "PT10H"
}

Response to the request to create a Viber operator template:

{
    "id": 17,
    "name": "viber_template",
    "channelType": "VIBER",
    "language": "EN",
    "content": {
        "attachment": null,
        "action": null,
        "caption": null,
        "header": null,
        "text": "Good afternoon, {{1}}. Your order {{2}} will be delivered on {{3}}. Thank you for choosing us!",
        "footer": null,
        "keyboard": {
            "rows": []
        },
        "securityRecommendation": null,
        "codeExpirationMinutes": null,
        "textExampleParams": [
            "Alex",            
            "56128793",
            "01.02" 
        ],
        "variableNames": [
            "name",            
            "order",
            "date"
        ],
        "vkAttachments": null,
        "vkTwoWayEnabled": null,
        "requestCallPermission": null
    },
    "category": null,
    "status": "PENDING",
    "locked": false,
    "type": "OPERATOR",
    "createdAt": "2026-10-06T14:48:41.295Z",
    "updatedAt": "2026-10-06T14:48:41.295Z",
    "messageTtl": null,
    "contentType": "TEXT"
} 

Error codes

Code	Error	Description	Possible comments
400	must not be null	The WhatsApp template category is not specified.	—
400	message-matcher-category-invalid	An invalid WhatsApp template category is specified.	—
400	message-matcher.saving.bad-request	Request fields are filled in incorrectly.	- Field content.variableNames - Variable names and examples count must match the number of variables (N) — The number of variable names and their examples must match the number of variables in the template text (N). - Field content.text - Maximum 8 variables allowed — The maximum number of variables allowed in the template text has been exceeded. A single template can contain no more than 8 variables. - Field content.text - Variables cannot be placed at the beginning or end of the text — A variable cannot be placed at the beginning or at the end of the template text. - Field content.text - Text must not start or end with # ( + % ', Field content.text - Invalid symbols in text — The special characters #, (, +, %, and ' cannot be used at the beginning or at the end of the template text; invalid characters were also found in the template text. - Field content.variableNames - Variable name [N] must contain only latin letters — The variable name [N] must contain only Latin letters. - Field content.variableNames - Variable name [N] is not unique — Variable names [N] must be unique within the template. - Field content.variableNames - Variable example [N] must not contain links — The example value of variable [N] must not contain links. - Field content.text - Each variable must be preceded by a space — A space is required before and after each variable. - Field content.buttons.payload - QUICK_REPLY button payload length must not exceed 128 — The maximum length of the quick reply button code field payload has been exceeded. The maximum length is 128 characters. - Field content.text - Invalid symbols in text. More than 2 consecutive \n or \r — The allowed number of consecutive line breaks in the template text has been exceeded. No more than two consecutive line breaks are allowed.
400	message-matcher-name-already-exists	A template with this name already exists.	Message matcher with specified channel type, tenantId and name already exists — A template with this channel type and name already exists.
400	message-matcher.saving.already-exists	A template with this content already exists.	—
400	invalid language	An invalid template language code is specified.	—
400	validation failure	WhatsApp template validation error. Occurs when the maximum number of buttons allowed in a WhatsApp template is exceeded.	- Field content.buttons - Buttons max allowed count is 10 — The maximum number of buttons in a template is 10. - Field content.buttons - URL buttons max allowed count is 2 — The maximum number of URL buttons in a template is 2. - Field content.buttons - PHONE buttons max allowed count is 1 — The maximum number of call buttons in a template is 1.
400	message-matcher-category-not-allowed-for-viber	A category must not be specified for Viber templates.	- Category must not be specified for VIBER message-matcher [category:X;tenantId:1] — A category must not be specified for a Viber template.
400	message-matcher-subject-invalid	The request uses invalid channel identifiers.	- Some of provided subjects are invalid (i.e. incorrect channel type or status) — Some of the specified channel identifiers are invalid, for example because of an unsuitable channel type or status.
400	message-matcher-type-not-supported-for-sms	The specified template type is not supported for the SMS channel.	- Only OPERATOR-type is supported for SMS message-matcher [tenantId:1;type:CUSTOM] — Only an operator template can be registered for the SMS channel via the API.