Цей сервіс використовує можливості пов’язаних пристроїв 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 підтримує довге опитування тривалістю до 25 секунд; GET /api/events/stream?after=<курсор> надає SSE. Події містять монотонно зростаючий seq. next_cursor у відповіді слід зберігати в постійному стані Agent; якщо gap=true, це означає, що старі події були очищені, тож слід повторно завантажити поточний стан чатів і продовжити з oldest_cursor. Події повідомлень, статуси надсилання та статуси підключення надсилаються окремо.
Поширені статуси
Не гарантується необмежена історія, довготривала доступність усіх медіа або те, що всі операції з групами завжди будуть прийняті WhatsApp. Якщо потрібно перевірити конкретний екземпляр, спершу перегляньте
/api/auth/status і /api/capabilities.