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

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

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

Оглавление

• Проверка подлинности хуков
• Хук сообщения v2
• Хук о печати
• Хук о реакции
• Хук сообщения v1 (deprecated)

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

Каждый хук содержит заголовок 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].

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

Описание объекта conversation

Описание объекта source

Описание объекта sender

Описание объекта receiver

Описание объекта message

Структура объекта разметки клавиатуры

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

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

Структура объекта кнопки

Структура объекта List Message

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

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

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

Структура объекта цитаты с ответом

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

Структура объекта цитаты с перессылкой

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

Структура объекта вложенного сообщения

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

{
  "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, в таком случае мы считаем хук успешно принятым.

Хук о печати

Описание

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

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

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

{
  "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, в таком случае мы считаем хук успешно принятым.

Хук о реакции

Описание

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

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

Описание объекта message реакции

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

{
  "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, в таком случае мы считаем хук успешно принятым.

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

Описание

Данная версия хука не поддерживается и не получает обновлений
Хук отправляется при отправке сообщения в канал, если при подключении канала аккаунта выставлена версия хука v1.

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

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

{
  "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 коды ответа