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

В данный момент существует несколько видов хуков:

  • Для каждого сообщения отправленного из amoCRM в канал чата
    • Есть 2 версии данных хуков. v1 и v2. v1 является устаревшим и больше не поддерживается.
  • Для событий "Менеджер печатает" (требуется отдельная подписка на хук для каждого канала через техническую поддержку)

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

Оглавление

Проверка подлинности хуков

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

Пример на PHP:

$secret = '5a44c5dff55f3c15a4cce8d7c4cc27e207c7e189';
$str = file_get_contents('php://input');
$signature = hash_hmac('sha1', $str, $secret);

if (isset($_SERVER['HTTP_X_SIGNATURE']) && $signature === $_SERVER['HTTP_X_SIGNATURE']) {
    //valid hook
}

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

Описание

Хук отправляется при отправке сообщений из amoCRM, если при подключении канала аккаунта выставлена версия хука v2.
Необязательные поля могут не приходить в хуке.

Важно отметить, что сообщение может прийти одновременно с медиа, текстом и кнопками.
Также стоит отметить, что при отправке нескольких вложений за раз, сообщение будет разбито на несколько хуков,
но у них будет общий message[message][media_group_id].

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

Параметр Тип данных Описание
account_id string ID аккаунта в API чатов
time int Время генерации хука, метка unix
message[conversation] object Объект с информацией о чате. Описание объекта
message[source] object Объект с информацией об источнике. Описание объекта
message[sender] object Объект с информацией об отправителе сообщения. Описание объекта
message[receiver] object Объект с информацией о получатели сообщения. Описание объекта
message[timestamp] int Время сообщения, метка unix
message[msec_timestamp] int Время сообщения, метка unix c миллисекундами
message[message] object Объект с информацией об отправляемом сообщении. Описание объекта
Описание объекта conversation
Параметр Тип данных Описание
id string Идентификатор чата в API чатов
client_id string Идентификатор чата на стороне интеграции. Необязательное поле. Если чат создан через функцию "Написать первым", поле будет отсутствовать в хуке
Описание объекта source
Параметр Тип данных Описание
external_id string Идентификатор источника чата на стороне интеграции.
Описание объекта sender
Параметр Тип данных Описание
id string Идентификатор отправителя сообщения в API чатов
Описание объекта receiver
Параметр Тип данных Описание
id string Идентификатор получателя сообщений в API чатов
phone string Телефон получателя сообщения. Поле приходит пустой строкой, если не передавался профиль при создании чата. При создании чата через функционал "Написать первым", будет передан выбранный номер телефона
email string Email получателя сообщения. Поле приходит пустой строкой, если не передавался профиль при создании чата
Описание объекта message
Параметр Тип данных Описание
id string Идентификатор сообщения в API чатов
type string Тип сообщений, может быть одним из списка: text, file, video, picture, voice, audio, sticker
text string Текст сообщения. Для типа text обязательно, для других типов сообщений может быть пустым
tag string Тег, выбранный пользователем при отправки сообщений. В данный момент функционал не поддерживается для сторонних интеграций
media string Ссылка на медиа, если тип сообщения не text
media_group_id string Идентификатор группы медиа сообщений. Если пользователь отправляет одно сообщение с несколькими вложениями, мы разобьем сообщение на несколько, но медиафайлы будут объединены в одну группу
thumbnail string Ссылка на картинку-предпросмотр. Приходит только для типов picture и video
file_name string Название файла. В данный момент для некоторых файлов может не приходить
file_size int Размер файла в байтах. В данный момент для некоторых файлов может не приходить
markup object Объект клавиатуры, которую нужно отобразить вместе с сообщением. Структура объекта клавиатуры
template object Объект шаблона, если сообщение было отправлено с использованием шаблона. Структура объекта шаблона
Структура объекта разметки клавиатуры

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

