Отправка HSM сообщения (imOutHSM)

Метод, описанный в этой статье, предназначен только для SME.

HSM это сообщение, которое следует строго установленной форме — шаблону. Компания WhatsApp ограничивает содержание текстов, с помощью которых можно начинать общение с клиентом (функция “Писать первым”) . Таким сообщением и является заранее утвержденный шаблон (HSM). В результате выполнения запроса будет отправлено сообщение от сервера, содержащее JSON. Клиент сможет продолжить диалог спустя 24 часа от последнего сообщения клиента.

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

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

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

В теле запроса передается JSON-объект с параметрами сообщения. Набор параметров зависит от типа HSM сообщения и его содержимого: текст, изображение, документ, аудио или видео.

Примеры

  • Текст:
{
    "id": "test-001",
    "subject": "test",
    "address": "7900000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Уважаемый клиент! Меня зовут Иван. Ваше обращение №785 было рассмотрено и принято положительное решение."
}
  • Текст и заголовок:
{
    "id": "test-001",
    "subject": "test",
    "address": "7900000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Меня зовут Андрей. Ваше обращение №785 было рассмотрено и принято положительное решение.",
    "header": {
        "text": "Уважаемый Евгений Анатольевич!"
    }
}
  • Текст и подпись:
{
    "id": "test-001",
    "subject": "test",
    "address": "7900000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Добрый день, Николай! Информируем Вас, что заказ №77 отправлен.",
    "footer": {
        "text": "С уважением, Edna"
    }
}
  • Текст, заголовок и подпись:
{
    "id": "test-001",
    "subject": "test",
    "address": "7900000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Добрый день, Николай! Информируем Вас, что заказ №77 отправлен.",
    "header": {
        "imageUrl": "https://cdn.maikoapp.com/3d4b/4qgko/200.jpg"
    },
    "footer": {
        "text": "С уважением, Edna"
    }
}
  • Текст и чат-кнопка:
{
"id": "test-001",
"subject": "test",
"address": "7900000000",
"imType":"whatsapp",
"contentType": "text",
"text": "Добрый день, Николай! Информируем Вас, что заказ №77 отправлен.",
  "keyboard": {
    "row": {
      "buttons": [
        {
          "text": "Yes",
          "buttonType": "QUICK_REPLY",
          "payload": "your_code"
        }
      ]
    }
}
}
  • Текст и кнопка-ссылка:
{
    "id": "test-001",
    "subject": "test",
    "address": "7900000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Добрый день, спасибо, что зашли к нам в офис! \nБыли рады вас видеть!\nВы можете записаться на следующий прием в наш офис по ссылке ниже.",
    "keyboard": {
        "row": {
            "buttons": [
                {
                    "text": "Записаться",
                    "buttonType": "URL",
                    "url": "https://im.edna.ru"
                }
            ]
        }
    }
}
  • Текст и кнопка-звонок:
{
    "id": "test-001",
    "subject": "test",
    "address": "7900000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Добрый день, спасибо, что зашли к нам в офис! \nБыли рады вас видеть!\nЕсли у вас остались вопросы, то можете позвонить нашему оператору",
    "keyboard": {
        "row": {
            "buttons": [
                {
                    "text": "Позвонить",
                    "buttonType": "PHONE",
                    "phone": "7900000000"
                }
            ]
        }
    }
}
  • Сочетание текста, заголовка, кнопки-звонка и кнопки-ссылки:
{
    "id": "967i112b-d190-470c-9826-7783433000b0",
    "subject": "test",
    "address": "79000000000",
    "imType": "whatsapp",
    "contentType": "text",
    "text": "Андрей, привет. Вот ваш посадочный билет на рейс 898.\n Спасибо что летаете с нами",
    "header": {
        "documentUrl": "https://yourboardingpass.edna.com/pass/id9890",
        "documentName": "sample_name.pdf"
    },
    "footer": {
        "text": "Что бы управлять вашей бронью, перейдите на наш портал"
    }
    "keyboard": {
        "row": {
            "buttons": [
                {
                    "text": "Связаться с нами",
                    "buttonType": "PHONE",
                    "phone": "7900000000"
                },
                {
                    "text": "Управлять бронированием",
                    "buttonType": "URL",
                    "url": "https://im.edna.ru"
                }
            ]
        }
    }
}

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

ПараметрТип данныхОписание
idstringИдентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Допускается любая длинна строки до 36 символов.
subjectstringТекст подписи в сообщении. 

Важно! Все подписи необходимо предварительно зарегистрировать в платформе. Иначе, сообщение не будет доставлено.
addressstringНомер абонента WhatsApp, на который будет отправлено сообщение в формате 79ХХХХХХХХХХ.
prioritystring (optional)Приоритет сообщения, влияет на время доставки сообщения. Возможные значения:

realtime — сообщение должно быть доставлено немедленно
high — сообщение с высоким приоритетом
normal — сообщение со стандартным приоритетом
low — сообщение с низким приоритетом
startTimestring (optional)Время, раньше которого сообщение не будет отправлено. Используется при отложенной отправке. Формат:

• YYYY-MM-DDTHH:mm:ss.SSSXXX (2020-06-12T15:30:10.000Z)
• YYYY-MM-DDTHH:mm:ss.SSS+TZ (2020-06-12T15:30:10.000+03:00)
validityPeriodSecondsint (optional)Время (в секундах), в течении которого должно быть доставлено сообщение. Если сообщение не может быть доставлено в течение этого времени (например, абонент не доступен), значит оно не будет доставлено вовсе. Значение по умолчанию — 1 сутки. Минимальное значение 30, максимальное 86400. Рекомендуется использовать 86400, так как WhatsApp округляет значение до полных суток.
imTypestring (optional)whatsapp или Viber
contentTypestringТип содержимого сообщения. Возможные значения:

text — текстовое сообщение
textstringТекст сообщения согласно утвержденному шаблону HSM
headerobject (optional)Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную {{1}}. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение. В настоящий момент для шаблонов сообщений с медиафайлами поддерживаются только документы в формате PDF.
footerobject (optional)Подпись. Отображается под сообщением приглушенным цветом текста
buttonsobject (optional)Массив объектов в каждом из которых определяется кнопка. Виды кнопок:

• Текст
• Ссылка
• Телефон
• Payload — возвращает входящее сообщение

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

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

{
  "id": "test-001",
  "code": "ok"
}

Параметры ответа

ПараметрТип данныхОписание
idstringИдентификатор сообщения
codestringКод ответа для данного сообщения. Возможные значения
Получение статуса доставки сообщения (imOutMessageId)
Cледующая статья Получение списка шаблонов HSM (getOutMessageMatchers)