API Чатов

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

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

При базовом использовании API чатов, при отправке сообщения в новый чат – создается чат, контакт и неразобранная сделка.
Чат связан с контактом, у одного контакта может быть несколько чатов из разных каналов, а также из разных источников одного канала.
В контакте также хранится информация – имя, телефон, email, а также аватар пользователя (если передан).
В карточке контакта чат не отображается, если у него есть привязанные сделки или покупатели.
Также при входящем сообщении в систему, менеджеры получают уведомления в центр уведомлений, который располагается в нижнем левом углу экрана в web-версии.
Уведомления приходят и на телефон, если установлено мобильное приложение, поэтому просим не злоупотреблять уведомлениями, чтобы пользователь не был вынужден отключить их в своем профиле.

Диаграмма ниже демонстрирует процесс отправки и получения сообщений через аккаунт amoCRM

Диаграмма взаимодействия сервисов

Ниже рассмотрим основные возможности, а также дополнительные, которые могут сделать вашу интеграцию более полезной для пользователя.

Основные возможности API чатов

Дополнительные возможности, которые могут быть реализованы интеграцией

В данной статье рассмотрим описанные выше возможности с точки зрения пользователя, с технической точки зрения – в следующих статьях.

Получение сообщений из внешних каналов в amoCRM

Одна из основных функций API Чатов – возможность получения сообщений из внешних каналов в amoCRM.
Интеграция выступает в роли транспорта для сообщений из сторонней чат-системы в amoCRM.
При входящем сообщении в новый чат – в amoCRM будет создано неразобранное в воронке.

Входящий чат в воронке сделок

Отправка сообщений из интерфейса amoCRM

Следующей основной возможностью API чатов является возможность отправлять сообщения из amoCRM во внешний канал.
Сообщения могут быть отправлены из карточки или ботом. Сообщение может содержать в себе следующую информацию:

  • Текст сообщения
  • Добавленные к сообщению медиа-файлы
  • Кнопки
  • Информацию о выбранном шаблоне и замененных маркерах, если отправляется шаблон

Отправка сообщения из amoCRM

Обновление статуса отправленного сообщения

API чатов также поддерживает статусы отправленных сообщений.
Интеграция может реализовать поддержку актуального статуса и обновлять его через API у каждого отправленного сообщения.

Статус Когда должен быть использован статус Enum значение статуса
Отправлено Сообщение было отправлено из amoCRM
Доставлено Сообщение было доставлено до адресата 1
Прочитано Сообщение было прочитано адресатом 2
Ошибка Сообщение не было доставлено -1

Отображение статуса сообщения

Вывод ошибки отправленного сообщения

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

Код ошибки Когда должна быть передан код
901 Пользователь удалил переписку
902 Интеграция отключена на стороне канала
903 Внутрення ошибка сервера
904 Невозможно создать переписку (Например, пользователь не зарегистрирован в WhatsApp)
905 Любая другая, вместе с данным кодом ошибки необходимо передать текст ошибки

Пример ошибки

Импорт истории переписки и бот канала

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

Создание чата и его привязка к существующим контактам

Для более сложных кейсов, когда история переписки нужна "здесь и сейчас", мы предоставляем специальные методы API,
которые позволяют связать созданный чат и любой контакт в аккаунте.

Получение истории переписки

API чатов предоставляет метод для получения истории переписки в рамках указанного чата. Интеграция может получить доступ только к тем чатам,
которые были созданы ей.

Функционал "Написать первым"

Некоторые мессенджеры поддерживают возможность инициировать общение с клиентом первым. Для этого мы добавили функционал "Написать первым".
Идентификатором для функционала "Написать первым" является номер телефона.
Клиент может инициировать общение в карточке сделки, нажав на номер телефона и выбрав источник. Также такая возможность есть в Salesbot.

Для использования этой функции, достаточно создать карточку сделки и добавить в нее контакт с номером телефона.
Поддерживающие функцию каналы отобразится в выпадающем списке Click-To-Call.

