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

KB Home
API
API edna Pulse
Шаблоны
Создание операторских шаблонов

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

Метод message-matchers

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

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

Для отправки сообщения выполняется POST-запрос на URL-адрес https://app.edna.ru/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
  ]
}

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

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

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

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

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

Параметр	Тип данных	Обязательный	Описание
`language`	string	да	Язык шаблона в формате WhatsApp Business Platform. Список поддерживаемых языков смотрите на официальном сайте Meta*.
`content`	object	да	Объект с содержимым шаблона.
`content.attachment`	object		Объект с информацией о вложении.
`content.attachment. fileUrl`	string		URL-адрес файла.
`content.attachment. originalFileName`	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. fileUrl`	string		URL-адрес файла в заголовке.
`content.header.attachment. originalFileName`	string		Имя файла в заголовке.
content.header. headerExampleTextParam	string	да, если `headerType` = `TEXT`	Пример текста заголовка.
`content.header. headerExampleMediaUrl`	string	да, если `headerType` = `IMAGE`, `VIDEO` или `DOCUMENT`	URL-адрес примера файла заголовка.
`content.text`	string	да	Текст сообщения.
`content.footer`	object		Объект с информацией о подписи.
`content.footer.text`	string		Текст подписи.
`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` = `URL`	URL-адрес, который открывается при нажатии кнопки.
`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.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-операторов, для которых регистрируется 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": "Здравствуйте, [\s\w]+! Спасибо, что выбрали нас."
        },
        "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} — это элементы автоподстановки, то есть строки символов, вместо которых можно указывать любые значения. У каждого провайдера свои правила использования этих элементов. Подробнее читайте в статьях SMS, Viber, WhatsApp.

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

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

В ответ на запрос возвращается 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.

* Деятельность компании Meta запрещена на территории Российской Федерации.

Войти с единой учетной записью edna