Форматы вебхуков чатов

Каждый хук содержит заголовок X-Signature, который рассчитывается только от тела запроса методом HMAC-SHA1. В качестве секрета используется секрет канала.

Для каждого сообщения отправленного из amoCRM в канал чата, формируется хук. Хук отправляется только один раз и не повторяется в случае ошибок при получении на стороне интеграции.
Время ответа на хук тоже ограничено, поэтому хорошей практикой считается обработка бизнес логики в фоне, а при приеме хука только проверять подпись запроса.

Оглавление

Хук сообщения v1

Описание

Хук отправляется, если при подключении канала аккаунта выставлена версия хука v1

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

Параметр Тип данных Описание
receiver string Идентификатор учаcтника чата (клиента) на стороне интеграции
conversation_id string Идентификатор чата на стороне интеграции
type string Тип сообщений, может быть одним из списка: text,file,video,picture
media string Url на картинку,файл,видео
thumbnail string Поле содержит url на предпросмотр, актуально только для типа picture,video
file_name string Название файла для url в поле media
file_size int Размер данных в байтах поля media
msec_timestamp int Время сообщения, метка unix c миллисекундами

Пример запроса

{
  "receiver": "b55770b5-974f-4dd6-8dd3-0356c08dc600",
  "conversation_id": "a4a5ab10-ea6f-4af4-8514-a8265e5c71bd",
  "msec_timestamp": 1596470952116,
  "type": "text",
  "text": "Можете уточнить адрес доставки заказа ?",
  "media": "",
  "thumbnail": "",
  "file_name": "",
  "file_size": 0
}

HTTP коды ответа

Код ответа Условие
200 Хук успешно обработан

Хук сообщения v2

Описание

Хук отправляется, если при подключении канала аккаунта выставлена версия хука v2

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

Параметр Тип данных Описание
account_id string Идентификатор чата на стороне интеграции
time int Время генерации хука, метка unix
message[sender][id] string Идентификатор участника чата amojo
message[receiver][id] string Идентификатор участника чата на стороне интеграции
message[receiver][phone] string Поле отсутствует, если не передавался профиль
message[receiver][email] string Поле отсутствует, если не передавался профиль
message[timestamp] int Время сообщения, метка unix
message[msec_timestamp] int Время сообщения, метка unix c миллисекундами
message[message][id] string Идентификатор сообщения amojo
message[message][type] string Тип сообщений, может быть одним из списка: text,file,video,picture,voice,audio,sticker
message[message][text] string Для типа text обязательно, для других типов сообщений может быть пустым
message[message][media] string Url на картинку,файл,видео,аудио,голос,стикер.
message[message][thumbnail] string Поле содержит url на предпросмотр, актуально только для типа picture,video
message[message][file_name] string Название файла для url в поле media
message[message][file_size] int Размер данных в байтах поля media

Пример запроса

{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "time": 1596470952,
  "message": {
    "receiver": {
      "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
      "phone": "79151112233",
      "email": "example.client@example.com"
    },
    "sender": {
      "id": "d8d9f9c4-9611-4794-a136-a253a13e1bb5"
    },
    "conversation": {
      "id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217"
    },
    "timestamp": 1596470952,
    "msec_timestamp": 1596470952116,
    "message": {
      "id": "c0a83937-3ed9-4774-9582-77224f7b9117",
      "type": "picture",
      "text": "",
      "media": "https://about.gitlab.com/images/blogimages/security-cover-new.png",
      "thumbnail": "",
      "file_name": "security-cover-new.png",
      "file_size": 223732
    }
  }
}

HTTP коды ответа

Код ответа Условие
200 Хук успешно обработан

Клавиатура в сообщениях

Описание

Хуки сообщений поддерживают разметку клавиатуры amoCRM.
Клавиатура это массив массивов кнопок с указанным способом их расположения. Способ расположения указывается в поле mode. Если указан параметр inline, то клавиатура отображаются под текстом сообщения.

Схема разметки клавиатуры

Параметр Тип данных Описание
mode string Способ расположения клавиатуры. Возможные значения: inline — кнопки отображаются под текстом сообщения
buttons button[][] Массив массивов с кнопками

Структура кнопок

Параметр Тип данных Описание
text string Текст, который по нажатию на кнопку будет отправлен в чат amoCRM
url string Ссылка, которую необходимо открыть по нажатию на кнопку

Пример разметки клавиатуры

{
  "mode":"inline",
  "buttons":[
    [
      {
        "text":"Принять заказ"
      },
      {
        "text":"Отменить заказ"
      }
    ]
  ]
}

Текстовые кнопки

Кнопки у которых заполнено поле text. Когда пользователь нажимает на текстовую кнопку, интегратору необходимо отправить сообщение с текстом этой кнопки в чат amoCRM. Отправка осуществляется посредству API отправки сообщения. Подробнее можно ознакомится на странице метода

Ссылочные кнопки

Кнопки у которых заполнено поле url. Когда пользователь нажимает на ссылочную кнопку интегратору, необходимо осуществить переход по этой ссылке.