Referència de l'API

L'API REST de WallaWhats us permet gestionar telèfons, subscripcions a comptes d'X i l'historial de notificacions de manera programàtica — exactament el que faríeu des del tauler.

URL base: https://api.wallawhats.com
Tipus de contingut: application/json
Autenticació: clau d'API (capçalera)
Versionat: l'API és estable. Els canvis incompatibles s'anuncien amb 30 dies d'antelació per correu electrònic a cada compte.

Autenticació

Totes les peticions han d'incloure una clau d'API a la capçalera x-api-key:

bash

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

Les claus es creen al tauler, a Configuració → Claus d'API, o mitjançant POST /apikeys. Un prefix de clau comença per bws_ i té 36 caràcters. Les claus només es mostren una vegada, en el moment de la creació — si en perdeu alguna, esborreu-la i creeu-ne una de nova.

Abast i caducitat

Una clau s'autentica com l'usuari que l'ha creada. Té els mateixos permisos que aquest usuari i es descompta de les mateixes quotes del pla.
Les claus són vàlides durant 365 dies. Renoveu-les creant-ne una de nova, fent el canvi i esborrant l'antiga.
Les claus absents, mal formades o revocades retornen 401 Unauthorized.

Límits del pla sobre les claus

Pla	Claus permeses
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Intentar crear-ne més de les que permet el pla retorna 400 amb "error": "api key limit reached".

Errors

Els errors es retornen com a JSON amb un camp error i un codi d'estat HTTP:

json

{ "error": "phoneNumber is required" }

Estat	Significat
`400`	Paràmetres no vàlids, quota superada o violació de regla de negoci
`401`	Clau d'API absent o no vàlida
`402`	No hi ha prou crèdits per completar l'operació
`404`	Recurs no trobat
`500`	Error del servidor — torneu-ho a provar amb retrocés exponencial

Límits de freqüència

Per defecte: 20 peticions/segon per clau d'API, amb ràfegues fins a 40.
Els endpoints de llista retornen fins a 50 elements per pàgina; feu servir el cursor lastKey per paginar.
Les regles del WAF poden retornar 403 en patrons abusius. Contacteu amb el suport si teniu limitacions de freqüència inesperades.

Usuari

Obtenir el vostre perfil

GET /user/profile

Retorna el perfil de l'usuari autenticat.

Resposta

json

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

Exemple

bash

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

Telèfons

Un telèfon és un número de WhatsApp verificat que pot rebre alertes. Cal verificar un telèfon abans de subscriure-hi un compte d'X.

Registrar un telèfon

POST /phones

Genera un codi de 6 dígits i l'envia al número per WhatsApp. El telèfon es crea en estat pending_verification.

Petició

Camp	Tipus	Obligatori	Notes
`phoneNumber`	string	sí	Format E.164, p. ex. `+34612345678`
`displayName`	string	no	Etiqueta descriptiva mostrada al tauler

Resposta

json

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

Errors

