Инструменты агента

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

Как добавить инструмент

Откройте настройки агента и добавьте инструмент приложения. Выберите одно из действий amoCRM и сохраните агента. Отдельной формы настройки у этих инструментов нет: параметры агент передаёт во время вызова из контекста диалога и своей инструкции.

До первого вызова убедитесь, что аккаунт amoCRM подключён в том же проекте.

Создать контакт

Создание контакта требует contact_name; phone и email необязательны. Всегда создаёт новый контакт в amoCRM, не создаёт сделку и не ищет дубликаты по имени, телефону или email. Перед созданием проверьте «Получить контакт» для текущего лида.

Результат: contact_id и account_url — ссылка на контакт.

Изменить контакт

Обязателен contact_id и хотя бы одно изменение: contact_name, phone или email. Остальные поля не затрагиваются; пустое значение не очищает данные. Переданный телефон или email заменяет значения соответствующего поля контакта. Сделки не изменяются.

Результат: contact_id и account_url.

Создать сделку

Обязательны contact_id существующего контакта и deal_name. Необязательны price, pipeline_id, status_id, responsible_user_id и tags через запятую. Создаётся только новая сделка в amoCRM; данные контакта не меняются. Перед созданием проверьте список сделок контакта, чтобы не завести повторную заявку.

Результат: deal_id и account_url — ссылка на новую сделку.

При выполнении этих трёх действий в контексте лида Senler выбранный contact_id сохраняется в его переменную связи с amoCRM, заменяя прежнюю связь. Новая сделка также добавляется в переменную текущего диалога. В MCP-действиях без контекста лида/диалога эти связи не создаются. Для записи чужого контакта используйте действие без контекста текущего лида.

Получить контакт

Получение контакта принимает contact_id. Для текущего лида ID можно не указывать: приложение прочитает его переменную связи. При found: true возвращаются contact_id, contact_name, contact_phone и contact_email. Для телефона и email выбирается непустое рабочее значение (WORK); если его нет — первое непустое значение соответствующего поля. Если значений нет, возвращается пустая строка.

Если контакт не существует или у лида ещё нет связи с amoCRM, результат — found: false, без полей контакта. Это не означает, что можно создать контакт без согласия клиента.

Получить сделку

Получение сделки требует точный deal_id. При found: true возвращаются deal_id, deal_name, deal_price, deal_pipeline_id и deal_status_id. Если сделка не существует, результат — found: false, без полей сделки. Контакт при этом не запрашивается.

Оба инструмента не ищут по имени. Если ID сделки неизвестен, сначала получите список сделок контакта и выберите нужную по контексту или уточните у клиента. Перед использованием полей проверьте found. Ошибки авторизации, прав, лимитов и связи не превращаются в «не найдено».

Получить сделки контакта

Инструмент списка возвращает сделки контакта с ID, названием, бюджетом, воронкой, этапом, ответственным, датами и ссылкой на карточку. Для текущего лида contact_id можно не передавать.

Параметр status принимает open (по умолчанию), closed или all, а limit — число от 1 до 50. Если подходящих сделок несколько, агент должен выбрать нужную по данным диалога или уточнить у пользователя, а не угадывать.

Перед выбором проверяется весь список связанных сделок, а не только первые 250. Если загрузить его полностью не удалось или у контакта больше 1000 сделок, инструмент вернёт ошибку, а не ложное «сделок нет». truncated: true означает, что подходящих сделок больше указанного limit.

Изменить сделку

Инструмент изменения сделки меняет название, бюджет, воронку, этап, ответственного, причину отказа и добавляет либо удаляет теги. deal_id обязателен. Если он неизвестен, сначала получите сделки контакта.

Перед сменой воронки, этапа или ответственного вызовите «Получить настройки amoCRM», если точные ID неизвестны. Этот инструмент возвращает воронки вместе с их этапами и доступных пользователей; он ничего не изменяет.

Добавить примечание

Инструмент примечания принимает entity_type, entity_id и text. Для сделки используйте entity_type: leads, для контакта — entity_type: contacts.

Результат содержит ID созданного примечания и исходную сущность.

Создать задачу

Инструмент задачи принимает тип и ID сущности, текст задачи и необязательный срок complete_after_minutes. Если срок не передан, используется 60 минут от момента вызова.

При необходимости задайте responsible_user_id и task_type_id: 1 означает звонок, 2 — встречу; пользовательские типы используют собственный ID amoCRM.

Получить настройки amoCRM

Без параметров возвращает воронки и этапы в pipelines, пользователей в users и признак users_available. Используйте только когда нужны точные ID воронки, этапа или ответственного. Если users_available = false, список сотрудников недоступен подключённому пользователю; воронки при этом можно получить.

ID и безопасные повторения

Все ID amoCRM — положительные числа. Не подставляйте ID из другого аккаунта или предположение по названию.

Техническая повторная доставка одного события Senler не создаёт дубль. Новый вызов создания без deal_id считается новым действием и создаёт новую сделку. Для изменения существующей записи всегда передавайте её точный ID.

Как инструмент связывает сделку с диалогом

Когда инструмент создаёт, изменяет или читает конкретную сделку, приложение запоминает её deal_id в текущем диалоге. Поэтому автоматизация или агентское событие «Изменение этапа сделки» впоследствии срабатывает именно в этом диалоге, а не в другом недавнем разговоре того же лида. Повторный webhook не запускает событие второй раз.