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

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

  • Для каждого сообщения отправленного из 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
thumbnail string Ссылка на картинку-предпросмотр. Приходит только для типов picture и video
file_name string Название файла
file_size int Размер файла в байтах
markup object Объект клавиатуры, которую нужно отобразить вместе с сообщением. Структура объекта клавиатуры
template object Объект шаблона, если сообщение было отправлено с использованием шаблона. Структура объекта шаблона
reply_to object Объект цитаты-ответа. Структура объекта цитирования
forwards object Объект цитаты c перессылки. Структура объекта цитирования
Структура объекта разметки клавиатуры

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

Также на Kommo.com доступна поддержка функционала WhatsApp List Message, при отправке подобного сообщения с помощью Salesbot, информация также находится в объекте markup.
Для List Message, в этом объекте, не будет свойств mode и buttons, но будет доступно свойство list_message.

Параметр Тип данных Описание
mode string Способ расположения клавиатуры. Возможные значения: inline — кнопки отображаются под текстом сообщения
buttons button[][] Массив массивов с объектами-кнопками. Структура объекта кнопки
list_message list_message Объект сообщения типа WhatsApp List Message. Структура объекта List Message
Структура объекта кнопки
Параметр Тип данных Описание
text string Текст. Когда пользователь нажимает на текстовую кнопку, мессенджер должен отправить сообщение с текстом этой кнопки в чат
url string Ссылка. Когда пользователь нажимает на ссылочную кнопку, мессенджер должен осуществить переход по этой ссылке. Свойство может отсутствовать, если передана обычная кнопка
Структура объекта List Message
Параметр Тип данных Описание
header string Заголовок сообщения. Строка длиной до 60 символов (поддерживаются эмодзи)
body string Тело сообщения. Строка длиной да 1024 символов (поддерживаются эмодзи и разметка Markdown)
footer string Нижняя часть сообщения. Строка длиной да 60 символов (поддерживаются эмодзи, ссылки и разметка Markdown)
button string Название главной кнопки, которая будет показываться пользователю, при нажатии на эту кнопку открывается меню с переданными sections
sections array Массив объектов (от 1 до 10 элементов), описывающий интерактивные элементы (секции)
sections[0] object Объект, описывающий интерактивную секцию
sections[0][title] string Название секции. Строка длиной до 24 символов.
sections[0][rows] array Массив объектов (от 1 до 10 элементов), описывающий отдельные кнопки в секции
sections[0][rows][0] object Объект, описывающий отдельную кнопки в секции
sections[0][rows][0][callback_data] string Уникальный идентификатор, который нужно передать в WhatsApp и который необходимо прислать с выбранной пользователем кнопкой в свойстве callback_data объекта message.
sections[0][rows][0][title] string Название кнопки
sections[0][rows][0][description] string Описание кнопки

Пример хука о сообщении с List Message доступен ниже

Структура объекта шаблона

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

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

Сообщение, отправленное из amoCRM может содержать цитату с ответом.
Чтобы включить возможность отправлять сообщения, содержащие цитату с ответом, из amoCRM в интеграцию – нужно обратиться техническую поддержку
Сообщение из цитаты может принадлежать только тому же чату, что и отправляемое сообщение

Параметр Тип данных Описание
message object Объект цитируемого сообщения. Структура объекта цитируемого сообщения
Структура объекта цитаты с перессылкой

Сообщение, отправленное из amoCRM может содержать цитату c перессылкой.
Чтобы включить возможность отправлять сообщения, содержащее цитату с перессылаемыми сообщениями, из amoCRM в интеграцию – нужно обратиться техническую поддержку
Сообщения из цитаты с перессылкой могут принадлежать любому чату, который принадлежит интеграции
Сообщения из цитаты могут принадлежать любому внешнему чату, что принадлежит интеграции

Параметр Тип данных Описание
messages array Массив объектов цитируемых сообщения. Структура объекта цитируемого сообщения
conversation_ref_id string Идентификатор чата на стороне API чатов
Структура объекта вложенного сообщения
Параметр Тип данных Описание
id string Идентификатор сообщения в API чатов
type string Тип сообщений, может быть одним из списка: text, file, video, picture, voice, audio, sticker
text string Текст сообщения. Для типа text обязательно, для других типов сообщений может быть пустым
media string Ссылка на медиа, если тип сообщения не text
thumbnail string Ссылка на картинку-предпросмотр. Приходит только для типов picture и video
file_name string Название файла
file_size int Размер файла в байтах
timestamp int Время сообщения, метка unix
msec_timestamp int Время сообщения, метка unix c миллисекундами
sender object Объект с информацией об отправителе сообщения. Описание объекта
receiver object Объект с информацией о получателе сообщения (без телефона и почты). Описание объекта

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

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

Пример запроса c List Message

