Справочник API

REST API WallaWhats позволяет программно управлять телефонами, подписками на аккаунты X и историей уведомлений — именно тем, что вы делаете из дашборда.

Базовый URL: https://api.wallawhats.com
Content type: application/json
Аутентификация: ключ API (заголовок)
Версионирование: API стабильный. О несовместимых изменениях сообщается за 30 дней по электронной почте каждому аккаунту.

Аутентификация

Каждый запрос должен содержать ключ API в заголовке x-api-key:

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_00000000000000000000000000000000"

Ключи создаются в дашборде в разделе Настройки → Ключи API или через POST /apikeys. Префикс ключа начинается с bws_ и имеет длину 36 символов. Ключи отображаются только один раз, при создании — если вы его потеряли, удалите и создайте новый.

Область действия и срок

Ключ аутентифицируется как создавший его пользователь. У него те же права, что и у этого пользователя, и он учитывается в тех же квотах тарифа.
Ключи действительны 365 дней. Обновляйте их, создавая новый ключ, переключаясь на него и удаляя старый.
Отсутствующие, повреждённые или отозванные ключи возвращают 401 Unauthorized.

Лимиты тарифов на ключи

Тариф	Разрешено ключей
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Попытка создать больше ключей, чем допускает тариф, возвращает 400 с "error": "api key limit reached".

Ошибки

Ошибки возвращаются в формате JSON с полем error и HTTP-статус-кодом:

json

{ "error": "phoneNumber is required" }

Статус	Значение
`400`	Неверные параметры, превышена квота или нарушено бизнес-правило
`401`	Отсутствует или неверный ключ API
`402`	Недостаточно кредитов для выполнения операции
`404`	Ресурс не найден
`500`	Ошибка сервера — повторите с экспоненциальной задержкой

Ограничения частоты

По умолчанию: 20 запросов/секунду на ключ API, всплеск до 40.
Эндпоинты списков возвращают до 50 элементов на страницу; используйте курсор lastKey для пагинации.
Правила WAF могут возвращать 403 при подозрительных шаблонах. Свяжитесь с поддержкой, если сталкиваетесь с ограничением неожиданно.

Пользователь

Получение профиля

GET /user/profile

Возвращает профиль аутентифицированного пользователя.

Ответ

json

{
  "userId": "5a4cbd70-...",
  "email": "jane@example.com",
  "name": "Jane",
  "plan": "pro_plus",
  "createdAt": 1745000000000
}

Пример

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_..."

Телефоны

Телефон — это подтверждённый номер WhatsApp, который может получать уведомления. Телефон необходимо подтвердить прежде, чем подписывать на него аккаунт X.

Регистрация телефона

POST /phones

Генерирует 6-значный код и отправляет его на номер через WhatsApp. Телефон создаётся в статусе pending_verification.

Запрос

Поле	Тип	Обязательно	Примечания
`phoneNumber`	string	да	формат E.164, например `+34612345678`
`displayName`	string	нет	Удобная метка, отображаемая в дашборде

Ответ

json

{ "phoneNumber": "+34612345678", "status": "pending_verification" }

Ошибки

