Creating Operator Templates

Last updated: 15 July 2025

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`	integer	Required	Array of signature IDs for which a template is being created. To find out the channel signature ID, use the method to get a list of channels. Receiving List of Channels

Request Parameters for WhatsApp Channel

Parameter	Data Type	Character	Description
`language`	string	Required	Template language in WhatsApp Business Platform format. 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. ISO 8601 - Convention

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 newline characters.
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
`language`	string	Required	Template language in the `ISO 639-1` format. ISO 639-1 Language Code List
`content`	object	Required	Object with template contents.
`content.action`	string	Optional	URL of the button.
`content.caption`	string	Optional	Button name.
`content.text`	string	Required	Message text.
`contentType`	string	Optional	Content type. Possible value: `TEXT' is a text message.
`category`	string	Required	Template category. Possible values: - `ACCOUNT_UPDATE` - `PAYMENT_UPDATE` - `PERSONAL_FINANCE_UPDATE` - `SHIPPING_UPDATE` - `RESERVATION_UPDATE` - `ISSUE_RESOLUTION` - `ISSUE_UPDATE` - `APPOINTMENT_UPDATE` - `TRANSPORTATION_UPDATE` - `TICKET_UPDATE` - `ALERT_UPDATE` - `AUTO_REPLY`
`type`	string	Required	Template type. Possible values: - `OPERATOR` — operator template registered with the telecom operator; - `USER` — user template created by the user based on the operator; - `CUSTOM` — free template with allowed for the specified channel content. Only the `OPERATOR` type is supported.

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": "new_matcher",
        "channelType": "VIBER",
        "language": "EN",
        "content": {
            "text": "Hello, %w{1,5}, thank you for choosing us."
        },
        "category": "TRANSACTIONAL",
        "type": "OPERATOR"
    },
    "subjectIds": [
        2234
    ]
}

info

{{1}}, [\ s\w]+ and %w{1,n} are the characters of the auto—suggestion elements, that is, strings of characters, instead of which you can specify any values. Each provider has its own rules for using these elements.

WhatsApp Operator Templates Viber 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"
}

Error codes

Code	Error	Description	Possible comments
`400`	`must not be null`	The category of the WhatsApp template is not specified.	—
`400`	`message-matcher-category-invalid`	The wrong category of the WhatsApp template is specified.	—
`400`	`message-matcher.saving.bad-request`	The fields in the request are filled in incorrectly.	- The example of a dynamic link for the WhatsApp template is not specified or is specified incorrectly. - `Field content.buttons.payload - QUICK_REPLY button payload length must not exceed 128` – Exceeded the length of the payload quick response button code field, the maximum number of characters is 128.
`400`	`message—matcher-name-already-exists`	Template with this the 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`	Invalid template language code is specified.
`400`	`validation failure`	WhatsApp template validation error. Occurs if the maximum allowed number of buttons is exceeded in the WhatsApp template.	- `Field content.buttons - Buttons max allowed count is 10` — The maximum number of buttons in the template is 10. - `Field content.buttons - URL buttons max allowed count is 2` — The maximum number of link buttons in the template is 2. - `Field content.buttons - PHONE buttons max allowed count is 1` — The maximum number of call buttons in the template is 1.

Calling the api/message-matchers Method​

Request Format​

General Request Parameters​

Request Parameters for WhatsApp Channel​

Validation of WhatsApp Templates​

Channels​

Template name​

Attachments​

Template message text​

Variables in the message text​

Text header​

Signature​

Buttons​

Quick Response button QUICK_REPLY​

The Link URL button​

Number Button PHONE_NUMBER​

Placeholder text​

Request Parameters for Viber channel​

Sample templates​

WhatsApp HSM with variables in the template text​

WhatsApp HSM with buttons​

WhatsApp HSM with TTL parameter​

Viber​

Response Format​

Error codes​