--> --> --> -->

Создание операторских шаблонов

31 May 2022

В статье описан метод API для создания операторских шаблонов.

Метод message-matchers

В результате выполнения запроса создается операторский шаблон. В случае успешного выполнения запроса клиент получает ответ от сервера с кодом 200. В обратном случае приходит сообщение с кодом ошибки.

URL-адрес подключения

Для отправки сообщения выполняется POST-запрос на URL-адрес https://app.edna.by/api/message-matchers.

Формат запроса

В теле запроса передается JSON-объект с параметрами.

{
  "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
  ]
}

Параметры шаблонов

Общие параметры:

ПараметрТип данныхОбяза
тельный		Описание
namestringдаНазвание шаблона. В нем могут быть только латинские буквы, цифры и подчеркивание (_). Максимальное количество символов — 60.
channelTypestringдаТип канала взаимодействия. Возможные значения: WHATSAPP, VIBER, SMS.
subjectIdsintegerдаМассив идентификаторов подписи, для которых создаётся шаблон. Чтобы узнать идентификатор подписи канала, используйте метод получения списка каналов.

Параметры для конкретных каналов перечислены в таблицах ниже.

Параметры для каналов WhatsApp

ПараметрТип данныхОбязательныйОписание
languagestringдаЯзык шаблона в формате WhatsApp Business Platform.
Список поддерживаемых языков смотрите на официальном сайте Meta*.
contentobjectдаОбъект с содержимым шаблона.
content.attachmentobjectОбъект с информацией о вложении.
content.attachment.
fileUrl		stringURL-адрес файла.
content.attachment.
originalFileName		stringИмя файла.
content.headerobjectОбъект с информацией о заголовке.
content.header.headerTypestring— да (внутренний API-интерфейс)
— нет (публичный API-интерфейс)		Тип заголовка: TEXT, IMAGE, VIDEO, DOCUMENT.
content.header.textstringТекст заголовка.
content.header.attachmentobjectОбъект с информацией о файле в заголовке.
content.header.attachment.
fileUrl		stringURL-адрес файла в заголовке.
content.header.attachment.
originalFileName		stringИмя файла в заголовке.
content.header.
headerExampleTextParam		stringда, если headerType =
TEXT		Пример текста заголовка.
content.header.
headerExampleMediaUrl		stringда, если headerType =
IMAGE, VIDEO или DOCUMENT		URL-адрес примера файла заголовка.
content.textstringдаТекст сообщения.
content.footerobjectОбъект с информацией о подписи.
content.footer.textstringТекст подписи.
content.keyboard.rows.
buttons		objectОбъект с информацией о кнопках.
content.keyboard.rows.
buttons.text		stringНазвание кнопки.
content.keyboard.rows.
buttons.buttonType		stringТип кнопки: PHONE, URL, QUICK_REPLY.
content.keyboard.rows.
buttons.url		stringда, если buttonType = URLURL-адрес, который открывается при нажатии кнопки.
content.keyboard.rows.
buttons.urlPostfix		stringДинамическая часть ссылки URL-адреса кнопки.
content.keyboard.rows.
buttons.phone		stringда, если buttonType = PHONEНомер телефона, который набирается при нажатии кнопки.
content.keyboard.rows.
buttons.payload		stringда, если buttonType = QUICK_REPLYТекст быстрого ответа.
content.keyboard.rows.
buttons.urlTextExample		stringда, если buttonType = URLПример URL-адреса для кнопки-ссылки.
content.textExampleParamsarray of stringsда, если channelType = WHATSAPP и content.text содержит переменныеПо одному примеру на каждую переменную в параметре content.text.
contentTypestringТип содержимого:
• TEXT — текстовое сообщение;
• IMAGE — изображение;
• BUTTON — кнопка;
• DOCUMENT — документ, вложенный в сообщение;
• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google Maps;
• AUDIO — сообщение со звуком;
• VIDEO — сообщение с видео;
• AUTHENTICATION — сообщение с одноразовым паролем.
categorystringдаКатегория шаблона. Возможные значения:
• MARKETING — новости о компании, предложения с акциями и скидками, информация о мероприятиях и вебинарах и т.д;
• AUTHENTICATION — коды для личного кабинета или приложения для безопасного доступ к учетным записям пользователей; обновление данных или настроек учетной записи, окончание подписки, изменение пароля;
• UTILITY — информация об изменениях в учетной записи, статусе заказа или программе лояльности; уведомление о получении платежа, подтверждение денежных переводов, прочие транзакции в сфере финансовых услуг.