Параметр Тип данных Описание
mode string Способ расположения клавиатуры. Возможные значения: inline — кнопки отображаются под текстом сообщения
buttons button[][] Массив массивов с объектами-кнопками. Структура объекта кнопки
Структура объекта кнопки
Параметр Тип данных Описание
text string Текст. Когда пользователь нажимает на текстовую кнопку, мессенджер должен отправить сообщение с текстом этой кнопки в чат
url string Ссылка. Когда пользователь нажимает на ссылочную кнопку, мессенджер должен осуществить переход по этой ссылке. Свойство может отсутствовать, если передана обычная кнопка
Структура объекта шаблона

Сообщение, отправленное из amoCRM может быть шаблонизированным.
Если отправленное сообщение шаблонизированное, то в хуке вы получите информацию о шаблоне.

Параметр Тип данных Описание
id int ID шаблона на стороне amoCRM
external_id string Если у шаблона на стороне amoCRM, при создании через API был указан external_id, то вы получите его в хуке
content string Оригинальный текст шаблона, может содержать маркеры
params array Массив объектов заменяемых маркеров в тексте
params[][key] string Маркер, используемый в сообщении
params[][value] string Значение, которое должно быть использовано вместо маркера

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

{
  "account_id": "52e591f7-c98f-4255-8495-827210138c81",
  "time": 1639572261,
  "message": {
    "receiver": {
      "id": "2ed64e26-70a1-4857-8382-bb066a076219",
      "phone": "79161234567",
      "email": "example.client@example.com",
      "client_id":"my_int-1376265f-86df-4c49-a0c3-a4816df41af8"
    },
    "sender": {
      "id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
    },
    "conversation": {
      "id": "8e4d4baa-9e6c-4a88-838a-5f62be227bdc",
      "client_id":"my_int-d5a421f7f218"
    },
    "source":{
      "external_id":"78001234567"
    },
    "timestamp": 1639572260,
    "msec_timestamp": 1639572260980,
    "message": {
      "id": "0371a0ff-b78a-4c7b-8538-a7d547e10692",
      "type": "picture",
      "text": "Текст сообщения Сделка #15926745",
      "markup": {
        "mode": "inline",
        "buttons": [
          [
            {
              "text":"Принять заказ"
            },
            {
              "text":"Отменить заказ"
            }
          ]
        ]
      },
      "tag": "",
      "media": "https://amojo.amocrm.ru/attachments/image.jpg",
      "thumbnail": "https://amojo.amocrm.ru/attachments/image_320x200.jpg",
      "file_name": "",
      "file_size": 0,
      "template": {
        "id": 7103,
        "external_id": "my_external_id",
        "content": "Текст сообщения {{lead.name}}",
        "params": [
          {
            "key": "{{lead.id}}",
            "value": "15926745"
          }
        ]
      }
    }
  }
}

HTTP коды ответа

Адрес, получающий данный вебхук должен ответить http-кодом 200, в таком случае мы считаем хук успешно принятым.

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

Хук о печати

Описание

Хук отправляется, когда менеджер печатает сообщение в интерфейсе amoCRM.
Хук отправляется не чаще, чем раз в 5 секунд.

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

Параметр Тип данных Описание
account_id string ID аккаунта в API чатов
time int Время генерации хука, метка unix
action[typing][conversation][id] string Идентификатор чата в API чатов
action[typing][conversation][client_id] string Идентификатор чата на стороне интеграции. Необязательное поле. Если чат создан через функцию "Написать первым", поле будет отсутствовать в хуке
action[typing][expired_at] int timestamp временной метки, когда мы считаем, что пользователь уже не печатает. Мы передаем временную метку окончания тайпинга, как текущее время начала печати + 5 секунд
action[user][id] string Идентификатор пользователя, который совершает действие в API чатов

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

{
  "account_id": "81ede28b-8952-4785-abe2-c8d93f5fcc7d",
  "time": 1637087558,
  "action": {
    "typing": {
      "user": {
        "id": "fb0fb604-9e04-4e1d-bee9-37c71924cdc2"
      },
      "conversation": {
        "id": "f1e4e02c-f502-4165-9377-8575c55c5ebd",
        "client_id": "c7"
      },
      "expired_at": 1637087563
    }
  }
}

HTTP коды ответа

Адрес, получающий данный вебхук должен ответить http-кодом 200, в таком случае мы считаем хук успешно принятым.

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

Хук сообщения 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 Хук успешно обработан