Отображение контрола Написать первым

Пользователь выбирает ваш виджет и отправляет сообщение через стандартный интерфейс написания сообщения.

Написание сообщения

После написания сообщения, мы отправим Webhook, в котором передаются идентификаторы чата, получателя и сообщения со стороны amoCRM.

Ваш сервер интеграции должен обработать запрос, и попытаться отправить сообщение получателю. По факту отправки или
невозможности отправить сообщение, интеграция должна отправить запрос в amoCRM на изменение статуса сообщения.

Возможность подключения нескольких источников для одного канала

В amoCRM предусмотрена возможность множественных источников. Это может быть полезно для тиражируемых интеграций,
которым необходимо через 1 канал интеграции обеспечить поддержку нескольких источников в мессенджере, например несколько номеров WhatsApp.
Для поддержки множественных источников, вашей интеграции необходимо через API источников завести соответствующие сущности и с каждым сообщением передавать данные об источнике.
Одна интеграция может завести до 50 источников в одном аккаунте amoCRM.

На скришноте ниже представлен пример, в котором у нас заведено 2 источника: Support и Sales.
В карточке сделки есть 2 контакта с разными номера, на каждый из которых мы отправили сообщение.
Контакту Никита мы отправили сообщение из источника Sales на 2 доступных номера в карточке.

Фид в карточке делится в зависимости от источника и пользователя.
Если у одного пользователя есть несколько номеров телефона, в таком случае номер телефона будет добавлен справа от имени контакта в фиде.

Множественные источники

Отображение статуса печати

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

Отображение тайпинга

Поддержка временного окна

В связи с тем, что многие интеграции ограничивают возможность писать сообщения по истечению N-ого времени,
мы добавили поддержку временных окон.
Интеграция сама определяет размер временного окна. В карточке, после каждого входящего сообщения, таймер будет обнуляться и отчитывать время до окончания временного окна.

Отображение таймера

На .com платформе, также интеграция может сообщить, что ей необходимо блокировать контрол отправки сообщения по истечению временного окна.
После блокировки контрола написания сообщения, у пользователя останется возможность выбрать шаблон для отправки.

Поддержка шаблонов сообщений

Начиная с осени 2021, при отправке шаблона из карточки или ботом, интеграция получит в вебхуке не только итоговый текст,
но и значения маркеров, которые были заменены и идентификатор шаблона. Это особенно актуально в связке с API шаблонов.

Поддержка шаблонов WhatsApp Business API

Начиная с осени 2023, можно создавать шаблоны типа WhatsApp через API и отправлять их на проверку, если установлена интеграция, работающая с белым WhatsApp.
Это откроет возможность настроить шаблон WhatsApp в Salesbot для общения с клиентом по прошествии 24 часового временного окна.
Для того, чтобы пометить источник работающим с белым WhatsApp – необходимо указать в источнике параметр waba.
Дальше вы сможете создать шаблон с типом WhatsApp и управлять его статусом через API, получать вебхук add_chat_template_review, когда пользователь запрашивает проверку шаблона.

Отправка реакции на сообщение

В релизе Весна 2023 мы добавили возможность отправлять реакцию на сообщение.
Интеграция может сообщить какой набор реакций она поддерживает, тогда менеджер сможет реагировать на сообщения из карточки.

Отображение реакции

Отправка сообщений List Message WhatsApp

Salesbot на платформе Kommo.com может отправлять клиенту сообщение типа List Message, которое позволяет отображать меню с выбором.
Пользователю достаточно лишь выбрать определенный вариант и сразу отправить сообщение со сделанным выбором.
Отправка таких сообщений из бота возможно только для интеграций с белым WhatsApp, и для которых указана поддержка данного типа сообщений.
Для того, чтобы использовать функционал, интеграция должна указать в источнике свойство services[0][params][is_supports_list_message].
Подробнее в документации источников.


В следующих статьях мы подробно рассмотрим техническую часть, описанного выше функционала, и особенности API Чатов, а также приведём примеры реализации.