> ## 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 наявні чати, контакти та повідомлення. Кожен розгорнутий екземпляр має незалежне підключення, токен доступу та постійне сховище. Сам сервіс не містить AI і не відповідає автоматично, не здійснює масові розсилки та не зв’язується ні з ким за власною ініціативою. > Цей сервіс використовує можливості пов’язаних пристроїв 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-.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` підтримує довге опитування тривалістю до 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.