ВАЖНО! Создание шаблонов категории AUTHENTICATION временно ограничено.
typestringдаТип шаблона. Возможные значения:
• OPERATOR — операторский шаблон (шаблон, зарегистрированный у оператора связи);
• USER — пользовательский шаблон (шаблон, созданный пользователем на основе операторского шаблона).

ВАЖНО! В настоящее время поддерживается только тип OPERATOR.

Валидация шаблонов WhatsApp

При создании операторских шаблонов WhatsApp учитывайте следующие ограничения:

ОграничениеОписание
КаналыСозданный шаблон можно использовать на всех каналах, привязанных к выбранному аккаунту WhatsApp Business.
Название шаблонаВ названии можно использовать только латинские буквы, цифры и символ (_). Использование пробелов и других символов не допускается.
ВложенияВозможные типы вложений:
• изображение (.jpeg, .jpg, .png);
• видео (.mp4, .3gpp);
• документ (.pdf).
Можно выбрать только один тип вложения для отправки в шаблоне.
Текст сообщения шаблона• Максимальное количество символов в тексте сообщения с учетом текста в строке символов — 1024. В дополнение к тексту допускается использование переменных.
• Текст не должен содержать символов новой строки.
• Текст не должен содержать символов 4-х и более последовательных пробелов.
Переменные в тексте сообщения• Переменная не должна содержать перенос строки. При использовании переноса изменения не сохраняются.
• Максимальное количество символов в значении переменной — 512. 
• Переменные должны быть указаны с двумя двойными фигурными скобками в начале и в конце.
• Использование одинарных скобок не допускается.
Символы в заголовке• Максимальное количество символов в текстовом заголовке — 60.
• В текстовый заголовок можно добавить одну переменную.
Подпись• Максимальное количество символов в подписи — 60.
• Использование переменных не допускается.
Кнопки• В одном шаблоне может быть не более одной кнопки каждого типа.
• Максимальное количество символов в названии кнопки — 25.
Кнопка Быстрый ответ (QUICK_REPLY)• Название кнопки согласуется вместе с текстом шаблона без возможности изменения в настройках.
• В одном шаблоне может быть не более 3 кнопок этого типа.
• После нажатия открывается 24-часовое окно.
• Нажатие расценивается как ответное сообщение с возможностью открыть переписку.
• Кнопку можно нажать только один раз.
Кнопка Ссылка (URL)• При нажатии выполняется переход по заранее согласованной ссылке.
• В рамках одного шаблона этот тип кнопок совместим только с кнопками типа Номер.
• Нажатие на кнопку не расценивается как ответ пользователя.
• Кнопку можно использовать несколько раз.
Кнопка Номер (PHONE_NUMBER)• При нажатии происходит набор указанного номера телефона.
• Указание номера телефона: разрешенный формат + код страны.
• Звонить можно только через мобильное приложение WhatsApp.
• В рамках одного шаблона этот тип кнопок совместим только с кнопками типа Ссылка.
• Нажатие на кнопку не расценивается как ответ пользователя.
• Кнопку можно использовать несколько раз.
Текст-заполнительМаксимальное количество текстов-заполнителей — 5.

Параметры для каналов Viber

ПараметрТип данныхОбяза
тельный		Описание
languagestringдаЯзык шаблона в формате ISO 639-1.
contentobjectдаОбъект с содержимым шаблона.
content.actionstringURL-адрес кнопки.
content.captionstringНазвание кнопки.
content.textstringдаТекст сообщения.
contentTypestringТип содержимого. TEXT — текстовое сообщение.
categorystringдаКатегория шаблона. Возможные значения: 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даТип шаблона. Возможные значения:
• OPERATOR — операторский шаблон (шаблон, который был зарегистрирован у оператора связи);
• USER — пользовательский шаблон (шаблон, который был создан пользователем на основе операторского шаблона);
• CUSTOM — шаблон «с нуля» без каких-либо ограничений, который может содержать любой контент, разрешенный для этого канала.