400 "invalid phone number format" — no compleix E.164
400 "phone number limit reached" — supera el límit del pla (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Exemple

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"}'

Verificar un telèfon

POST /phones/verify

Confirma un telèfon enviant el codi de 6 dígits. Els codis caduquen al cap de 15 minuts.

Petició

Camp	Tipus	Obligatori
`phoneNumber`	string (E.164)	sí
`code`	string (6 dígits)	sí

Resposta

json

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

Errors

404 "phone not found"
400 "invalid code" — codi incorrecte
400 "code expired" — més de 15 minuts
400 "phone already verified"

Llistar els vostres telèfons

GET /phones

Resposta

json

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

Esborrar un telèfon

DELETE /phones/{phoneNumber}

Elimina el telèfon i desactiva qualsevol subscripció que l'utilitzés com a destí. Codifiqueu el + com a %2B a la URL.

Resposta

json

{ "success": true }

Exemple

bash

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

Subscripcions

Una subscripció enllaça un compte d'X que voleu monitorar amb un dels vostres telèfons verificats. Quan el compte d'X publica, WallaWhats envia una alerta de WhatsApp a aquest telèfon.

Crear una subscripció

POST /subscriptions

Petició

Camp	Tipus	Obligatori	Notes
`xUsername`	string	sí	1–15 caràcters, alfanumèrics i guió baix. S'accepta el prefix `@` i s'elimina.
`phoneNumber`	string (E.164)	sí	Ha de ser un dels vostres telèfons verificats.

Resposta

json

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

Errors

400 "invalid X username format" — no coincideix amb l'expressió regular
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — vegeu la taula del pla més avall
404 "X account not found" — el nom d'usuari no es resol a X

Límits del pla

Pla	Subscripcions
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Llistar les vostres subscripcions

GET /subscriptions

Resposta

json

{
  "subscriptions": [ /* mateixa forma que la resposta de POST /subscriptions */ ],
  "count": 3
}

Esborrar una subscripció

DELETE /subscriptions/{xUsername}

Coincidència insensible a majúscules i minúscules a xUsername. Elimineu l'@ abans d'enviar.

Resposta

json

{ "success": true }

Notificacions

Cada alerta que WallaWhats envia es registra aquí, juntament amb el seu estat de lliurament a WhatsApp.

Llistar notificacions

GET /notifications

Paràmetres de consulta

Paràmetre	Tipus	Descripció
`from`	number (ms epoch)	Filtra notificacions creades en aquest instant o després
`to`	number (ms epoch)	Filtra notificacions creades en aquest instant o abans
`lastKey`	string	Cursor de paginació retornat per la resposta anterior

Resposta

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..."
}

Valors possibles de status: queued, sent, delivered, read, failed.

La mida de pàgina és 50. Quan lastKey no hi és, heu arribat al final.

Claus d'API

Gestioneu les claus que les vostres aplicacions utilitzen per cridar aquesta API.

Crear una clau d'API

POST /apikeys

Petició

Camp	Tipus	Obligatori
`name`	string	no, per defecte `"Default"`

Resposta (201 Created)

json

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

Valor mostrat només una vegada

apiKey es retorna només en el moment de la creació. Deseu-la immediatament al vostre gestor de secrets. Les crides següents només exposen el keyPrefix.

Llistar les vostres claus d'API

GET /apikeys

Resposta

json

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

Esborrar una clau d'API

DELETE /apikeys/{keyPrefix}

Utilitzeu el keyPrefix de 12 caràcters de la resposta de la llista — mai la clau sencera.

Resposta

json

{ "success": true }

Inici ràpid

bash

# 1. Creeu una clau al tauler i exporteu-la
export WALLA_API_KEY="bws_prod_..."

# 2. Registreu i verifiqueu el vostre número de 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"}'
# -> el telèfon rep un codi de WhatsApp. Envieu-lo:
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. Subscriviu-vos a un compte d'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. Mireu com arriben les alertes
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Ja està — quan el compte d'X publiqui, l'alerta arribarà al telèfon en uns 10 segons.

Suport

Preguntes sobre l'API, informes d'errors o sol·licituds d'increment de quota: obriu una sol·licitud des de la pestanya Suport del vostre tauler, o envieu un correu a hello@support.wallawhats.com.

Referència de l'API ​

Autenticació ​

Abast i caducitat ​

Límits del pla sobre les claus ​

Errors ​

Límits de freqüència ​

Usuari ​

Obtenir el vostre perfil ​

Telèfons ​

Registrar un telèfon ​

Verificar un telèfon ​

Llistar els vostres telèfons ​

Esborrar un telèfon ​

Subscripcions ​

Crear una subscripció ​

Llistar les vostres subscripcions ​

Esborrar una subscripció ​

Notificacions ​

Llistar notificacions ​

Claus d'API ​

Crear una clau d'API ​

Llistar les vostres claus d'API ​

Esborrar una clau d'API ​

Inici ràpid ​

Suport ​

Referència de l'API

Autenticació

Abast i caducitat

Límits del pla sobre les claus

Errors

Límits de freqüència

Usuari

Obtenir el vostre perfil

Telèfons

Registrar un telèfon

Verificar un telèfon

Llistar els vostres telèfons

Esborrar un telèfon

Subscripcions

Crear una subscripció

Llistar les vostres subscripcions

Esborrar una subscripció

Notificacions

Llistar notificacions

Claus d'API

Crear una clau d'API

Llistar les vostres claus d'API

Esborrar una clau d'API

Inici ràpid

Suport