{
  "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": "text",
      "text": "Текст сообщения Сделка #15926745",
      "markup": {
        "list_message": {
          "header": "Какой вид услуги вы хотите получить?",
          "body": "Пожалуйста, выберите один из вариантов ответа в меню по кнопке ниже.",
          "footer": "С уважением, Тестовая Компания",
          "button": "Меню услуг",
          "sections": [
            {
              "title": "Доступные услуги",
              "rows": [
                {
                  "callback_data": "vG9ujre8N7",
                  "title": "Услуга 1",
                  "description": "Описание услуги 1"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

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

Хук о реакции

Описание

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

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

Параметр Тип данных Описание
account_id string ID аккаунта в API чатов
time int Время генерации хука, метка unix
action[reaction][message] object Объект сообщения Описание объекта
action[reaction][user] object Объект с информацией об отправителе реакции Описание объекта
action[reaction][conversation][id] string Идентификатор чата в API чатов
action[reaction][conversation][client_id] string Идентификатор чата на стороне интеграции. Необязательное поле. Если чат создан через функцию "Написать первым", поле будет отсутствовать в хуке
action[reaction][type] string Тип события: react, unreact
action[reaction][emoji] string Реакция поставленная пользователем. Необязательное поле. Если пользователь убрал реакцию, то поле будет отсутствовать в хуке
Описание объекта message реакции
Параметр Тип данных Описание
id string Идентификатор сообщения в API чатов
client_id string Идентификатор сообщения чата на стороне интеграции. Необязательное поле. Если сообщение было создана на стороне amoCRM, то поле будет отсутствовать в хуке
receiver object Объект с информацией о получателе сообщения Описание объекта
sender object Объект с информацией об отправителе сообщения Описание объекта
timestamp int Время сообщения, метка unix
msec_timestamp int Время сообщения, метка unix c миллисекундами

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

{
  "account_id": "81ede28b-8952-4785-abe2-c8d93f5fcc7d",
  "time": 1637087558,
  "action": {
    "reaction": {
      "msgid": "cd05887d-bb16-4e11-b298-40455cc77195",
      "user": {
        "id": "fb0fb604-9e04-4e1d-bee9-37c71924cdc2"
      },
      "conversation": {
        "id": "f1e4e02c-f502-4165-9377-8575c55c5ebd",
        "client_id": "c7"
      },
      "type": "react",
      "emoji": "😍"
    }
  }
}

HTTP коды ответа

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

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

Хук об ответе на комментарий

Описание

Хук отправляется, когда менеджер отвечает на комментарий комментарием в интерфейсе amoCRM.
Отличительным признаком является наличие поля post, содержащего 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 Объект с информацией об отправляемом сообщении. Описание объекта
Структура объекта message
Параметр Тип данных Описание
id string Идентификатор сообщения в API чатов
type string Тип сообщений, на данный момент может быть только text
text string Текст сообщения.
tag string Тег, выбранный пользователем при отправки сообщений. В данный момент функционал не поддерживается для сторонних интеграций
media string Ссылка на медиа, если тип сообщения не text.
thumbnail string Ссылка на картинку-предпросмотр. Приходит только для типов picture и video
file_name string Название файла
file_size int Размер файла в байтах
markup object Объект клавиатуры, которую нужно отобразить вместе с сообщением. В данный момент функционал не поддерживается для сторонних интеграций
post object Объект поста к которому был написан комменатирий на который отправлен ответ. Структура объекта post
reply_to object Объект цитаты-ответа. Структура объекта цитирования
Структура объекта post
Параметр Тип данных Описание
id string Идентификатор поста в интеграции

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

{
  "account_id": "bb037c36-8101-4bfd-8e7b-1cd3d576d124",
  "time": 1752066224,
  "message": {
    "receiver": {
      "id": "0d1eb48c-b2b0-4550-b126-05544e6483ed",
      "name": "Имя клинета",
      "client_id": "11000f5f-4554-4de4-be9d-83a3ca0e275d"
    },
    "sender": {
      "id": "38d777b1-f9ee-4d01-871e-1e4d3e4a0034",
      "name": "Имя менеджера"
    },
    "conversation": {
      "id": "7573b310-9258-477c-8986-a8c7f893f3f3",
      "client_id": "d0111a11-d001-44b3-a541-8c05293d2d8f"
    },
    "timestamp": 1752066224,
    "msec_timestamp": 1752066224654,
    "message": {
      "id": "c9b5d6f2-07e0-4c63-9018-cbc0fde8424a",
      "type": "text",
      "text": "Привет!",
      "markup": null,
      "tag": "",
      "media": "",
      "thumbnail": "",
      "file_name": "",
      "file_size": 0,
      "post": {
        "id": "1999992"
      },
      "reply_to": {
        "message": {
          "id": "90e985eb-3e5d-426e-bd62-1eb78ef6db67",
          "msgid": "d0111a04-c111-44b3-a541-8c05293d2d8f",
          "type": "text",
          "text": "Привет",
          "timestamp": 1751641366,
          "msec_timestamp": 1751641366000,
          "sender": {
            "id": "0d1eb48c-b2b0-4550-b126-05544e6483ed",
            "name": "Имя клиента",
            "client_id": "11000f5f-4554-4de4-be9d-83a3ca0e275d"
          }
        }
      }
    }
  }
}

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