400 "invalid phone number format" — не соответствует E.164
400 "phone number limit reached" — превышен лимит тарифа (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Пример

bash

curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: bws_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+34612345678", "displayName": "Work"}'

Подтверждение телефона

POST /phones/verify

Подтверждает телефон отправкой 6-значного кода. Коды истекают через 15 минут.

Запрос

Поле	Тип	Обязательно
`phoneNumber`	string (E.164)	да
`code`	string (6 цифр)	да

Ответ

json

{ "phoneNumber": "+34612345678", "status": "verified" }

Ошибки

404 "phone not found"
400 "invalid code" — неверный код
400 "code expired" — старше 15 минут
400 "phone already verified"

Список телефонов

GET /phones

Ответ

json

{
  "phones": [
    {
      "phoneNumber": "+34612345678",
      "status": "verified",
      "displayName": "Work",
      "createdAt": 1745000000000,
      "verifiedAt": 1745000060000
    }
  ],
  "count": 1
}

Удаление телефона

DELETE /phones/{phoneNumber}

Удаляет телефон и деактивирует все подписки, нацеленные на него. Закодируйте + в URL как %2B.

Ответ

json

{ "success": true }

Пример

bash

curl -X DELETE "https://api.wallawhats.com/phones/%2B34612345678" \
  -H "x-api-key: bws_prod_..."

Подписки

Подписка связывает аккаунт X, за которым вы хотите следить, с одним из ваших подтверждённых телефонов. Когда аккаунт X публикует пост, WallaWhats отправляет уведомление WhatsApp на этот телефон.

Создание подписки

POST /subscriptions

Запрос

Поле	Тип	Обязательно	Примечания
`xUsername`	string	да	1–15 символов, алфанумерические и подчёркивание. Префикс `@` принимается и удаляется.
`phoneNumber`	string (E.164)	да	Должен быть одним из ваших подтверждённых телефонов.

Ответ

json

{
  "xUsername": "elonmusk",
  "xUserId": "44196397",
  "xDisplayName": "Elon Musk",
  "xProfileImage": "https://pbs.twimg.com/...",
  "phoneNumber": "+34612345678",
  "isActive": true,
  "createdAt": 1745000000000
}

Ошибки

400 "invalid X username format" — не соответствует регулярному выражению
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — см. таблицу тарифов ниже
404 "X account not found" — имя пользователя не найдено в X

Лимиты тарифов

Тариф	Подписки
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Список подписок

GET /subscriptions

Ответ

json

{
  "subscriptions": [ /* та же структура, что у ответа POST /subscriptions */ ],
  "count": 3
}

Удаление подписки

DELETE /subscriptions/{xUsername}

Сравнение xUsername без учёта регистра. Удалите @ перед отправкой.

Ответ

json

{ "success": true }

Уведомления

Каждое уведомление, доставленное WallaWhats, регистрируется здесь вместе со статусом доставки в WhatsApp.

Список уведомлений

GET /notifications

Параметры запроса

Параметр	Тип	Описание
`from`	number (мс epoch)	Фильтр: уведомления, созданные в это время или позже
`to`	number (мс epoch)	Фильтр: уведомления, созданные в это время или раньше
`lastKey`	string	Курсор пагинации, возвращённый предыдущим ответом

Ответ

json

{
  "notifications": [
    {
      "notificationId": "a1b2c3d4-...",
      "userId": "5a4cbd70-...",
      "phoneNumber": "+34612345678",
      "xUsername": "elonmusk",
      "tweetId": "1797123456789000000",
      "tweetText": "...",
      "tweetUrl": "https://x.com/elonmusk/status/...",
      "waMessageId": "wamid.HBgN...",
      "status": "delivered",
      "errorMessage": null,
      "createdAt": 1745000000000,
      "updatedAt": 1745000002000
    }
  ],
  "lastKey": "eyJOT1RJRklDQVRJT05fSUQi..."
}

Возможные значения status: queued, sent, delivered, read, failed.

Размер страницы — 50. Когда lastKey отсутствует, вы достигли конца.

Ключи API

Управляйте ключами, которые ваши приложения используют для вызова этого API.

Создание ключа API

POST /apikeys

Запрос

Поле	Тип	Обязательно
`name`	string	нет, по умолчанию `"Default"`

Ответ (201 Created)

json

{
  "apiKey": "bws_prod_00000000000000000000000000000000",
  "keyPrefix": "bws_prod_00",
  "keyName": "CI server",
  "createdAt": 1745000000000,
  "expiresAt": 1776536000000
}

Значение показывается один раз

apiKey возвращается только при создании. Немедленно сохраните его в вашем менеджере секретов. Последующие вызовы показывают только keyPrefix.

Список ключей API

GET /apikeys

Ответ

json

[
  {
    "keyPrefix": "bws_prod_00",
    "keyName": "CI server",
    "createdAt": 1745000000000,
    "lastUsedAt": 1745086400000,
    "expiresAt": 1776536000000
  }
]

Удаление ключа API

DELETE /apikeys/{keyPrefix}

Используйте 12-символьный keyPrefix из ответа списка — никогда полный ключ.

Ответ

json

{ "success": true }

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

bash

# 1. Создайте ключ в дашборде и экспортируйте его
export WALLA_API_KEY="bws_prod_..."

# 2. Зарегистрируйте и подтвердите номер WhatsApp
curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","displayName":"Mobile"}'
# -> на телефон приходит код WhatsApp. Отправьте его:
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","code":"123456"}'

# 3. Подпишитесь на аккаунт X
curl -X POST https://api.wallawhats.com/subscriptions \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xUsername":"elonmusk","phoneNumber":"+34612345678"}'

# 4. Смотрите, как поступают уведомления
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Вот и всё — как только аккаунт X опубликует пост, уведомление придёт на телефон примерно за 10 секунд.

Поддержка

Вопросы по API, сообщения об ошибках или запросы на увеличение квоты: откройте заявку во вкладке Поддержка в дашборде или напишите на hello@support.wallawhats.com.

Справочник API ​

Аутентификация ​

Область действия и срок ​

Лимиты тарифов на ключи ​

Ошибки ​

Ограничения частоты ​

Пользователь ​

Получение профиля ​

Телефоны ​

Регистрация телефона ​

Подтверждение телефона ​

Список телефонов ​

Удаление телефона ​

Подписки ​

Создание подписки ​

Список подписок ​

Удаление подписки ​

Уведомления ​

Список уведомлений ​

Ключи API ​

Создание ключа API ​

Список ключей API ​

Удаление ключа API ​

Быстрый старт ​

Поддержка ​

Справочник API

Аутентификация

Область действия и срок

Лимиты тарифов на ключи

Ошибки

Ограничения частоты

Пользователь

Получение профиля

Телефоны

Регистрация телефона

Подтверждение телефона

Список телефонов

Удаление телефона

Подписки

Создание подписки

Список подписок

Удаление подписки

Уведомления

Список уведомлений

Ключи API

Создание ключа API

Список ключей API

Удаление ключа API

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

Поддержка