Создание шаблона

31 мая 2022

Статья содержит описание метода 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
  ]
}

Параметры запроса

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

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

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

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

ПараметрТип данныхОбязательныйОписание
languagestringдаЯзык шаблона в формате WhatsApp Business Platform
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.
typestringдаТип шаблона. Возможные значения:
• OPERATOR — операторский шаблон (шаблон, который был зарегистрирован у оператора связи);
• USER — пользовательский шаблон (шаблон, который был создан пользователем на основе операторского шаблона).

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

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

Cледующая статья Получение статуса шаблона
In this article
Разделы статьи