Этот сервис использует возможность связанных устройств WhatsApp и не является официальным Business API WhatsApp; способ подключения аккаунта не поддерживается официально WhatsApp. Изменения протокола, отзыв устройства или ограничения аккаунта могут привести к прерыванию работы. Подключайте только аккаунты, которыми вы владеете, соблюдайте условия WhatsApp и не используйте сервис для спама или массовой отправки без согласия.
Развертывание и авторизация владельцем
- Создайте в консоли приложение «Прокси аккаунта WhatsApp», после оформления подписки нажмите развернуть. Ресурсы экземпляра автоматически настраиваются платформой.
- После готовности экземпляра просмотрите QR-код на странице управления. На своем телефоне откройте WhatsApp Настройки → Связанные устройства → Привязать устройство и отсканируйте код. Также можно ввести собственный номер телефона для запроса кода сопряжения, а затем подтвердить его на телефоне.
- Когда статус на странице управления изменится на «Подключено», скопируйте выделенный MCP-адрес и Bearer-токен доступа.
- Выход из аккаунта попытается отозвать связанное устройство и очистить локальную сессию и историю. Если результат выхода неясен, сначала отзовите это устройство в разделе «Связанные устройства» на телефоне; уничтожение экземпляра удалит его постоянный том.
Аутентификация и возможности
За исключением/health и /readyz, интерфейсы REST, MCP, сканирования кода и сопряжения требуют Authorization: Bearer <токен доступа>. Размещайте токен только в заголовке запроса, не в URL или журналах. GET /api/capabilities показывает операции, фактически поддерживаемые текущим экземпляром, и лимиты хранения.
В настоящее время поддерживаются: статус аккаунта и подключения, чаты и контакты, синхронизированные со связанным устройством, события сообщений в реальном времени, чтение локально сохраненных сообщений, отправка и получение текста и медиа размером не более 10 MiB, ответы с цитированием, реакции эмодзи, отметка о прочтении, а также разрешенные правами аккаунта и текущими правилами WhatsApp редактирование/отзыв собственных сообщений, информация о группах и операции с отдельными участниками. Изменение групп по-прежнему проверяется WhatsApp на права участников и администраторов.
Диапазон истории: можно читать только сообщения, фактически синхронизированные с телефона на связанное устройство, а также сообщения, полученные во время работы прокси. Получение всех старых сообщений не гарантируется; локально хранится максимум последние 5 000 сообщений и 2 000 событий. При наличии метаданных медиа исходное медиа также может быть уже недоступно для загрузки.
MCP
Страница управления развертыванием предоставляетhttps://whatsapp-bot-<实例 ID>.app.acedata.cloud/mcp. Настройте этот адрес в MCP-клиенте, поддерживающем Streamable HTTP и пользовательские заголовки запросов, и добавьте тот же Bearer-токен. Инструменты MCP включают whatsapp_capabilities, whatsapp_whoami, whatsapp_chats, whatsapp_contacts, whatsapp_messages, whatsapp_events, whatsapp_send, whatsapp_send_status, whatsapp_media, whatsapp_mark_read, whatsapp_group и whatsapp_group_update.
Agent может читать сообщения в соответствии со своей задачей; перед отправкой сообщений третьим лицам, изменением сообщений или изменением групп он должен запросить у пользователя подтверждение конкретного получателя и содержимого. Настройка MCP сама по себе не запускает никаких отправок.
Примеры REST
target должен использовать JID, возвращенный /api/chats или /api/contacts; нельзя использовать произвольный номер телефона для холодной рассылки. Сначала владелец должен подтвердить получателя и содержимое.
action может быть text, media, edit, revoke или reaction. Для отправки медиа передавайте media_base64 и mime_type; для ответа — reply_to; для редактирования и отзыва — локально доступный собственный message_id; для реакции — message_id и emoji. Медиа можно скачать через GET /api/chats/{target}/messages/{id}/media, а отметить чат прочитанным — через POST /api/chats/{target}/read.
Отправка должна содержать Idempotency-Key длиной 8–128 символов. Возвращаемый message_id фиксирован, а статус бывает pending, accepted, unknown, delivered или read. accepted означает только, что локальное подключение приняло отправку, и не означает, что получатель ее получил. При возникновении unknown проверьте GET /api/sends/{Idempotency-Key} и события сообщений; не отправляйте то же сообщение с новым ключом, чтобы избежать дублирования. Прокси не повторяет автоматически операции с неопределенным результатом.
Записи отправки не удаляются автоматически; после достижения 100 000 записей экземпляр отклоняет новые отправки (HTTP 507), чтобы избежать повторной отправки после очистки старых ключей идемпотентности.
События в реальном времени
GET /api/events?after=<предыдущий next_cursor>&wait_ms=25000 поддерживает long polling продолжительностью до 25 секунд; GET /api/events/stream?after=<курсор> предоставляет SSE. События содержат монотонно возрастающий seq. next_cursor из ответа следует сохранять в постоянном состоянии Agent; если gap=true, это означает, что старые события были очищены, следует повторно получить текущее состояние чатов и продолжить с oldest_cursor. События сообщений, статусы отправки и статусы подключения сообщаются независимо.
Распространенные статусы
Не гарантируются бесконечная история, долгосрочная доступность всех медиа или постоянное принятие WhatsApp всех групповых операций. Если необходимо проверить конкретный экземпляр, сначала просмотрите
/api/auth/status и /api/capabilities.