Creating Operator Templates

KB Home
API
edna Pulse API
Templates
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.

{
  "name": "string",
  "channelType": "SMS",
  "language": "string",
  "content": {
    "attachment": {
      "fileUrl": "string",
      "originalFileName": "string",
    },
    "action": "string",
    "caption": "string",
    "header": {
      "headerType": "TEXT",
      "text": "string",
      "attachment": {
        "fileUrl": "string",
        "originalFileName": "string",
      },
      "headerExampleTextParam": "string",
      "headerExampleMediaUrl": "string"
    },
    "text": "string",
    "footer": {
      "text": "string"
    },
    "keyboard": {
      "rows": [
        {
          "buttons": [
            {
              "text": "string",
              "buttonType": "PHONE",
              "url": "string",
              "urlPostfix": "string",
              "phone": "string",
              "payload": "string",
              "urlTextExample": "string",
            }
          ]
        }
      ]
    },
    "textExampleParams": [
      "string"
    ],
    "contentType": "TEXT",
    "category": "ACCOUNT_UPDATE",
    "type": "OPERATOR",
  },
  "subjectIds": [
    0
  ],
  "smsProviderIds": [
    0
  ]
}

Template Parameters

General parameters:

Parameter	Data type	Obligatory	Description
`name`	string	yes	The name of the template. It can only contain Latin letters, numbers and underscores (_). The maximum length is 60 characters.
`channelType`	string	yes	The interaction channel type. Possible values: `WHATSAPP`, `VIBER`, `SMS`
`subjectIds`	integer	yes	The 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

Patameter	Data type	Obligatory	Description
`language`	string	yes	The template language in the WhatsApp Business Platform format.
`content`	object	yes	The object with the template contents.
`content.attachment`	object		The object with information about the attachment.
`content.attachment. fileUrl`	string		The URL of the file.
`content.attachment. originalFileName`	string		The name of the file.
`content.header`	object		The object with the header information.
`content.header.headerType`	string	yes (internal API) no (public API)	The header type: `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT`.
`content.header.text`	string		The header text.
`content.header.attachment`	object		The object with information about the file in the header.
`content.header.attachment. fileUrl`	string		The URL of the file in the header.
`content.header.attachment. originalFileName`	string		The file name in the header.
`content.header. headerExampleTextParam`	string	yes, if `headerType` = `TEXT`	An example of the title text.
`content.header. headerExampleMediaUrl`	string	yes, if `headerType` = `IMAGE`, `VIDEO` or `DOCUMENT`	The URL of the sample header file.
`content.text`	string	yes	The message text.
`content.footer`	object		The object with information about the signature.
`content.footer.text`	string		The footer text.
`content.keyboard.rows. buttons`	array of objects		The array of objects with information about buttons. The maximum allowed number of buttons in the template is 10.
`content.keyboard.rows. buttons.text`	string		The button name.
`content.keyboard.rows.` `buttons.buttonType`	string		The button type: `PHONE`, `URL`, `QUICK_REPLY`. 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	yes, if `buttonType` = `URL`	The URL that opens when pressing the button.
`content.keyboard.rows. buttons.urlPostfix`	string		The dynamic part of the link of the button URL.
`content.keyboard.rows. buttons.phone`	string	yes, if `buttonType` = `PHONE`	The number to be called when the button is pressed.
`content.keyboard.rows. buttons.payload`	string	yes, if `buttonType` = `QUICK_REPLY`	The quick response text.
`content.keyboard.rows. buttons.urlTextExample`	string	yes, if `buttonType` = URL	An example URL for the link button.
`content.textExampleParams`	array of strings	yes, if `channelType` = `WHATSAPP` and content.text contains variables	One example for each variable in the content.text parameter.
`contentType`	string		The 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.
`category`	string	yes	The 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.
`type`	string	yes	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). Important! Currently, only the `OPERATOR` type is supported.

Validation of WhatsApp Templates

When creating WhatsApp operator templates, consider the following limitations:

Limitation	Description
Channels	The created template can be used on all channels associated with the selected WhatsApp Business account.
Template name	The name can only contain Latin letters, numbers and underscores (_). The use of spaces and other characters is not allowed.
Attachments	Possible 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.
Placeholders	The maximum number of placeholders is 5.

Parameters for Viber Channels

Parameter	Data type	Obligatory	Description
`language`	string	yes	The template language is in ISO 639-1 format.
`content`	object	yes	The object with the template contents.
`content.action`	string		The URL of the button.
`content.caption`	string		The button name.
`content.text`	string	yes	The message text.
`contentType`	string		The content type. `TEXT` is a text message.
`category`	string	да	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`.
`type`	string	да	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

Parameter	Data type	Obligatory	Description
`content`	object	yes	The object with the template contents.
`content.text`	string	yes	The message text.
`type`	string	yes	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.
`smsProviderIds`	integer	yes	The 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
    ],
    "smsProviderIds": [
        2
    ]
}

{{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 SMS, Viber, WhatsApp.

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.

Errors

Code	Error	Description
`400`	`must not be nul`	The WhatsApp template category is not specified.
`400`	`message-matcher-category-invalid`	The WhatsApp template category is incorrect. Possible categories: • `MARKETING` • `AUTHENTICATION` • `UTILITY`
`400`	`message-matcher.saving.bad-request`	The example of a dynamic link for the WhatsApp template is not specified or is specified incorrectly.
`400`	`message-matcher-name-already-exists`	The template with the same name already exists. Possible message: • `Message matcher with specified channel type, tenantId and name already exists`
`400`	`message-matcher.saving.already-exists`	The template with the same content already exists.
`400`	`invalid language`	The template language code is incorrect.
`400`	`validation failure`	WhatsApp template validation error. Occurs if the maximum allowed number of buttons is exceeded in the WhatsApp template. Possible messages: • `Field content.buttons - Buttons max allowed count is 10` • `Field content.buttons - URL buttons max allowed count is 2` • `Field content.buttons - PHONE buttons max allowed count is 1`

Log in with a single edna account