Creating Operator Templates

This article covers an API method for creating operator templates.

message-matchers Method

An operator template is created as a result of a completed request using the method-matchers method. If the request is completed successfully, the server returns code 200. If the request fails, the server returns a response with an error code.

URL

To create an operator template, send a POST request to the following URL address: https://app.edna.io/api/message-matchers

Request Format

A JSON object is passed in the request body with the following parameters.

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "EN",
        "content": {
            "text": "Hello, thank you for choosing us."
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        2234
    ]
}

Template Parameters

General parameters:

ParameterData typeObligatoryDescription
namestringyesThe name of the template. It can only contain Latin letters, numbers and underscores (_). The maximum length is 60 characters.
channelTypestringyesThe interaction channel type. Possible values: WHATSAPPVIBERSMS
subjectIdsintegeryesThe array of identifiers of the subjects of the channels for which the template is being created. To get the IDs, use the channel-profile method.

The parameters for specific channels are listed in the tables below.

Parameters for WhatsApp Channels

PatameterData typeObligatoryDescription
languagestringyesThe template language in the WhatsApp Business Platform format.
contentobjectyesThe object with the template contents.
content.attachmentobjectThe object with information about the attachment.
content.attachment.
fileUrl
stringThe URL of the file.
content.attachment.
originalFileName
stringThe name of the file.
content.headerobjectThe object with the header information.
content.header.headerTypestringyes (internal API)
no (public API)
The header type: TEXT, IMAGE, VIDEO, DOCUMENT.
content.header.textstringThe header text.
content.header.attachmentobjectThe object with information about the file in the header.
content.header.attachment.
fileUrl
stringThe URL of the file in the header.
content.header.attachment.
originalFileName
stringThe file name in the header.
content.header.
headerExampleTextParam
stringyes, if headerType =
TEXT
An example of the title text.
content.header.
headerExampleMediaUrl
stringyes, if headerType =
IMAGE, VIDEO or DOCUMENT
The URL of the sample header file.
content.textstringyesThe message text.
content.footerobjectThe object with information about the signature.
content.footer.textstringThe footer text.
content.keyboard.rows.
buttons
objectThe object with information about the buttons.
content.keyboard.rows.
buttons.text
stringThe button name.
content.keyboard.rows.
buttons.buttonType
stringThe button type: PHONE, URL, QUICK_REPLY.
content.keyboard.rows.
buttons.url
stringyes, if buttonType = URLThe URL that opens when pressing the button.
content.keyboard.rows.
buttons.urlPostfix
stringThe dynamic part of the link of the button URL.
content.keyboard.rows.
buttons.phone
stringyes, if buttonType = PHONEThe number to be called when the button is pressed.
content.keyboard.rows.
buttons.payload
stringyes, if buttonType = QUICK_REPLYThe quick response text.
content.keyboard.rows.
buttons.urlTextExample
stringyes, if buttonType = URLAn example URL for the link button.
content.textExampleParamsarray of stringsyes, if channelType = WHATSAPP and content.text contains variablesOne example for each variable in the content.text parameter.
contentTypestringThe content type:
• TEXT: text message;
• IMAGE: image;
• BUTTON: button;
• DOCUMENT: document attached to the message;
• LOCATION: message with coordinates, address and description of the place. The coordinates are converted to a Google Maps snapshot;
• AUDIO: message with sound;
• VIDEO: message with video;
• AUTHENTICATION: message with a one-time password.
categorystringyesThe template category. Possible values:
MARKETING: company news, offers with promotions and discounts, information about events and webinars, etc.;
AUTHENTICATION: personal account or application codes for secure access to user accounts; updating account information or settings, subscription end date, password change;
UTILITY: information on changes to the account, order status or loyalty program; notification of receipt of payment, transfer confirmations, other financial services transactions.

Important! The creation of AUTHENTICATION category templates is temporarily restricted.
typestringyesThe template type. Possible values:
OPERATOR: operator template (a template registered with a service provider);
USER: user template (a template created by the user based on an operator template).

Important! Currently, only the OPERATOR type is supported.

Validation of WhatsApp Templates

When creating WhatsApp operator templates, consider the following limitations:

