Для запроса на создание операторского шаблона используется метод api/message-matchers
.
Вызов метода api/message-matchers
Чтобы вызвать метод api/message-matchers
, отправьте POST-запрос на URL-адрес https://app.edna.by/api/message-matchers
.
Если запрос выполнен успешно, создается операторский шаблон и метод возвращает ответ с кодом 200
. Если запрос выполнен неуспешно, метод возвращает код ошибки.
Формат тела запроса
{ "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 ] }
Общие параметры запроса
Параметр | Тип данных | Характер | Описание |
name | string | Обязательный | Название шаблона. В нем могут быть только латинские буквы, цифры и подчеркивание (_). Максимальное количество символов — 60. |
channelType | string | Обязательный | Тип канала, для которого надо создать операторский шаблон. Возможные значения: • WHATSAPP — канал WhatsApp;• VIBER — канал Viber;• SMS — канал SMS. |
subjectIds | integer | Обязательный | Массив идентификаторов подписи, для которых создается шаблон. Чтобы узнать идентификатор подписи канала, используйте метод получения списка каналов. |
Параметры запроса для канал WhatsApp
Параметр | Тип данных | Характер | Описание |
language | string | Обязательный | Язык шаблона в формате WhatsApp Business Platform. Список поддерживаемых языков смотрите на официальном сайте Meta*. |
content | object | Обязательный | Объект с содержимым шаблона. |
content.attachment | object | Необязательный | Объект с информацией о вложении. |
content.attachment. | string | Необязательный | URL-адрес файла. |
content.attachment. | string | Необязательный | Имя файла. |
content.header | object | Необязательный | Объект с информацией о заголовке. |
content.header.headerType | string | Обязательный (внутренний API-интерфейс) Необязательный (публичный API-интерфейс) | Тип заголовка. Возможные значения: • TEXT — текст;• IMAGE — изображение;• VIDEO — видео;• DOCUMENT — файл. |
content.header.text | string | Необязательный | Текст заголовка. |
content.header.attachment | object | Необязательный | Объект с информацией о файле в заголовке. |
content.header.attachment. | string | Необязательный | URL-адрес файла в заголовке. |
content.header.attachment. | string | Необязательный | Имя файла в заголовке. |
content.header. headerExampleTextParam | string | Обязательный, если headerType =TEXT | Пример текста заголовка. |
content.header. | string | Обязательный, если headerType =IMAGE , VIDEO или DOCUMENT | URL-адрес примера файла заголовка. |
content.text | string | Обязательный | Текст сообщения. |
content.footer | object | Необязательный | Объект с информацией о подписи. |
content.footer.text | string | Необязательный | Текст подписи. |
content.keyboard.rows. | object | Необязательный | Объект с информацией о кнопках. |
content.keyboard.rows. | string | Необязательный | Название кнопки. |
content.keyboard.rows. | string | Необязательный | Тип кнопки. Возможные значения: • PHONE — кнопка-звонок;• URL — кнопка-ссылка;• QUICK_REPLY — кнопка быстрого ответа. |
content.keyboard.rows. | string | Обязательный, если buttonType = URL | URL-адрес, который открывается при нажатии кнопки. |
content.keyboard.rows. | string | Необязательный | Динамическая часть ссылки URL-адреса кнопки. |
content.keyboard.rows. | string | Обязательный, если buttonType = PHONE | Номер телефона, который набирается при нажатии кнопки. |
content.keyboard.rows. | string | Обязательный, если buttonType = QUICK_REPLY | Текст быстрого ответа. |
content.keyboard.rows. | string | Обязательный, если buttonType = URL | Пример URL-адреса для кнопки-ссылки. |
content.textExampleParams | array of strings | Обязательный, если channelType = WHATSAPP и content.text содержит переменные | Пример на каждую переменную в параметре content.text . |
contentType | string | Необязательный | Тип содержимого. Возможные значения: • TEXT — текстовое сообщение;• IMAGE — изображение;• BUTTON — кнопка;• DOCUMENT — файл, вложенный в сообщение;• LOCATION — сообщение с координатами, адресом и описанием места (координаты преобразуются в снимок Google Maps);• AUDIO — сообщение с аудио;• VIDEO — сообщение с видео;• AUTHENTICATION — сообщение с одноразовым паролем. |
category | string | Обязательный | Категория шаблона. Возможные значения: • MARKETING — новости о компании, предложения с акциями и скидками, информация о мероприятиях и вебинарах;• AUTHENTICATION — коды для личного кабинета или приложения для безопасного доступ к учетным записям пользователей, обновление данных или настроек учетной записи, окончание подписки, изменение пароля;• UTILITY — информация об изменениях в учетной записи, статусе заказа или программе лояльности, уведомление о получении платежа, подтверждение денежных переводов, прочие транзакции в сфере финансовых услуг.Создание шаблонов категории AUTHENTICATION временно ограничено. |
type | string | Обязательный | Тип шаблона. Возможные значения: • OPERATOR — операторский шаблон, зарегистрированный у оператора связи;• USER — пользовательский шаблон, созданный пользователем на основе операторского.Поддерживается только тип шаблона OPERATOR . |
Валидация шаблонов WhatsApp
При создании операторских шаблонов WhatsApp учитывайте следующие ограничения:
Ограничение | Описание |
Каналы | Созданный шаблон можно использовать на всех каналах, привязанных к выбранному аккаунту WhatsApp Business. |
Название шаблона | В названии можно использовать только латинские буквы, цифры и символ (_). Использование пробелов и других символов не допускается. |
Вложения | Возможные типы вложений: • изображение (JPEG, JPG, PNG); • видео (MP4, 3GPP, 3GPP); • документ (PDF). Можно выбрать только один тип вложения для отправки в шаблоне. |
Текст сообщения шаблона | • Поле с текстом обязательно для заполнения. • Максимальное количество символов в тексте сообщения с учетом текста в строке символов — 1024. В дополнение к тексту допускается использование переменных. • Текст не должен содержать символов новой строки. • Текст не должен содержать символов 4-х и более последовательных пробелов. |
Переменные в тексте сообщения | • Переменная не должна содержать перенос строки. При использовании переноса изменения не сохраняются. • Максимальное количество символов в значении переменной — 512. • Переменные должны быть указаны с двумя двойными фигурными скобками в начале и в конце. • Использование одинарных скобок не допускается. |
Текстовый заголовок | • Поля с текстом и типом заголовка обязательны для заполнения. • Максимальное количество символов в текстовом заголовке — 60. • В текстовый заголовок можно добавить одну переменную. • В начале и в конце заголовка нельзя использовать пробелы. |
Подпись | • Поле с подписью обязательно для заполнения. • Максимальное количество символов в подписи — 60. • Использование переменных не допускается. • В начале и в конце подписи нельзя использовать пробелы. |
Кнопки | • Максимальное количество символов в названии кнопки — 25. • При добавлении кнопки должен быть указан ее тип, все поля обязательны для заполнения. |
Кнопка Быстрый ответ (QUICK_REPLY ) | • Название кнопки согласуется вместе с текстом шаблона без возможности изменения в настройках. • Максимальное количество символов в коде кнопки — 250. • В одном шаблоне может быть не более 3 кнопок этого типа. • Эту кнопку нельзя использовать вместе с кнопками типа Ссылка или Номер. • После нажатия открывается 24-часовое окно. • Нажатие расценивается как ответное сообщение с возможностью открыть переписку. • Кнопку можно нажать только один раз. |
Кнопка Ссылка (URL ) | • Максимальное количество символов в ссылке — 2000. • Доступна проверка работоспособности URL. • При нажатии выполняется переход по заранее согласованной ссылке. • В рамках одного шаблона этот тип кнопок совместим только с кнопками типа Номер. • Нажатие на кнопку не расценивается как ответ пользователя. • Кнопку можно использовать несколько раз. |
Кнопка Номер (PHONE_NUMBER ) | • При нажатии происходит набор указанного номера телефона. • Номер телефона должен быть указан в международном формате (символ «+» в начале), допустимое количество цифр в номере — 10–19. • Звонить можно только через мобильное приложение WhatsApp. • В рамках одного шаблона этот тип кнопок совместим только с кнопками типа Ссылка. • Нажатие на кнопку не расценивается как ответ пользователя. • Кнопку можно использовать несколько раз. |
Текст-заполнитель | Максимальное количество текстов-заполнителей — 5. |
Параметры запроса для канала Viber
Параметр | Тип данных | Характер | Описание |
language | string | Обязательный | Язык шаблона в формате ISO 639-1. |
content | object | Обязательный | Объект с содержимым шаблона. |
content.action | string | Необязательный | URL-адрес кнопки. |
content.caption | string | Необязательный | Название кнопки. |
content.text | string | Обязательный | Текст сообщения. |
contentType | string | Необязательный | Тип содержимого. Возможные значения: • TEXT — текстовое сообщение. |
category | string | Обязательный | Категория шаблона. Возможные значения: • 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 | Обязательный | Тип шаблона. Возможные значения: • OPERATOR — операторский шаблон, зарегистрированный у оператора связи;• USER — пользовательский шаблон, созданный пользователем на основе операторского;• CUSTOM — свободный шаблон с разрешенным для указанного канала контентом.Поддерживается только тип OPERATOR . |
Параметры запроса для канала SMS
Параметр | Тип данных | Характер | Описание |
content | object | Обязательный | Объект с содержимым шаблона. |
content.text | string | Обязательный | Текст сообщения. |
type | string | Обязательный | Тип шаблона. Возможные значения: • OPERATOR — операторский шаблон, зарегистрированный у оператора связи. |
smsProviderCodes | string | Обязательный | Названия операторов связи, для которых регистрируется шаблон SMS. Возможные значения: • mts — МТС;• megafon — Мегафон;• tele2 — Тele2;• beeline — Билайн;• motiv — Мотив. |
category | string | Обязательный | Категория шаблона. Возможные значения: • AUTHORIZATION — авторизационный шаблон;• TEMPLATE_ADV — шаблонируемая реклама;• SERVICE — сервисный шаблон. |
Примеры шаблонов
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": "Здравствуйте, %w{1,5}! Спасибо, что выбрали нас." }, "category": "TRANSACTIONAL", "type": "OPERATOR" }, "subjectIds": [ 2234 ] }
SMS:
{ "messageMatcher": { "name": "new_matcher", "channelType": "SMS", "language": "RU", "content": { "text": "Здравствуйте, %w{1,5}! Спасибо, что выбрали нас." }, "category": "MARKETING", "type": "OPERATOR", "createdAt": "2022-05-05T11:34:34.844Z", "updatedAt": "2022-05-05T11:34:34.844Z" }, "subjectIds": [ 2234 ], "smsProviderCodes": "beeline" }
{{1}}
, [\s\w]+
и %w{1,n}
— это символы элементов автоподстановки, вместо которых можно указывать любые значения. У каждого провайдера свои правила использования этих элементов.
Примеры запросов на отправку сообщений смотрите в статье.
Формат ответа
В ответ на запрос возвращается 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 | Шаблон с таким названием уже существует. |
message-matcher.saving.already-exists | Шаблон с таким содержанием уже существует. |
invalid language | Указан неверный код языка шаблона. |
validation failure | Ошибка валидации шаблона WhatsApp. |