· Nacho Coll · Guides · 9 min de lectura
API de Alertas X: Suscripciones Programáticas e Historial de Notificaciones
Construye integraciones personalizadas encima de WALLAWHATS. Añade y elimina suscripciones de X, enruta alertas a canales, extrae historial de notificaciones — todo vía REST.
Cuando las alertas de X (Twitter) en tiempo real se vuelven críticas para tu negocio, la gestión manual desde el panel de control alcanza sus límites. Ya sea que estés construyendo paneles de inteligencia de clientes, automatizando flujos de trabajo de monitorización de marca, o creando sistemas personalizados de notificaciones para mesas de trading, necesitas control programático sobre tus suscripciones de alertas X.
WALLAWHATS proporciona una API REST que te permite crear, gestionar y auditar suscripciones de alertas X sin tocar la interfaz web. Añade o elimina cuentas monitorizadas, extrae historial de notificaciones con estado de entrega, e integra alertas de X en tiempo real en cualquier sistema que hable HTTP.
¿Por Qué Usar la API de WALLAWHATS?
El panel de control funciona genial para flujos de trabajo manuales, pero el acceso API desbloquea escenarios de automatización que escalan más allá de la gestión humana:
Plataformas de Inteligencia de Clientes: Suscríbete automáticamente a ejecutivos competidores recién identificados, líderes de producto, o analistas del sector según se descubren através de herramientas de investigación o integraciones CRM.
Flujos de Trabajo Trading y Financieros: Monitoriza programáticamente cuentas regulatorias, perfiles de CEOs, o periodistas específicos del sector basándote en cambios de cartera o eventos del mercado — sin gestión manual de suscripciones.
Monitorización de Marca a Escala: Añade o elimina seguimiento de menciones de marca según se lanzan nuevas campañas, salen productos, o se desarrollan situaciones de crisis.
Aplicaciones SaaS Multi-Tenant: Monitorización X en tiempo real de marca blanca para tus clientes, con gestión programática de suscripciones entre bastidores.
Sistemas de Cumplimiento y Auditoría: Extrae historial completo de notificaciones con estado de entrega para reportes regulatorios, rastros de auditoría interna, o monitorización de SLA.
Autenticación y Acceso API
Cada plan de WALLAWHATS incluye acceso API con cuotas de claves escalables:
- Free: 1 clave API
- Pro: 1 clave API
- Pro+: 2 claves API
- Business: 5 claves API
- Enterprise: 20 claves API
La autenticación usa el header x-api-key (no Authorization: Bearer). Genera tus claves desde la sección API del panel de control, y trátalas como contraseñas — tienen privilegios completos de cuenta.
curl -H "x-api-key: tu_clave_api_aqui" \
https://api.wallawhats.com/subscriptionsEndpoints Core de la API
La API de WALLAWHATS proporciona cinco grupos principales de recursos para construir integraciones:
Gestión de Suscripciones
Crear una nueva suscripción:
POST /subscriptions
Content-Type: application/json
x-api-key: tu_clave_api_aqui
{
"xUsername": "elonmusk"
}Listar todas las suscripciones:
GET /subscriptions
x-api-key: tu_clave_api_aquiEliminar una suscripción:
DELETE /subscriptions/elonmusk
x-api-key: tu_clave_api_aquiNota que el endpoint delete toma el handle de X como parámetro de ruta — no un ID interno de suscripción.
Historial de Notificaciones y Auditoría
Extraer historial de notificaciones con estado de entrega:
GET /notifications?from=1704067200000&to=1704153600000
x-api-key: tu_clave_api_aquiEl endpoint de notificaciones devuelve resultados paginados con cada fila representando una alerta entregada a un canal. Los valores de estado incluyen:
queued: Alerta aceptada, esperando entregasent: Enviada al proveedor del canaldelivered: Confirmado recibido por el destinoread: Abierto por el receptor (solo WhatsApp, requiere confirmaciones de lectura habilitadas)failed: Intento de entrega sin éxito
Gestión de Canales
Listar canales configurados:
GET /channels
x-api-key: tu_clave_api_aquiAñadir un nuevo canal:
POST /channels
Content-Type: application/json
x-api-key: tu_clave_api_aqui
{
"type": "email",
"destination": "alerts@tuempresa.com"
}Eliminar un canal:
DELETE /channels/id_del_canal_aqui
x-api-key: tu_clave_api_aquiCapturas de Tweets
Acceder a la galería de capturas:
GET /snapshots
x-api-key: tu_clave_api_aquiEliminar una captura específica:
DELETE /snapshots/id_del_tweet_aqui
x-api-key: tu_clave_api_aquiConstruyendo Integraciones: Ejemplos de Código
Integración Node.js
Aquí tienes un ejemplo Node.js que añade una suscripción y consulta nuevas notificaciones:
const axios = require('axios');
class WallaWhatsClient {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseURL = 'https://api.wallawhats.com';
}
async addSubscription(xUsername) {
try {
const response = await axios.post(
`${this.baseURL}/subscriptions`,
{ xUsername },
{ headers: { 'x-api-key': this.apiKey } }
);
return response.data;
} catch (error) {
throw new Error(`Failed to add subscription: ${error.response?.data?.message || error.message}`);
}
}
async getNotifications(from, to, lastKey = null) {
try {
let url = `${this.baseURL}/notifications?from=${from}&to=${to}`;
if (lastKey) url += `&lastKey=${lastKey}`;
const response = await axios.get(url, {
headers: { 'x-api-key': this.apiKey }
});
return response.data;
} catch (error) {
throw new Error(`Failed to fetch notifications: ${error.response?.data?.message || error.message}`);
}
}
async listSubscriptions() {
try {
const response = await axios.get(
`${this.baseURL}/subscriptions`,
{ headers: { 'x-api-key': this.apiKey } }
);
return response.data;
} catch (error) {
throw new Error(`Failed to list subscriptions: ${error.response?.data?.message || error.message}`);
}
}
}
// Ejemplo de uso
async function monitorCompetitor() {
const client = new WallaWhatsClient('tu_clave_api_aqui');
// Añadir una nueva suscripción
await client.addSubscription('vercel');
console.log('Ahora monitorizando @vercel');
// Verificar notificaciones recientes
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
const notifications = await client.getNotifications(oneDayAgo, Date.now());
console.log(`Encontradas ${notifications.items.length} alertas recientes`);
notifications.items.forEach(notification => {
console.log(`${notification.xUsername}: ${notification.status} en ${notification.timestamp}`);
});
}Integración Python
Para flujos de trabajo Python, aquí tienes una clase que maneja gestión de suscripciones y consulta de notificaciones:
import requests
import time
from datetime import datetime, timedelta
class WallaWhatsAPI:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://api.wallawhats.com'
self.headers = {'x-api-key': api_key}
def add_subscription(self, x_username):
"""Añadir una nueva cuenta X para monitorizar"""
response = requests.post(
f'{self.base_url}/subscriptions',
json={'xUsername': x_username},
headers=self.headers
)
response.raise_for_status()
return response.json()
def remove_subscription(self, x_username):
"""Eliminar una cuenta X de la monitorización"""
response = requests.delete(
f'{self.base_url}/subscriptions/{x_username}',
headers=self.headers
)
response.raise_for_status()
return response.status_code == 200
def get_notifications(self, from_ms, to_ms, last_key=None):
"""Recuperar historial de notificaciones con paginación"""
params = {'from': from_ms, 'to': to_ms}
if last_key:
params['lastKey'] = last_key
response = requests.get(
f'{self.base_url}/notifications',
params=params,
headers=self.headers
)
response.raise_for_status()
return response.json()
def get_all_notifications(self, from_ms, to_ms):
"""Recuperar todas las notificaciones en un rango de tiempo, manejando paginación"""
all_notifications = []
last_key = None
while True:
batch = self.get_notifications(from_ms, to_ms, last_key)
all_notifications.extend(batch['items'])
if not batch.get('lastKey'):
break
last_key = batch['lastKey']
return all_notifications
def list_subscriptions(self):
"""Obtener todas las suscripciones actuales"""
response = requests.get(
f'{self.base_url}/subscriptions',
headers=self.headers
)
response.raise_for_status()
return response.json()
# Ejemplo: Reporte de auditoría diaria
def generate_daily_report():
api = WallaWhatsAPI('tu_clave_api_aqui')
# Obtener notificaciones de ayer
end_time = int(time.time() * 1000)
start_time = end_time - (24 * 60 * 60 * 1000)
notifications = api.get_all_notifications(start_time, end_time)
# Agrupar por cuenta y estado
report = {}
for notification in notifications:
account = notification['xUsername']
status = notification['status']
if account not in report:
report[account] = {'total': 0, 'delivered': 0, 'failed': 0}
report[account]['total'] += 1
if status in ['delivered', 'read']:
report[account]['delivered'] += 1
elif status == 'failed':
report[account]['failed'] += 1
# Imprimir resumen
print(f"Reporte Diario de Alertas - {datetime.now().strftime('%Y-%m-%d')}")
print("-" * 50)
for account, stats in report.items():
success_rate = (stats['delivered'] / stats['total']) * 100 if stats['total'] > 0 else 0
print(f"@{account}: {stats['total']} alertas, {success_rate:.1f}% entregadas")Entendiendo el Enrutado de Canales
WALLAWHATS usa un modelo de enrutado de canales global — cada alerta de cada suscripción se distribuye a todos los canales habilitados y verificados. No puedes enrutar cuentas específicas a destinos específicos vía la API (como “@elonmusk → WhatsApp, @vercel → email”).
La selección de canal ocurre a nivel de cuenta en la página de Canales. Cuando añades un canal vía API, se vuelve disponible para todas las alertas una vez verificado. Cuando eliminas un canal, deja de recibir alertas de todas las suscripciones.
Este diseño simplifica la automatización mientras previene fragmentación de alertas. Tu código de integración no necesita rastrear reglas de enrutado por suscripción — solo gestiona qué cuentas monitorizar y qué canales habilitar.
Límites de Velocidad y Topes de Velocidad
WALLAWHATS implementa topes de velocidad por usuario para prevenir spam de alertas durante períodos de alta actividad:
- Free: 2 alertas/hora
- Pro: 5 alertas/hora
- Pro+: 15 alertas/hora
- Business: 30 alertas/hora
- Enterprise: 100 alertas/hora
Cuando los topes de velocidad se exceden, los tweets adicionales se almacenan en mensajes resumen y se entregan cada 15 minutos. Tu integración API verá estos como registros de notificación separados — uno para la alerta inmediata, y uno para cada lote resumen.
La API misma no impone límites de velocidad separados en gestión de suscripciones o consultas de notificación. Sin embargo, evita bombardear los endpoints con solicitudes innecesarias — cachea listas de suscripción localmente y haz lotes de consultas de notificación eficientemente.
Manejo de Errores y Resolución de Problemas
Patrones comunes de errores API y cómo manejarlos:
Fallos de autenticación (401):
- Verifica que tu clave API sea correcta y no haya sido revocada
- Asegúrate de usar el header
x-api-key, noAuthorization
Conflictos de suscripción (409):
- Cuenta ya monitorizada: La suscripción existe, trata como éxito
- Cuenta protegida/privada: WALLAWHATS las rechaza por diseño
Limitación de velocidad (429):
- Retrocede exponencialmente antes de reintentar
- Verifica si te acercas a los límites del plan en cuentas monitorizadas
Problemas de verificación de canal:
- Los canales nuevos requieren verificación OTP antes de recibir alertas
- Los canales añadidos programáticamente no funcionarán hasta que el usuario complete la verificación
Monitorizando y Alertando Tus Integraciones
Como WALLAWHATS se convierte en infraestructura crítica cuando se integra en flujos de trabajo empresariales, monitoriza la salud de tu integración:
Detección de Deriva de Suscripciones:
// Verificar si las suscripciones esperadas siguen activas
async function auditSubscriptions(expectedHandles) {
const current = await client.listSubscriptions();
const currentHandles = current.map(s => s.xUsername);
const missing = expectedHandles.filter(h => !currentHandles.includes(h));
if (missing.length > 0) {
console.warn(`Suscripciones faltantes: ${missing.join(', ')}`);
}
return missing;
}Monitorización de Tasa de Éxito de Entrega:
def check_delivery_health():
# Verificar últimas 6 horas
end_time = int(time.time() * 1000)
start_time = end_time - (6 * 60 * 60 * 1000)
notifications = api.get_all_notifications(start_time, end_time)
if not notifications:
return None
delivered = sum(1 for n in notifications if n['status'] in ['delivered', 'read'])
total = len(notifications)
success_rate = (delivered / total) * 100
if success_rate < 95:
# Alertar a tu equipo de ops
print(f"AVISO: La tasa de éxito de entrega cayó a {success_rate:.1f}%")
return success_ratePatrones de Integración y Mejores Prácticas
Procesamiento Estilo Webhook: Aunque WALLAWHATS no proporciona webhooks directamente, puedes consultar el endpoint de notificaciones para nuevas alertas y procesarlas en casi tiempo real:
async function pollForNewAlerts() {
const lastCheck = localStorage.getItem('lastNotificationCheck') || Date.now() - 300000;
const now = Date.now();
const notifications = await client.getNotifications(lastCheck, now);
for (const notification of notifications.items) {
if (notification.status === 'delivered') {
// Procesar la alerta - enviar a Slack, actualizar base de datos, etc.
await processAlert(notification);
}
}
localStorage.setItem('lastNotificationCheck', now);
}
// Consultar cada 30 segundos
setInterval(pollForNewAlerts, 30000);Gestión de Suscripciones Condicional: Añadir o eliminar suscripciones dinámicamente basándote en activadores externos:
def update_competitor_monitoring(portfolio_companies):
"""Actualizar monitorización X basándose en cartera actual"""
current_subs = {s['xUsername'] for s in api.list_subscriptions()}
# Cuentas que deberíamos estar monitorizando
target_accounts = set()
for company in portfolio_companies:
if company.get('ceo_twitter_handle'):
target_accounts.add(company['ceo_twitter_handle'])
if company.get('company_twitter_handle'):
target_accounts.add(company['company_twitter_handle'])
# Añadir suscripciones faltantes
for account in target_accounts - current_subs:
try:
api.add_subscription(account)
print(f"Comenzó a monitorizar @{account}")
except Exception as e:
print(f"Falló al añadir @{account}: {e}")
# Eliminar suscripciones desactualizadas
for account in current_subs - target_accounts:
api.remove_subscription(account)
print(f"Dejó de monitorizar @{account}")La API de WALLAWHATS transforma alertas de X en tiempo real de una herramienta manual de panel de control a un componente de infraestructura programable. Ya sea que estés construyendo flujos de trabajo de inteligencia personalizados, automatizando monitorización de marca, o creando servicios de notificación de marca blanca, la API proporciona el control y capacidades de auditoría necesarios para integración en producción.
¿Quieres expandir tu monitorización más allá de competidores? Echa un vistazo a nuestra guía sobre monitorización de Twitter crypto para señales de mercado o aprende cómo los periodistas usan WALLAWHATS para monitorización de fuentes en tiempo real.
Nunca te pierdas una publicación importante otra vez. Crea una cuenta gratuita — 1 número WhatsApp, alertas en tiempo real, sin tarjeta de crédito requerida.
