Referencia de API

La API REST de WallaWhats te permite gestionar teléfonos, suscripciones a cuentas de X e historial de notificaciones de forma programática — exactamente lo mismo que harías desde el panel.

URL base: https://api.wallawhats.com
Content type: application/json
Autenticación: API key (cabecera)
Versionado: la API es estable. Los cambios incompatibles se anuncian con 30 días de antelación por correo electrónico a cada cuenta.

Autenticación

Toda petición debe incluir una API key en la cabecera x-api-key:

bash

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

Las claves se crean en el panel, en Settings → API Keys, o a través de POST /apikeys. El prefijo de clave empieza por bws_ y tiene 36 caracteres. Las claves se muestran una sola vez, al crearlas — si pierdes una, elimínala y crea otra.

Alcance y caducidad

Una clave autentica como el usuario que la creó. Tiene los mismos permisos que ese usuario y consume las mismas cuotas del plan.
Las claves son válidas durante 365 días. Rota creando una clave nueva, migrando a ella y eliminando la antigua.
Claves ausentes, mal formadas o revocadas devuelven 401 Unauthorized.

Límite de claves por plan

Plan	Claves permitidas
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Intentar crear más de las que permite tu plan devuelve 400 con "error": "api key limit reached".

Errores

Los errores se devuelven en JSON con un campo error y un código de estado HTTP:

json

{ "error": "phoneNumber is required" }

Status	Significado
`400`	Parámetros inválidos, cuota superada o violación de regla de negocio
`401`	API key ausente o inválida
`402`	Créditos insuficientes para completar la operación
`404`	Recurso no encontrado
`500`	Error del servidor — reintenta con retroceso exponencial

Límites de tasa

Por defecto: 20 peticiones/segundo por API key, con ráfagas de hasta 40.
Los endpoints de listado devuelven hasta 50 elementos por página; usa el cursor lastKey para paginar.
Las reglas del WAF pueden devolver 403 ante patrones abusivos. Si crees que te están limitando de forma inesperada, contacta con soporte.

User

Obtener tu perfil

GET /user/profile

Devuelve el perfil del usuario autenticado.

Respuesta

json

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

Ejemplo

bash

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

Phones

Un teléfono es un número de WhatsApp verificado que puede recibir alertas. Debes verificar un teléfono antes de suscribirle una cuenta de X.

Registrar un teléfono

POST /phones

Genera un código de 6 dígitos y lo envía al número por WhatsApp. El teléfono se crea en estado pending_verification.

Petición

Campo	Tipo	Requerido	Notas
`phoneNumber`	string	sí	Formato E.164, por ejemplo `+34612345678`
`displayName`	string	no	Etiqueta descriptiva mostrada en el panel

Respuesta

json

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

Errores

400 "invalid phone number format" — no es E.164
400 "phone number limit reached" — supera el máximo del plan (Free/Pro 1, Pro+ 2, Business 3, Enterprise 10)

Ejemplo

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éfono

POST /phones/verify

Confirma un teléfono enviando el código de 6 dígitos. Los códigos caducan a los 15 minutos.

Petición

Campo	Tipo	Requerido
`phoneNumber`	string (E.164)	sí
`code`	string (6 dígitos)	sí

Respuesta

json

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

Errores

404 "phone not found"
400 "invalid code" — código incorrecto
400 "code expired" — más de 15 minutos
400 "phone already verified"

Listar tus teléfonos

GET /phones

Respuesta

json

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

Eliminar un teléfono

DELETE /phones/{phoneNumber}

Elimina el teléfono y desactiva cualquier suscripción que lo tuviera como destino. Codifica el + en la URL como %2B.

Respuesta

json

{ "success": true }

Ejemplo

bash

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

Subscriptions

Una suscripción vincula una cuenta de X que quieres monitorizar con uno de tus teléfonos verificados. Cuando la cuenta de X publica, WallaWhats envía una alerta de WhatsApp a ese teléfono.

Crear una suscripción

POST /subscriptions

