API справочник

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

Основен URL: https://api.wallawhats.com
Тип съдържание: application/json
Удостоверяване: API ключ (заглавка)
Версии: API-то е стабилно. Промените, които нарушават съвместимостта, се обявяват 30 дни предварително чрез имейл до всеки акаунт.

Удостоверяване

Всяка заявка трябва да съдържа API ключ в заглавката x-api-key:

bash

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

Ключовете се създават в таблото под Settings → API Keys или чрез 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" — regex неуспешен
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 (ms epoch)	Филтрирайте известия, създадени в или след този момент
`to`	number (ms 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, доклади за грешки или заявки за увеличаване на квотата: отворете заявка от таба Support във вашето табло или изпратете имейл на hello@support.wallawhats.com.

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

Удостоверяване ​

Обхват и изтичане ​

Ограничения на плана за ключове ​

Грешки ​

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

Потребител ​

Вземете профила си ​

Телефони ​

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

Потвърдете телефон ​

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

Изтрийте телефон ​

Абонаменти ​

Създайте абонамент ​

Списък на вашите абонаменти ​

Изтрийте абонамент ​

Известия ​

Списък на известията ​

API ключове ​

Създайте API ключ ​

Списък на вашите API ключове ​

Изтрийте API ключ ​

Бърз старт ​

Поддръжка ​

API справочник

Удостоверяване

Обхват и изтичане

Ограничения на плана за ключове

Грешки

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

Потребител

Вземете профила си

Телефони

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

Потвърдете телефон

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

Изтрийте телефон

Абонаменти

Създайте абонамент

Списък на вашите абонаменти

Изтрийте абонамент

Известия

Списък на известията

API ключове

Създайте API ключ

Списък на вашите API ключове

Изтрийте API ключ

Бърз старт

Поддръжка