ВАЖНО! В настоящее время поддерживается только тип OPERATOR.

Параметры для каналов SMS

ПараметрТип данныхОбяза
тельный		Описание
contentobjectдаОбъект с содержимым шаблона.
content.textstringдаТекст сообщения.
typestringдаТип шаблона. Возможные значения:
• OPERATOR — операторский шаблон (шаблон, зарегистрированный у оператора связи);
• USER — пользовательский шаблон (шаблон, созданный пользователем на основе операторского шаблона);
• CUSTOM — шаблон «с нуля» без ограничений с любым содержанием, разрешенным для этого канала.

ВАЖНО! В настоящее время поддерживается только тип OPERATOR.
smsProviderIdsintegerдаID SMS-операторов, для которых регистрируется SMS-шаблон. Значения:
• 0 — МТС;
• 1 — Билайн;
• 2 — Мегафон;
• 3 — Тele2.

Примеры шаблонов

  • WhatsApp HSM с переменными в тексте шаблона
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "RU",
        "content": {
            "header": {
                "text": "Ваша компания {{1}}",
                "headerExampleTextParam": "Солнышко"
            },
            "text": "Здравствуйте, {{1}}! Спасибо, что выбрали нас {{2}}",
            "textExampleParams": [
                "Николай",
                "Пример"
            ],
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Сайт",
                                "buttonType": "URL",
                                "url": "https://edna.ru/{{1}}",
                                "urlTextExample": "https://edna.ru/test"
                            },
                            {
                                "text": "Позвонить",
                                "buttonType": "PHONE",
                                "phone": "+7900000000"
                            }
                        ]
                    }
                ]
            },
            "footer": {
                "text": "Спасибо за интерес"
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}
  • WhatsApp HSM с кнопками
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "RU",
        "content": {
            "header": {
                "text": "Ваш чат с edna"
            },
            "text": "Здравствуйте! Спасибо, что выбрали нас.",
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Да",
                                "buttonType": "QUICK_REPLY",
                                "payload": "1"
                            },
                            {
                                "text": "Нет",
                                "buttonType": "QUICK_REPLY",
                                "payload": "2"
                            },
                            {
                                "text": "Не знаю",
                                "buttonType": "QUICK_REPLY",
                                "payload": "3"
                            }
                        ]
                    }
                ]
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}
  • Viber
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "VIBER",
        "language": "RU",
        "content": {
            "text": "Здравствуйте, [\s\w]+! Спасибо, что выбрали нас."
        },
        "category": "TRANSACTIONAL",
        "type": "OPERATOR"
    },
    "subjectIds": [
        2234
    ]
}
  • SMS
{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "SMS",
        "language": "RU",
        "content": {
            "text": "Здравствуйте, %w{1,10}! Спасибо, что выбрали нас."
        },
        "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]+ и %w{1,10} — это элементы автоподстановки, то есть строки символов, вместо которых можно указывать любые значения. У каждого провайдера свои правила использования этих элементов.

Примеры запросов на отправку сообщений см. в статье Примеры отправки сообщений.

Формат ответа

В ответ на запрос возвращается JSON-объект, содержащий код выполнения запроса.

Коды ответов на запрос

Код ответаОписание
okЗапрос выполнен успешно.
must not be nullНе указана категория шаблона WhatsApp.
message-matcher-category-invalidУказана неверная категория шаблона WhatsApp. Возможные категории: MARKETING, AUTHENTICATION, UTILITY.
message-matcher.saving.bad-requestПример динамической ссылки для шаблона WhatsApp не указан или указан неверно.
message-matcher-name-already-existsШаблон с таким названием или содержанием уже существует.
invalid languageУказан неверный код языка шаблона.
validation failureОшибка валидации шаблона WhatsApp.
* Деятельность компании запрещена на территории РФ.
In this article
In this article