LimitationDescription
ChannelsThe created template can be used on all channels associated with the selected WhatsApp Business account.
Template nameThe name can only contain Latin letters, numbers and underscores (_). The use of spaces and other characters is not allowed.
AttachmentsPossible attachment types:
• image (.jpeg, .jpg, .png);
• video (.mp4, .3gp);
• document (.pdf).
You can select only one type of attachment to send in the template.
Template message text The field with the text is required to be filled in.
The maximum number of characters in the message body is 1024 (including the text in the string). In addition to the text, the use of variables is allowed.
The text shouldn’t contain line breaks.
The text shouldn’t contain characters with 4 or more consecutive spaces.
Variables in the message text The variable shouldn’t contain a line break. If you use transfer, the changes are not saved.
The maximum number of characters in a variable value is 512.
Variables should be specified with two double curly braces at the beginning and end.
The use of single braces is not permitted.
Text header• Fields with text and header type are required to be filled in.
The maximum number of characters in the text header is 60.
You can add one variable to the text header.
• You can’t use spaces at the beginning and end of the header.
Footer The footer field is required to be filled in.
The maximum number of characters in the footer is 60.
The use of variables is not allowed.
• You can’t use spaces at the beginning and end of the footer.
Buttons• The maximum number of characters in the button name is 25.
• When adding a button, you should specify its type, all fields are required to be filled in.
Quick reply button (QUICK_REPLY)• The name of the button is consistent with the template text, without the possibility of changing the settings.
• The maximum number of characters in the button code is 250.
• There can be no more than 3 buttons of this type in a template.
• You can’t use this button together with the URL or Phone number buttons.
• Pressing the button opens a 24-hour window.
• Pressing the button is considered as a reply message with the possibility to open a conversation.
• The button can only be pressed once.
URL button (URL)• The maximum number of characters in the link is 2000.
• Еhe URL health check is available.
Pressing the button opens the indicated link.
Within the same template, this button type is compatible only with the Phone number button.
Pressing the button is not considered as a user’s response.
The button can be used several times.
Phone number button (PHONE_NUMBER) Pressing the button calls the indicated phone number.
The phone number should be specified in the international format (the symbol “+” at the beginning), the allowed quantity of digits in the number is 10-19.
• Calls can only be made through the WhatsApp mobile application.
Within the same template, this button type is compatible only with the URL button.
• Pressing the button is not considered as a user’s response.
• The button can be used several times.
PlaceholdersThe maximum number of placeholders is 5.

Parameters for Viber Channels

ParameterData typeObligatoryDescription
languagestringyesThe template language is in ISO 639-1 format.
contentobjectyesThe object with the template contents.
content.actionstringThe URL of the button.
content.captionstringThe button name.
content.textstringyesThe message text.
contentTypestringThe content type. TEXT is a text message.
categorystringдаThe 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.
typestringдаThe template type. Possible values:
OPERATOR: operator template (a template registered with a service provider);
USER: user template (a template created by the user based on an operator template).
• CUSTOM: a template from scratch without any restrictions, which can contain any content allowed for this channel.

Important! Currently, only the OPERATOR type is supported.

Parameters for SMS Channels

ParameterData typeObligatoryDescription
contentobjectyesThe object with the template contents.
content.textstringyesThe message text.
typestringyesThe template type. Possible values:
OPERATOR: operator template (a template registered with a service provider);
USER: user template (a template created by the user based on an operator template).
• CUSTOM: a template from scratch without any restrictions, which can contain any content allowed for this channel.

Important! Currently, only the OPERATOR type is supported.
smsProviderIdsintegeryesThe ID of the SMS operators for which the SMS template is being registered.

Template Examples

  • WhatsApp HSM with parameters within text body
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "EN",
        "content": {
            "header": {
                "text": "Your company {{1}}",
                "headerExampleTextParam": "edna"
            },
            "text": "Hello, {{1}}! Thanks for choosing {{2}}",
            "textExampleParams": [
                "David",
                "glory"
            ],
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Website",
                                "buttonType": "URL",
                                "url": "https://edna.io/{{1}}",
                                "urlTextExample": "https://edna.io/test"
                            },
                            {
                                "text": "Call us",
                                "buttonType": "PHONE",
                                "phone": "+1900000000"
                            }
                        ]
                    }
                ]
            },
            "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"
            },
            "text": "Hello! Thanks for choosing us.",
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Yes",
                                "buttonType": "QUICK_REPLY",
                                "payload": "1"
                            },
                            {
                                "text": "No",
                                "buttonType": "QUICK_REPLY",
                                "payload": "2"
                            },
                            {
                                "text": "Do not know",
                                "buttonType": "QUICK_REPLY",
                                "payload": "3"
                            }
                        ]
                    }
                ]
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}
  • Viber
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "VIBER",
        "language": "EN",
        "content": {
            "text": "Hello, [\s\w]+, thank you for choosing us."
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        2234
    ]
}
  • SMS
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "SMS",
        "language": "EN",
        "content": {
            "text": "Hello, %w{1,10}, thank you for choosing us."
        },
        "category": "MARKETING",
        "type": "OPERATOR",
        "createdAt": "2022-05-05T11:34:34.844Z",
        "updatedAt": "2022-05-05T11:34:34.844Z"
    },
    "subjectIds": [
        2234
    ]
}

{{1}}, [\s\w]+, and %w{1,10} are regular expressions, which are strings of characters that you can replace with any value. Each service provider has its own rules and standards for using regular expressions. Read more in the articles SMSViberWhatsApp.

See possible examples of messages that can be sent via the API.

Response Format

A JSON object with the request execution code is returned as a response to the request.

Response Codes

Response codeDescription
okThe request completed successfully.
must not be nulThe WhatsApp template category is not specified.
message-matcher-category-invalidThe WhatsApp template category is incorrect. Possible categories: MARKETING, AUTHENTICATION, UTILITY.
message-matcher.saving.bad-requestThe example of a dynamic link for the WhatsApp template is not specified or is specified incorrectly.
message-matcher-name-already-existsA template with the same name or content already exists.
invalid languageThe template language code is incorrect.
validation failureWhatsApp template validation error.
Next Article Receiving Template Registration Status