amoCRM Salesbot: сообщения, файлы и группы через AISAR
Как в Salesbot amoCRM отправлять через каналы AISAR сообщение клиенту сделки, файл по ссылке и сообщение в существующий чат или группу: поля блоков, ID канала и ID чата, ограничения и коды ошибок.
Что умеют блоки AISAR
Виджет AISAR добавляет в конструктор Salesbot amoCRM три блока (раздел «Виджеты»). Бот доходит до блока, AISAR отправляет сообщение через выбранный канал и возвращает бота на выход «Отправлено» или «Не удалось отправить».
| Блок | Кому | Что отправляет |
|---|---|---|
| AISAR: отправить сообщение | главному контакту сделки | текст или одобренный шаблон WhatsApp Business |
| AISAR: отправить файл | главному контакту сделки | файл по публичной ссылке и подпись к нему |
| AISAR: отправить в чат | существующему чату канала по его ID: группе или человеку | текст, файл или файл с текстом как подписью |
Блоки «отправить сообщение» и «отправить файл» работают только в ботах на сделках. Блок «отправить в чат» работает в боте на любой сущности: сделке, покупателе или контакте, потому что получатель задан ID чата.
Перед началом
- amoCRM подключена к AISAR: в my.aisar.app Настройки → CRM и интеграции → amoCRM. На вкладке «Основное» есть карточка «Salesbot: блоки AISAR» с подсказками из этой статьи.
- Salesbot включён для вашей интеграции. По умолчанию он выключен, и переключателя в кабинете нет: Salesbot включает команда AISAR по вашему запросу в поддержку. Строка «Salesbot для этой интеграции» в той же карточке показывает, включён ли он. Пока не включён, любой блок завершается кодом
salesbot_disabled. Для компаний AISAR Kids Salesbot не включается. - Виджет AISAR установлен в amoCRM: Настройки → Интеграции → AISAR → Установить. Блоки «отправить файл» и «отправить в чат» есть в виджете начиная с версии 2.1.0.
- Ответственные за сделки сопоставлены с сотрудниками AISAR на вкладке «Маппинг». Это нужно, когда у контакта ещё нет переписки на выбранном канале: тогда AISAR открывает диалог от имени ответственного за сделку (подробнее ниже).
Где взять ID канала и ID чата
- ID канала AISAR нужен во всех трёх блоках. Это число в адресе страницы канала: откройте канал в Настройки → Каналы, ID стоит в конце ссылки, например
…/settings/channels/15. Подходит только подключённый канал вашей компании. - ID чата нужен в блоке «отправить в чат». Откройте в AISAR диалог с группой или человеком: в панели диалога есть строка «ID чата» с кнопкой «Скопировать ID чата». У группы WhatsApp ID заканчивается на
@g.us, у группы Telegram это число вида -100…, у человека в Telegram это его числовой id. - ID чата можно вписать в блок как есть или хранить в поле сделки и подставлять маркером amoCRM, например
{{lead.cf.123}}. Чат должен уже быть в том канале, который указан в блоке: бот новые чаты не создаёт.
Блок «AISAR: отправить сообщение»
| Поле | Что вписать |
|---|---|
| ID канала AISAR | канал, с которого отправить |
| ID шаблона AISAR | только для WhatsApp Business: ID одобренного шаблона |
| Текст сообщения | для остальных каналов; маркеры amoCRM вроде {{contact.name}} работают |
| Переменные шаблона | JSON, например {"name": "{{contact.name}}"} или ["{{lead.price}}"] |
- WhatsApp Business: с ID шаблона уходит шаблон, без него текст уходит, только пока открыто 24-часовое окно клиента.
- Instagram (Meta) и Messenger: текст, только пока открыто 24-часовое окно клиента.
- WhatsApp, Telegram (аккаунт или бот): текст без ограничения окна.
- Телефония, SMS, Live Chat, Threads и TikTok не подходят (
channel_type_unsupported).
invalid_params.Кому уходит сообщение или файл по сделке
Получатель блоков «отправить сообщение» и «отправить файл» всегда главный контакт той сделки, на которой идёт бот. Сообщение уходит в его существующую переписку на выбранном канале. Контакту, который отказался от сообщений, бот не пишет.
Если переписки на этом канале ещё нет, AISAR открывает диалог от имени ответственного за сделку, как это делает оператор в кабинете. Для этого ответственный сопоставлен с сотрудником AISAR, состоит в компании, может создавать диалоги и имеет доступ к каналу. У контакта должен быть адрес этого мессенджера, а для WhatsApp и WhatsApp Business достаточно телефона в карточке (не короче 8 цифр). Скрытому контакту новый диалог не открывается. Новых диалогов от Salesbot в день не больше 200 на компанию. В истории диалога видно, кто его открыл и почему: «amoCRM Salesbot, сделка #N».
Блок «AISAR: отправить файл»
| Поле | Что вписать |
|---|---|
| ID канала AISAR | канал, с которого отправить |
| Ссылка на файл | публичная ссылка https или маркер поля сделки, например {{lead.cf.123}} |
| Имя файла | необязательно; расширение AISAR ставит по настоящему типу файла |
| Подпись к файлу | необязательно, до 1024 символов |
Правила для файлов
- Только публичная ссылка https: прайс на вашем сайте, прямая ссылка из облака, ссылка из поля сделки. Ссылки на внутренние и частные адреса не принимаются, переадресаций не больше трёх. Файлы из хранилища amoCRM пока не поддерживаются: им нужна авторизация аккаунта.
- Тип определяется по содержимому файла, а не по имени, и сверяется с тем, что принимает канал. HTML, SVG, скрипты, программы и архивы не отправляются ни в один канал.
- WhatsApp Business, Instagram (Meta) и Messenger: файл человеку уходит, только пока открыто его 24-часовое окно. Это проверяется до скачивания.
- Бот ждёт, пока файл скачается и уйдёт, обычно до минуты, и только потом идёт дальше.
| Канал | Размер файла |
|---|---|
| WhatsApp Business | картинки до 5 МБ (JPEG, PNG), видео и аудио до 16 МБ, документы до 64 МБ |
| Instagram и Messenger | картинки до 8 МБ (JPEG, PNG, GIF), остальные файлы до 25 МБ |
| Telegram (аккаунт или бот) | до 50 МБ |
| до 64 МБ | |
| остальные каналы | файлы не отправляются (channel_type_unsupported) |
Блок «AISAR: отправить в чат»
| Поле | Что вписать |
|---|---|
| ID канала AISAR | канал, в котором есть этот чат |
| ID чата | из панели диалога AISAR или маркер поля сделки |
| Текст сообщения | текст; если указан файл, это подпись к нему (до 1024 символов) |
| Ссылка на файл | необязательно: публичная ссылка https, правила те же, что выше |
| Имя файла | необязательно |
- Группа: 24-часового окна и отказа от рассылок у группы нет, поэтому эти проверки не применяются. Скрытой или заблокированной группе бот не пишет.
- Личный чат: те же правила окна и отказа от сообщений, что для контакта сделки.
- Нужен текст, файл или оба. Шаблоны WhatsApp Business в чаты не отправляются, а групп у WhatsApp Business нет.
- Сообщения в группу видны в AISAR (и в открытой линии Битрикс24, если она подключена), но не в карточке сделки amoCRM: чаты amoCRM привязаны к контакту, и группы туда не попадают.
От чьего имени пишет бот
no_actor, actor_no_permission или actor_no_channel_access.Блоки «отправить сообщение» и «отправить файл» тоже могут писать с любого подключённого канала компании, но только главному контакту сделки, на которой идёт бот. Выдавайте право править Salesbot в amoCRM тем, кому готовы доверить каналы и чаты компании.
Ограничения
- В один чат блоком «отправить в чат» уходит не больше 20 сообщений в минуту (
chat_rate_limited). - В одну группу не больше 500 сообщений в день (
group_daily_cap). У личных чатов дневного лимита нет. - Шагов с файлом не больше 6 в минуту на аккаунт amoCRM (
file_rate_limited). Файлы скачиваются по одному на интеграцию, есть дневная квота на объём скачанного (2 ГБ на интеграцию в сутки,file_quota_exceeded). Шаг, который ждал очереди дольше 5 минут, завершается кодомqueue_busy. - Шаблонов WhatsApp Business блоком «отправить сообщение» не больше 500 в день на компанию (
daily_cap_reached), новых диалогов от Salesbot не больше 200 в день на компанию (daily_dialog_cap_reached). - Повтор того же шага бота второго сообщения не даёт (
duplicate_step).
Если шаг ушёл в «Не удалось отправить»
Каждую отправку и каждый отказ видно в my.aisar.app на вкладке «Активность» страницы amoCRM, отказ с кодом ошибки. Код приходит и в бота: второй шаг блока читает {{json.status}} (success или fail), а при fail в ответе есть error_code. Коды по смыслу:
| Код | Что случилось и что сделать |
|---|---|
salesbot_disabled | Salesbot не включён для интеграции. Напишите в поддержку AISAR. |
file_disabled, chat_disabled | файлы или блок «в чат» временно выключены на стороне AISAR. Повторите позже. |
unsupported_entity | блок сообщения или файла стоит в боте не на сделке. Для покупателей и контактов подходит только «отправить в чат». |
integration_unavailable | интеграция amoCRM в AISAR недоступна. Проверьте её статус на странице amoCRM. |
channel_required, channel_not_found, channel_inactive | ID канала не указан, не найден в компании или канал отключён. Проверьте ID и статус канала. |
channel_type_unsupported | этот тип канала блок не поддерживает (см. правила выше). |
window_closed | 24-часовое окно клиента закрыто. В WhatsApp Business отправьте шаблон блоком «отправить сообщение». |
contact_opted_out, contact_blocked, contact_hidden | контакт отказался от сообщений, заблокирован или скрыт в AISAR. |
lead_not_found, amocrm_unavailable | AISAR не смог прочитать сделку в amoCRM: её нет или amoCRM не ответил. Во втором случае повторите позже. |
lead_has_no_contact, contact_not_linked | у сделки нет главного контакта или он ещё не связан с контактом AISAR. |
no_thread, no_contact_account, invalid_phone, phone_belongs_to_other_contact, dialog_not_created | переписки нет и открыть её не удалось: у контакта нет адреса в этом мессенджере, телефон короче 8 цифр, номер уже принадлежит другой карточке или диалог не создался. |
responsible_not_mapped, responsible_not_member, responsible_no_permission, responsible_no_channel_access | ответственный за сделку не сопоставлен с сотрудником AISAR, не состоит в компании, не может создавать диалоги или не имеет доступа к каналу. Проверьте вкладку «Маппинг» и права сотрудника. |
template_required, template_not_found, template_not_approved, template_params_missing, invalid_params | для WhatsApp Business нужен ID одобренного шаблона и все его переменные корректным JSON. |
text_required, text_too_long | нет текста или он слишком длинный. |
file_url_required, file_url_invalid | ссылки нет, она не https, ведёт на внутренний адрес или маркер amoCRM не подставился. |
file_download_failed | файл не скачался: сайт не ответил, слишком много переадресаций или не уложились по времени. |
file_too_large, file_type_unsupported | файл больше лимита канала или канал не принимает этот тип. |
file_quota_exceeded, file_rate_limited, queue_busy | сработал лимит файлов (см. «Ограничения»). Повторите позже. |
caption_too_long | подпись к файлу длиннее 1024 символов. |
chat_required, chat_not_found | ID чата не указан, в этом канале такого чата нет или маркер amoCRM не подставился. |
text_or_file_required | в блоке «отправить в чат» нет ни текста, ни файла. |
no_actor, actor_no_permission, actor_no_channel_access | пользователь, который подключил amoCRM, ушёл из компании, не может создавать диалоги или не имеет доступа к каналу. |
chat_rate_limited, group_daily_cap, daily_cap_reached, daily_dialog_cap_reached | сработал лимит (см. «Ограничения»). |
duplicate_step | этот шаг уже выполнялся, второе сообщение не отправлено. |
internal_error | сбой на стороне AISAR. Если повторяется, напишите в поддержку. |