Petición

Campo	Tipo	Requerido	Notas
`xUsername`	string	sí	1–15 caracteres, alfanumérico + guion bajo. El prefijo `@` se acepta y se elimina.
`phoneNumber`	string (E.164)	sí	Debe ser uno de tus teléfonos verificados.

Respuesta

json

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

Errores

400 "invalid X username format" — la regex falla
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — consulta la tabla de planes más abajo
404 "X account not found" — el nombre de usuario no existe en X

Límites por plan

Plan	Suscripciones
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Listar tus suscripciones

GET /subscriptions

Respuesta

json

{
  "subscriptions": [ /* misma estructura que la respuesta de POST /subscriptions */ ],
  "count": 3
}

Eliminar una suscripción

DELETE /subscriptions/{xUsername}

Coincidencia insensible a mayúsculas en xUsername. Quita el @ antes de enviarlo.

Respuesta

json

{ "success": true }

Notifications

Toda alerta que WallaWhats entrega se registra aquí, junto con su estado de entrega en WhatsApp.

Listar notificaciones

GET /notifications

Parámetros de consulta

Parámetro	Tipo	Descripción
`from`	number (epoch ms)	Filtra notificaciones creadas en o después de este instante
`to`	number (epoch ms)	Filtra notificaciones creadas en o antes de este instante
`lastKey`	string	Cursor de paginación devuelto por la respuesta anterior

Respuesta

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

Valores posibles de status: queued, sent, delivered, read, failed.

El tamaño de página es 50. Cuando no viene lastKey, has llegado al final.

API keys

Gestiona las claves que usan tus aplicaciones para llamar a esta API.

Crear una API key

POST /apikeys

Petición

Campo	Tipo	Requerido
`name`	string	no, por defecto `"Default"`

Respuesta (201 Created)

json

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

Valor mostrado una sola vez

apiKey se devuelve solo al crearla. Guárdala en tu gestor de secretos de inmediato. Las llamadas posteriores solo exponen el keyPrefix.

Listar tus API keys

GET /apikeys

Respuesta

json

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

Eliminar una API key

DELETE /apikeys/{keyPrefix}

Usa el keyPrefix de 12 caracteres de la respuesta del listado — nunca la clave completa.

Respuesta

json

{ "success": true }

Inicio rápido

bash

# 1. Crea una clave en el panel y expórtala
export WALLA_API_KEY="bws_prod_..."

# 2. Registra y verifica tu 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éfono recibe un código por WhatsApp. Envíalo:
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. Suscríbete a una cuenta de 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. Observa cómo llegan las alertas
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Eso es todo — en cuanto la cuenta de X publique, la alerta llegará al teléfono en unos 10 segundos.

Soporte

Consultas sobre la API, informes de errores o ampliaciones de cuota: abre un ticket desde la pestaña Support de tu panel, o escribe a hello@support.wallawhats.com.

Referencia de API ​

Autenticación ​

Alcance y caducidad ​

Límite de claves por plan ​

Errores ​

Límites de tasa ​

User ​

Obtener tu perfil ​

Phones ​

Registrar un teléfono ​

Verificar un teléfono ​

Listar tus teléfonos ​

Eliminar un teléfono ​

Subscriptions ​

Crear una suscripción ​

Listar tus suscripciones ​

Eliminar una suscripción ​

Notifications ​

Listar notificaciones ​

API keys ​

Crear una API key ​

Listar tus API keys ​

Eliminar una API key ​

Inicio rápido ​

Soporte ​

Referencia de API

Autenticación

Alcance y caducidad

Límite de claves por plan

Errores

Límites de tasa

User

Obtener tu perfil

Phones

Registrar un teléfono

Verificar un teléfono

Listar tus teléfonos

Eliminar un teléfono

Subscriptions

Crear una suscripción

Listar tus suscripciones

Eliminar una suscripción

Notifications

Listar notificaciones

API keys

Crear una API key

Listar tus API keys

Eliminar una API key

Inicio rápido

Soporte