WhatsApp — документация AIKraft Agents

Интеграция WhatsApp использует поток QR-паривания (тот же, что и WhatsApp Web) и работает в подпроцессе-воркере, чтобы изолировать глобальное состояние Baileys от основного процесса Electron.

Неофициальная интеграция. Адаптер WhatsApp использует Baileys — клиент, созданный путем обратного инжиниринга и поддерживаемый сообществом для WhatsApp Web. Это не официальная интеграция WhatsApp Business API. Используйте её для личной автоматизации и учитывайте, что Meta может рейтрекить или блокировать сессию по своему усмотрению — храните резервные копии важных чатов в другом месте.

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

Настройки → Мессендинг: в AIKraft Agents нажмите кнопку Подключить на плитке WhatsApp.
Отсканируйте QR-код телефоном: в диалоговом окне появится QR-код. На телефоне откройте WhatsApp → Настройки → Связанные устройства → Связать устройство и отсканируйте код.
Ожидание подключения: диалог обновится до `Подключено как <ваш-имя>`. Сессия Baileys сохраняется в:
terminalbash
```
~/.craft-agent/workspaces/{workspaceId}/messaging/whatsapp-session/
```
Сохраните эту папку — удаление её потребует повторного паривания.

Второй телефон не нужен. Режим самосообщений (включён по умолчанию) позволяет писать самому себе (свой номер в WhatsApp) и управлять ответом агентом. См. Режим самосообщений ниже.

Первая беседа

Самосообщение (рекомендуется)

Напишите себе в WhatsApp: откройте чат с собственным номером (запись "Написать себе" на экране нового чата).
Отправьте /new: воркер видит сообщение от вашего JID, создаёт сессию и связывает чат. Ответы агента появляются с префиксом 🤖, чтобы отличать их от ваших сообщений.
Общайтесь обычно: всё, что вы печатаете, пересылается агенту. Префикс 🤖 на ответах также используется воркером для фильтрации собственных эхо-сообщений — не удаляйте его при копировании или репосте.

Второй телефон / контакт

Попросите контакт писать вам (или используйте второй телефон). Они отправляют `/new` на привязанный номер; воркер получает сообщение и связывает чат с новой сессией.
Агент отвечает в чат: ответы идут обратно тому же контакту. Каждое входящее сообщение от этого контакта управляет привязанной сессией, пока они (или вы) не отправите `/unbind`.

Режим самосообщений

Когда включён (по умолчанию), сообщения, которые вы отправляете с другого устройства того же аккаунта WhatsApp на свой собственный JID, обрабатываются как входящие и маршрутизируются в привязанную сессию.

Поведение	Почему это важно
Префикс ответа	Все исходящие сообщения воркера к себе помечаются префиксом 🤖 (U+1F916). Это позволяет воркеру фильтровать собственные эхо-сообщения, чтобы не запустить бесконечный цикл.
Отслеживание ID отправленных	Воркер также отслеживает ID сообщений, которые он отправил, чтобы ответы на них обрабатывались как контекст, а не как новые запросы.
Поддержка LID	Контакты с длинным ID (новый формат `lid`, который WhatsApp постепенно внедряет) распознаются как "сам" при привязке к вашему аккаунту.

Отключите режим самосообщений в Настройки → Мессендинг → WhatsApp, если хотите управлять сессиями только через отдельный контакт.

Вложения

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

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

Для привязок WhatsApp `approvalChannel` всегда равен `app` — шлюз не поддерживает ответы на одобрение прямо в WhatsApp. Когда привязанная сессия находится в режиме Спрашивай перед правкой и агент запрашивает одобрение для bash-команды, запрос появляется в десктопном приложении, а не в чате. Всё остальное (запросы, ответы) проходит через WhatsApp как обычно.

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

Когда агент находится в режиме Изучение и отправляет план через `SubmitPlan`, пользователи WhatsApp видят текстовую ссылку:

📝 План готов к проверке. Откройте десктопное приложение, чтобы просмотреть и одобрить его.

Вы не можете принять или отклонить план из WhatsApp — цикл одобрения происходит только в десктопном приложении.

В отличие от привязок Telegram, которые получают две кнопки (`✅ Принять план` и `♻️ Принять и уплотнить`), прикреплённые к сообщению с планом, а также содержимое плана встроенно (или как прикреплённый `plan.md`, если он превышает лимит длины сообщения Telegram).

Почему так? Три причины:

