Довідник 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

Швидкий старт

Підтримка