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

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.
type	string	да	Тип шаблона. Возможные значения: • `OPERATOR` — операторский шаблон (шаблон, который был зарегистрирован у оператора связи); • `USER` — пользовательский шаблон (шаблон, который был создан пользователем на основе операторского шаблона). ВАЖНО! В настоящее время поддерживается только тип `OPERATOR`.

Параметры шаблона для канала 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` — операторский шаблон (шаблон, который был зарегистрирован у оператора связи); • `USER` — пользовательский шаблон (шаблон, который был создан пользователем на основе операторского шаблона); • `CUSTOM` — шаблон «с нуля» без каких-либо ограничений, который может содержать любой контент, разрешенный для этого канала. ВАЖНО! В настоящее время поддерживается только тип `OPERATOR`.
smsProviderIds	integer	да	ID SMS-операторов, для которых регистрируется SMS шаблон. Значения: • `0` — МТС • `1` — Билайн • `2` — Мегафон • `3` — Теле2

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

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

{
    "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} — это элементы автоподстановки, то есть строки символов, вместо которых можно указывать любые значения. У каждого провайдера есть собственные правила использования таких элементов, подробнее читайте в статьях: 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 — указан неверный код языка шаблона

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

Cледующая статья Получение статуса шаблона

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