WhatsApp не поддерживает встроенные кнопки в текущем наборе возможностей адаптера. Поток Telegram зависит от кнопок для передачи подписанного токена одобрения плана; WhatsApp не может отобразить их.

Нет пути для текстового ответа — токены одобрения планов одноразовые и предназначены для использования при нажатии кнопки. Нет команды вроде `/accept ` для чатов без кнопок.

`approvalChannel` жёстко задан как `app` для WhatsApp — это дополнительная мера безопасности: запросы на одобрение bash-команд и отправка планов оба маршрутизируются в десктопное приложение.

Это сознательное отложение, а не жёсткое ограничение. WhatsApp поддерживает кнопки быстрого ответа в более новых протоколах (Baileys `buttonsMessage` / `interactiveMessage`), и fallback на слеш-команды сработал бы даже без поддержки протокола. Отслеживайте это ограничение в GitHub Issues, если вам это нужно — пока не реализовано.

Архитектура (для любопытных)

Пропустите этот раздел, если вы не отлаживаете или не разворачиваете на удалённом сервере. Повседневное использование не требует понимания воркера.

Адаптер WhatsApp необычен тем, что Baileys содержит много глобального состояния (хранилища учётных данных, очереди сообщений, таймеры переподключения) и ожидает, что он единственный экземпляр в своём процессе. Запуск его внутри основного процесса Electron сделал бы краши инфицирующими. Вместо этого:

terminalbash

┌──────────────────────────┐   NDJSON over stdio   ┌───────────────────────────┐
│ Electron main process    │ ────────────────────► │ messaging-whatsapp-worker │
│  (messaging-gateway      │ ◄──────────────────── │  (Baileys + grammY-like   │
│   adapter client)        │   typed events        │   event loop, single CJS) │
└──────────────────────────┘                       └───────────────────────────┘
        ↑                                                      ↑
        │                                                      │
        └─ sends IncomingMessage                                └─ persists creds to
           to Router                                              whatsapp-session/

Воркер — это один объединённый CJS-файл (`packages/messaging-whatsapp-worker/dist`), запущенный под встроенным Node Electron через `ELECTRON_RUN_AS_NODE`.
Связь — новостная JSON-разделённая по строкам через stdio: запросы от основного процесса, типизированные события (QR, подключено, сообщение, отключение) от воркера.
При выходе воркера основной процесс сбрасывает отложенные отправки с таймаутом, чтобы ничего не потерялось.
В CI сборка и проверка бандла воркера входят в артефакты релиза, чтобы не допустить выпуска сломанных бандлов.

Устранение неполадок

QR-код отображается, но не подключается

Убедитесь, что телефон, сканирующий код, онлайн.
Проверьте, что WhatsApp на телефоне обновлён — Meta иногда меняет протокол связывания, и Baileys требует релиза для синхронизации.
Попробуйте Отключить из меню трёх точек и повторно привяжите с нуля.

«Отключить» vs «Забыть устройство»

Метка меню — Отключить (переименовано из прежнего «Забыть устройство»). Она очищает сохранённую сессию Baileys и требует повторного паривания при следующем подключении.

Ответы агента появляются на телефоне, но не на десктопном WhatsApp

WhatsApp синхронизирует связанные устройства с задержкой. Откройте WhatsApp на привязанном устройстве, подождите 10–15 секунд или отправьте тестовое сообщение с телефона, чтобы принудительно запустить синхронизацию.

Незавершённые сообщения теряются при закрытии приложения

Воркер сбрасывает отложенные исходящие сообщения при выходе с таймаутом. Если приложение принудительно завершено, очередь теряется, но все входящие сообщения сохраняются на стороне WhatsApp — вы не пропустите сообщения, отправленные на агента; возможно, вы упустите ответы агента, которые были в процессе отправки.

Самосообщение не распознаётся

Подтвердите, что режим самосообщений включён в Настройки → Мессендинг → WhatsApp.
Если ваш аккаунт недавно мигрировал на LID, привязка может всё ещё ссылаться на старый JID. Отвяжите и повторно привяжите из самосообщения.

Связанное устройство удалено WhatsApp

Meta периодически истекает срок действия неактивных связанных устройств. Повторно привяжите из приложения — ваши привязки и данные сессии сохранятся.

Не могу одобрить план из WhatsApp

По умолчанию, пока что. Когда агент отправляет план в режиме Изучение, привязки WhatsApp получают текстовую ссылку на «открытие десктопного приложения» вместо интерактивной кнопки. См. Отправка плана для объяснений и обходных путей.