· Nacho Coll · Guides · 9 min de lectura
API de Alertas de X: Suscripciones Programáticas e Historial de Notificaciones
Construye integraciones personalizadas sobre WALLAWHATS. Agrega y elimina suscripciones de X, enruta alertas a canales, extrae historial de notificaciones — todo vía REST.
Cuando las alertas en tiempo real de X (Twitter) se vuelven críticas para tu negocio, la gestión manual del dashboard llega a su límite. Ya sea que estés construyendo dashboards de inteligencia de clientes, automatizando flujos de monitoreo de marca, o creando sistemas de notificación personalizados para mesas de trading, necesitas control programático sobre tus suscripciones de alertas de X.
WALLAWHATS proporciona una API REST que te permite crear, gestionar y auditar suscripciones de alertas de X sin tocar la interfaz web. Agrega o elimina cuentas monitoreadas, 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 dashboard funciona genial para flujos 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 de industria conforme se descubren a través de herramientas de investigación o integraciones CRM.
Flujos de Trading y Financieros: Monitorea programáticamente cuentas regulatorias, handles de CEOs, o periodistas específicos de sectores basándote en cambios de portafolio o eventos de mercado—sin gestión manual de suscripciones.
Monitoreo de Marca a Escala: Agrega o elimina seguimiento de menciones de marca conforme nuevas campañas se lanzan, productos se envían, o situaciones de crisis se desarrollan.
Aplicaciones SaaS Multi-Inquilino: Monitoreo de X en tiempo real con marca blanca para tus clientes, con gestión programática de suscripciones tras bambalinas.
Sistemas de Cumplimiento y Auditoría: Extrae historial completo de notificaciones con estado de entrega para reportes regulatorios, rastros de auditoría interna, o monitoreo de SLA.
Autenticación y Acceso API
Cada plan de WALLAWHATS incluye acceso API con cuotas escalables de claves:
- 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 dashboard, 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 Principales 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 de eliminación 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: Confirmada como recibida por el destinoread: Abierta por el destinatario (solo WhatsApp, requiere confirmaciones de lectura habilitadas)failed: Intento de entrega fallido
Gestión de Canales
Listar canales configurados:
GET /channels
x-api-key: tu_clave_api_aquiAgregar 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/channel_id_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/tweet_id_aqui
x-api-key: tu_clave_api_aquiConstruyendo Integraciones: Ejemplos de Código
Integración Node.js
Aquí tienes un ejemplo de Node.js que agrega una suscripción y consulta por 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');
// Agregar una nueva suscripción
await client.addSubscription('vercel');
console.log('Ahora monitoreando @vercel');
// Revisar 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 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):
"""Agregar una nueva cuenta de X para monitorear"""
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 de X del monitoreo"""
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):
"""Obtener 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):
"""Obtener 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 diario
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 de Alertas Diarias - {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 Enrutamiento de Canales
WALLAWHATS usa un modelo de enrutamiento global de canales—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 canales ocurre a nivel de cuenta en la página de Canales. Cuando agregas 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 la fragmentación de alertas. Tu código de integración no necesita rastrear reglas de enrutamiento por suscripción—solo gestiona qué cuentas monitorear y qué canales habilitar.
Límites de Velocidad y Caps de Velocidad
WALLAWHATS implementa caps de velocidad a nivel de 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 caps de velocidad se exceden, tweets adicionales se almacenan en mensajes de 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 de resumen.
La API en sí no impone límites de velocidad separados en la gestión de suscripciones o consultas de notificaciones. Sin embargo, evita bombardear los endpoints con solicitudes innecesarias—cachea listas de suscripciones localmente y agrupa consultas de notificaciones eficientemente.
Manejo de Errores y Solución de Problemas
Patrones comunes de errores de API y cómo manejarlos:
Fallas 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 monitoreada: La suscripción existe, tratar 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 límites de plan en cuentas monitoreadas
Problemas de verificación de canales:
- Nuevos canales requieren verificación OTP antes de recibir alertas
- Canales agregados programáticamente no funcionarán hasta que el usuario complete la verificación
Monitoreando y Alertando tus Integraciones
Ya que WALLAWHATS se convierte en infraestructura crítica cuando se integra en flujos de negocio, monitorea la salud de tu integración:
Detección de Deriva de Suscripciones:
// Revisar 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;
}Monitoreo de Tasa de Éxito de Entrega:
def check_delivery_health():
# Revisar ú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"ADVERTENCIA: Tasa de éxito de entrega bajó 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 por nuevas alertas y procesarlas en tiempo casi 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 Condicional de Suscripciones: Agregar o eliminar suscripciones dinámicamente basándose en disparadores externos:
def update_competitor_monitoring(portfolio_companies):
"""Actualizar monitoreo de X basado en portafolio actual"""
current_subs = {s['xUsername'] for s in api.list_subscriptions()}
# Cuentas que deberíamos estar monitoreando
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'])
# Agregar suscripciones faltantes
for account in target_accounts - current_subs:
try:
api.add_subscription(account)
print(f"Empezando a monitorear @{account}")
except Exception as e:
print(f"Falló agregar @{account}: {e}")
# Eliminar suscripciones desactualizadas
for account in current_subs - target_accounts:
api.remove_subscription(account)
print(f"Dejando de monitorear @{account}")La API de WALLAWHATS transforma las alertas de X en tiempo real de una herramienta manual de dashboard a un componente de infraestructura programable. Ya sea que estés construyendo flujos personalizados de inteligencia, automatizando monitoreo de marca, o creando servicios de notificación con marca blanca, la API proporciona las capacidades de control y auditoría necesarias para integración en producción.
¿Buscas expandir tu monitoreo más allá de competidores? Revisa nuestra guía sobre monitorear crypto Twitter para señales de mercado o aprende cómo los periodistas usan WALLAWHATS para monitoreo de fuentes en tiempo real.
Nunca te pierdas un post importante otra vez. Crea una cuenta gratis — 1 número de WhatsApp, alertas en tiempo real, no se requiere tarjeta de crédito.
