Обзор мессенджеров — документация AIKraft Agents

Мессенджеры позволяют связать внешний чат (Telegram DM, WhatsApp-контакт или чат Lark/Feishu) с сессией AIKraft Agents. Сообщения, отправленные в этом чате, управляют агентом; вывод агента отображается обратно в том же чате.

Поддерживаемые платформы

Telegram — токен бота (через @BotFather), работает в режимах in-process long-poll или webhook. Поддерживает инлайн-кнопки, фото, документы, голос и видео вложения до 20 МБ.
WhatsApp — QR-код или код подключения через воркер-подпроцесс на базе Baileys. Поддерживает текст, медиа-вложения и режим «самочата», чтобы не нужен был второй телефон для тестирования.
Lark / Feishu — подключение App ID + App Secret через Lark Open Platform (международная) или Feishu Open Platform (Китай). Используйте кнопку «Создать» с пометкой «Создано для агентов» на странице создания приложения, чтобы пропустить настройку scope и подписки на события. Длинное соединение, богатый текст через Lark post, интерактивные карточки, вложения изображений и файлов.

Как это работает

Включите платформу в настройках — откройте Настройки → Мессенджеры и настройте Telegram (вставьте токен бота) или WhatsApp (отсканируйте QR-код). Каждый workspace имеет собственную конфигурацию мессенджеров.
Свяжите чат с сессией — из внешнего чата отправьте /new, чтобы создать новую сессию, /bind, чтобы выбрать из недавних сессий, или /pair <code>, чтобы активировать код подключения, сгенерированный в приложении.
Чат управляет агентом — после связывания всё, что вы вводите, пересылается агенту как запрос. Ответ агента отображается в чате с использованием выбранного режима ответа.

Команды

Доступны в любом чате — шлюз обрабатывает любое сообщение, начинающееся с /, как команду.

Команда	Что делает
`/new [name]`	Создаёт новую сессию и связывает с ней этот чат. Необязательное имя.
`/bind`	Показывает до 10 недавних сессий. В Telegram нажмите на инлайн-кнопку. В WhatsApp ответьте `/bind <number>`.
`/bind <id>`	Связывает напрямую с сессией по её ID или индексу в списке.
`/pair <code>`	Активирует 6-значный код подключения, сгенерированный из меню сессии в приложении.
`/unbind`	Отсоединяет этот чат от текущей сессии.
`/status`	Показывает связанную сессию, канал одобрения и режим ответа.
`/stop`	Прерывает текущий запуск агента.
`/help`	Показывает доступные команды.

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

Режимы ответа

Как вывод агента отображается в чате.

Режим	Что вы видите	Когда использовать
`progress` (по умолчанию)	Одно меняющееся сообщение за запуск. Появляется пузырь «💭 думаю…» при первой активности, редактируется на месте по мере выполнения инструментов и заменяется окончательным ответом по завершении. Если запуск завершается на вызове инструмента без выдачи не промежуточного финала, используется последний текст ассистента в качестве ответа вместо оставшегося пузыря мысли.	Поддерживает чат в чистоте — большинство пользователей.
`streaming`	Живые правки во время финального хода, плюс каждое промежуточное `text_complete` как отдельное сообщение. Несколько сообщений за запуск.	Соответствие внутриприложенному опыту стриминга.
`final_only`	Молчалив до завершения запуска, затем одно сообщение с финальным текстом. Если не пришло не промежуточного финала, публикуется последний текст ассистента; совершенно пустые запуски остаются молчаливыми.	Тихие чаты, пакетные рабочие процессы.

Режим ответа настраивается для каждой связи — вы можете иметь один чат на progress и другой на final_only в одном workspace.

Интервал редактирования в Telegram. Чтобы не превышать лимиты Telegram, рендерер группирует правки с интервалом ~3,5 сек (≈ 20 правок/мин). WhatsApp не поддерживает редактирование сообщений, поэтому в режиме progress на WhatsApp публикуется только финальный пузырь «думаю…» и заменяется ответом.

Коды подключения

Если у вас уже есть открытая сессия в приложении и вы хотите продолжить её с телефона, используйте код подключения вместо ввода ID сессии:

Сгенерируйте код из меню сессии — в приложении откройте нужную сессию, нажмите на три точки и выберите Связать с мессенджером…. Отображается 6-значный код.
Активируйте его из чата — в внешнем чате отправьте /pair 123456 (используйте ваш реальный код). Шлюз проверяет код, связывает чат и подтверждает.

Безопасность:

Коды истекают после короткого TTL.
Команда /pair ограничена по количеству попыток на отправителя — неверные попытки также расходуют бюджет.
Коды работают только внутри workspace, который их выдал.

Вложения

Поддерживаются на Telegram: фото, документы, голосовые сообщения, видео и аудио. Файлы загружаются во временное хранилище и пересылаются в сессию как объекты FileAttachment — так же, как загрузки из приложения. Жёсткий лимит: 20 МБ на вложение.

Пересылка вложений из WhatsApp следует той же схеме; платформенно-специфичные лимиты и обработка MIME-типов описаны на странице WhatsApp.

Канал одобрения

Когда связанная сессия находится в режиме прав Спрашивай, агент запрашивает одобрение перед выполнением команды bash. approvalChannel для каждой связи определяет, где появляется запрос:

Значение	Поведение
`chat` (по умолчанию для Telegram)	Запрос одобрения публикуется в чат — вы отвечаете Одобрить/Отклонить прямо там.
`app` (по умолчанию для WhatsApp, обязательно)	Запрос отображается только в десктопном приложении. Связи WhatsApp не поддерживают инлайн-одобрение.

Собственный режим прав сессии всё ещё является обязательным — approvalChannel только управляет где отображается запрос, а не выполняется ли он.

Отправка плана

Когда агент отправляет план в режиме Изучение, связи Telegram получают инлайн-кнопки ✅ Принять план / ♻️ Принять и уплотнить (плюс содержимое плана инлайн или как вложение plan.md). Связи WhatsApp получают текстовое указание открыть десктопное приложение — принять план из WhatsApp пока нельзя. См. WhatsApp → Отправка плана для объяснений.

Безопасность и область действия

Для каждого workspace. Каждый workspace имеет собственную конфигурацию мессенджеров, связи и коды подключения. Связь в workspace A никогда не принимает коды, выданные workspace B.
Отзыв план-токенов. План-токены (используемые для потоков bash-одобрения) привязаны к связи — пересвязывание чата аннулирует ожидающие токены для старой связи.
Ограничение скорости. /pair ограничен по скорости на отправителя. Входящие сообщения маршрутизируются через очередь на уровне связи, чтобы спам не задерживал другие связи.
Нет чатов групп/каналов. Сообщения из групп и каналов Telegram отклоняются на уровне адаптера — только приватные DM могут управлять сессией.

Расположение конфигурации

Конфигурация мессенджеров сохраняется для каждого workspace:

terminalbash

~/.craft-agent/workspaces/{workspaceId}/messaging/
  ├── config.json          # флаги включения платформ
  ├── bindings.json        # сопоставления чат → сессия
  └── whatsapp-session/    # учётные данные Baileys (только WhatsApp)

Изменения в bindings.json вступают в силу при следующем входящем сообщении. Удаление папки whatsapp-session/ вынуждает повторное подключение.

Удалённый сервер

Шлюз также работает внутри автономного headless-сервера Bun (packages/server). Telegram использует режим webhook на сервере (вы настраиваете URL webhook), тогда как WhatsApp всё ещё запускает воркер-подпроцесс Baileys. Подробности развёртывания см. в разделе Сервер.