> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Руководство по использованию прокси аккаунта WhatsApp > Platform API guide - Ace Data Cloud Прокси аккаунта WhatsApp подключает **авторизованный вами аккаунт WhatsApp** и предоставляет вашему Agent существующие чаты, контакты и сообщения. Каждый экземпляр развертывания имеет независимые подключение, токен доступа и постоянное хранилище. Сам сервис не содержит ИИ и не отвечает автоматически, не делает массовых рассылок и не связывается с кем-либо по собственной инициативе. > Этот сервис использует возможность связанных устройств WhatsApp и не является официальным Business API WhatsApp; способ подключения аккаунта не поддерживается официально WhatsApp. Изменения протокола, отзыв устройства или ограничения аккаунта могут привести к прерыванию работы. Подключайте только аккаунты, которыми вы владеете, соблюдайте условия WhatsApp и не используйте сервис для спама или массовой отправки без согласия. ## Развертывание и авторизация владельцем 1. Создайте в консоли приложение «Прокси аккаунта WhatsApp», после оформления подписки нажмите развернуть. Ресурсы экземпляра автоматически настраиваются платформой. 2. После готовности экземпляра просмотрите QR-код на странице управления. На своем телефоне откройте WhatsApp **Настройки → Связанные устройства → Привязать устройство** и отсканируйте код. Также можно ввести собственный номер телефона для запроса кода сопряжения, а затем подтвердить его на телефоне. 3. Когда статус на странице управления изменится на «Подключено», скопируйте выделенный MCP-адрес и Bearer-токен доступа. 4. Выход из аккаунта попытается отозвать связанное устройство и очистить локальную сессию и историю. Если результат выхода неясен, сначала отзовите это устройство в разделе «Связанные устройства» на телефоне; уничтожение экземпляра удалит его постоянный том. QR-код и код сопряжения можно передавать только владельцу аккаунта. При обычном перезапуске будет использована сессия этого экземпляра; после отзыва устройства на телефоне экземпляр снова потребует авторизации. ## Аутентификация и возможности За исключением `/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 ```bash theme={null} BASE='https://whatsapp-bot-<实例 ID>.app.acedata.cloud' TOKEN='<管理页显示的访问令牌>' curl "$BASE/api/auth/status" -H "Authorization: Bearer $TOKEN" curl "$BASE/api/chats?limit=20" -H "Authorization: Bearer $TOKEN" curl "$BASE/api/chats/123%40s.whatsapp.net/messages?limit=20" -H "Authorization: Bearer $TOKEN" ``` Отправляйте сообщения только в **собственные существующие чаты или контакты**. `target` должен использовать JID, возвращенный `/api/chats` или `/api/contacts`; нельзя использовать произвольный номер телефона для холодной рассылки. Сначала владелец должен подтвердить получателя и содержимое. ```bash theme={null} curl -X POST "$BASE/api/messages" \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: my-confirmed-message-20261004-1" \ -H 'Content-Type: application/json' \ -d '{"target":"123@s.whatsapp.net","action":"text","text":"你好"}' ``` `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`. События сообщений, статусы отправки и статусы подключения сообщаются независимо. ## Распространенные статусы | HTTP / статус | Способ обработки | | - | - | | 401 | Проверьте Bearer-токен и заголовок запроса. | | 404 | Целевой чат, контакт или сообщение отсутствует в локальной записи этого экземпляра. | | 409 | Аккаунт не подключен, либо одинаковому ключу идемпотентности соответствует другое содержимое. | | 413 | Медиа превышает 10 MiB. | | 403 / 429 | Операция отклонена или сработало ограничение частоты; если это произошло при отправке, все равно сначала проверьте результат по этому ключу идемпотентности. | | 502 / 503 | Подключение или удаленная операция завершились ошибкой; при неопределенном результате отправки сначала проверьте статус операции и события. | Не гарантируются бесконечная история, долгосрочная доступность всех медиа или постоянное принятие WhatsApp всех групповых операций. Если необходимо проверить конкретный экземпляр, сначала просмотрите `/api/auth/status` и `/api/capabilities`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.