# whapi — WhatsApp API

> HTTP API к WhatsApp поверх Baileys (протокол WhatsApp Web multi-device).
> Пути совместимы с whapi.cloud. Описание собрано из маршрутов работающей сборки
> версии 1.0.2, поэтому соответствует тому, что развёрнуто прямо сейчас.

- Базовый URL: https://whapi.xpertnet.ai
- Аутентификация: заголовок `X-API-Key: <ключ>`, либо `Authorization: Bearer <ключ>`, либо `?api_key=<ключ>`
- Без ключа доступны только: `/health`, `/docs`, `/openapi.json`, `/llms.txt`, `/llms-full.txt`
- Ответы: `{ "success": true, ... }` или `{ "success": false, "error": "...", "error_code": "..." }`
- Лимиты HTTP: 200 запросов в минуту на IP, 30 в минуту на отправку сообщений
- Канал выбирается `?channelId=<id>` или заголовком `X-Channel-Id`; в путях `/channels/:id/*` — из пути

## Быстрый старт

```bash
KEY=<ваш ключ>
# 1. создать канал
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Продажи"}' https://whapi.xpertnet.ai/channels
# 2. подключить и забрать QR (сканировать в WhatsApp → Связанные устройства)
curl -X POST -H "X-API-Key: $KEY" https://whapi.xpertnet.ai/channels/<id>/connect
curl -H "X-API-Key: $KEY" https://whapi.xpertnet.ai/channels/<id>/qr
# 3. отправить текст
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"to":"79991234567","body":"Привет"}' "https://whapi.xpertnet.ai/messages/text?channelId=<id>"
```

## Разделы API

- **analytics** (7): Аналитика сообщений
- **backups** (6): Резервные копии данных
- **business** (3): Бизнес-профиль
- **channels** (51): Каналы: создание, подключение по QR или коду, статус, вебхуки, прокси, диагностика
- **chats** (12): Чаты: список, архив, закрепление, отметка о прочтении
- **communities** (6): Сообщества
- **contacts** (10): Контакты, проверка номеров, блокировки
- **groups** (16): Группы и участники
- **labels** (7): Метки чатов
- **media** (5): Загрузка и скачивание медиа
- **messages** (31): Отправка сообщений всех типов и операции над ними
- **newsletters** (6): Каналы WhatsApp (newsletters)
- **presences** (3): Присутствие и статус «печатает…»
- **stories** (8): Статусы (истории)
- **system** (14): Служебные: здоровье, метрики, документация
- **users** (6): Профиль подключённого аккаунта
- **webhooks** (13): Вебхуки: мониторинг доставки, DLQ, песочница

## Полное описание

- [Все эндпоинты с параметрами](https://whapi.xpertnet.ai/llms-full.txt) — текст для агента
- [OpenAPI 3.1](https://whapi.xpertnet.ai/openapi.json) — машинночитаемая спецификация
- [HTML-документация](https://whapi.xpertnet.ai/docs)

## Важное про WhatsApp

- Отправка проходит через антибан-шлюз: паузы 3–8 с между сообщениями, лимиты в час и в день,
  прогрев нового аккаунта. При превышении возвращается 429 с кодом причины — это ожидаемое поведение, не ошибка сети.
- Один аккаунт WhatsApp = один IP. Смена IP может инвалидировать сессию.
- Статусы канала: `connected`, `connecting`, `qr`, `pairing_code`, `disconnected`, `replaced` (сессию занял другой
  WhatsApp Web), `logged_out` (устройство отвязано), `banned`, `needs_qr`.