· Nacho Coll · Guides · 9 min de lectura
API d'Alertes de X: Subscripcions Programàtiques i Historial de Notificacions
Crea integracions personalitzades sobre WALLAWHATS. Afegeix i elimina subscripcions de X, dirigeix alertes a canals, consulta l'historial de notificacions — tot via REST.
Quan les alertes en temps real de X (Twitter) es tornen críticament importants per al teu negoci, la gestió manual del panell de control arriba al límit. Ja sigui que estiguis construint panells d’intel·ligència de clients, automatitzant fluxos de monitoratge de marca, o creant sistemes de notificació personalitzats per a sales de trading, necessites control programàtic sobre les teves subscripcions d’alertes de X.
WALLAWHATS proporciona una API REST que et permet crear, gestionar i auditar subscripcions d’alertes de X sense tocar la interfície web. Afegeix o elimina comptes monitoritzats, consulta l’historial de notificacions amb l’estat de lliurament, i integra alertes de X en temps real a qualsevol sistema que parli HTTP.
Per Què Utilitzar l’API de WALLAWHATS?
El panell de control funciona perfectament per a fluxos manuals, però l’accés a l’API desbloqueja escenaris d’automatització que escalen més enllà de la gestió humana:
Plataformes d’Intel·ligència de Clients: Subscriu automàticament als executius de la competència, responsables de producte o analistes del sector recentment identificats mentre són descoberts a través d’eines de recerca o integracions de CRM.
Fluxos de Trading i Financers: Monitora programàticament comptes reguladors, perfils de CEOs o periodistes específics de sectors basats en canvis de cartera o esdeveniments del mercat—sense gestió manual de subscripcions.
Monitoratge de Marca a Escala: Afegeix o elimina el seguiment de mencions de marca mentre es llancen noves campanyes, s’envien productes o es desenvolupen situacions de crisi.
Aplicacions SaaS Multi-Tenant: Monitora X en temps real amb marca blanca per als teus clients, amb gestió programàtica de subscripcions entre bastidors.
Sistemes de Compliment i Auditoria: Consulta l’historial complet de notificacions amb l’estat de lliurament per a informes reguladors, auditories internes o monitoratge d’SLA.
Autenticació i Accés de l’API
Tots els plans de WALLAWHATS inclouen accés a l’API amb quotes de claus escalables:
- Free: 1 clau API
- Pro: 1 clau API
- Pro+: 2 claus API
- Business: 5 claus API
- Enterprise: 20 claus API
L’autenticació utilitza la capçalera x-api-key (no Authorization: Bearer). Genera les teves claus des de la secció API del panell, i tracta-les com contrasenyes—tenen tots els privilegis del compte.
curl -H "x-api-key: your_api_key_here" \
https://api.wallawhats.com/subscriptionsEndpoints Principals de l’API
L’API de WALLAWHATS proporciona cinc grups principals de recursos per construir integracions:
Gestió de Subscripcions
Crear una nova subscripció:
POST /subscriptions
Content-Type: application/json
x-api-key: your_api_key_here
{
"xUsername": "elonmusk"
}Llistar totes les subscripcions:
GET /subscriptions
x-api-key: your_api_key_hereEliminar una subscripció:
DELETE /subscriptions/elonmusk
x-api-key: your_api_key_hereNota que l’endpoint d’eliminació pren el nom d’usuari de X com a paràmetre de ruta—no un ID intern de subscripció.
Historial de Notificacions i Auditoria
Consultar historial de notificacions amb estat de lliurament:
GET /notifications?from=1704067200000&to=1704153600000
x-api-key: your_api_key_hereL’endpoint de notificacions retorna resultats paginats amb cada fila representant una alerta lliurada a un canal. Els valors d’estat inclouen:
queued: Alerta acceptada, esperant lliuramentsent: Enviada al proveïdor del canaldelivered: Confirmada rebuda pel destíread: Oberta pel destinatari (només WhatsApp, requereix confirmacions de lectura habilitades)failed: Intent de lliurament fallit
Gestió de Canals
Llistar canals configurats:
GET /channels
x-api-key: your_api_key_hereAfegir un nou canal:
POST /channels
Content-Type: application/json
x-api-key: your_api_key_here
{
"type": "email",
"destination": "alerts@yourcompany.com"
}Eliminar un canal:
DELETE /channels/channel_id_here
x-api-key: your_api_key_hereCaptures de Tuits
Accedir a la galeria de captures:
GET /snapshots
x-api-key: your_api_key_hereEliminar una captura específica:
DELETE /snapshots/tweet_id_here
x-api-key: your_api_key_hereConstruint Integracions: Exemples de Codi
Integració Node.js
Aquí tens un exemple de Node.js que afegeix una subscripció i consulta noves notificacions:
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(`Error en afegir subscripció: ${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(`Error en obtenir notificacions: ${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(`Error en llistar subscripcions: ${error.response?.data?.message || error.message}`);
}
}
}
// Exemple d'ús
async function monitorCompetitor() {
const client = new WallaWhatsClient('your_api_key_here');
// Afegir una nova subscripció
await client.addSubscription('vercel');
console.log('Ara monitorem @vercel');
// Consultar notificacions recents
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
const notifications = await client.getNotifications(oneDayAgo, Date.now());
console.log(`Trobades ${notifications.items.length} alertes recents`);
notifications.items.forEach(notification => {
console.log(`${notification.xUsername}: ${notification.status} a les ${notification.timestamp}`);
});
}Integració Python
Per a fluxos de Python, aquí tens una classe que gestiona les subscripcions i consulta les notificacions:
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):
"""Afegir un nou compte de X per monitora"""
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 un compte de X del monitoratge"""
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):
"""Obtenir historial de notificacions amb paginació"""
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):
"""Obtenir totes les notificacions en un rang de temps, gestionant la paginació"""
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):
"""Obtenir totes les subscripcions actuals"""
response = requests.get(
f'{self.base_url}/subscriptions',
headers=self.headers
)
response.raise_for_status()
return response.json()
# Exemple: Informe d'auditoria diari
def generate_daily_report():
api = WallaWhatsAPI('your_api_key_here')
# Obtenir les notificacions d'ahir
end_time = int(time.time() * 1000)
start_time = end_time - (24 * 60 * 60 * 1000)
notifications = api.get_all_notifications(start_time, end_time)
# Agrupar per compte i estat
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 resum
print(f"Informe d'Alertes Diàries - {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']} alertes, {success_rate:.1f}% lliurades")Entenent l’Enrutament de Canals
WALLAWHATS utilitza un model global d’enrutament de canals—cada alerta de cada subscripció s’envia a tots els canals habilitats i verificats. No pots dirigir comptes específics a destins específics via l’API (com “@elonmusk → WhatsApp, @vercel → email”).
La selecció de canals passa a nivell de compte a la pàgina de Canals. Quan afegeixes un canal via API, esdevé disponible per a totes les alertes un cop verificat. Quan elimines un canal, deixa de rebre alertes de totes les subscripcions.
Aquest disseny simplifica l’automatització mentre prevé la fragmentació d’alertes. El teu codi d’integració no necessita fer seguiment de regles d’enrutament per subscripció—només gestiona quins comptes monitorar i quins canals habilitar.
Límits de Velocitat i Caps de Velocitat
WALLAWHATS implementa caps de velocitat a nivell d’usuari per prevenir el spam d’alertes durant períodes d’alta activitat:
- Free: 2 alertes/hora
- Pro: 5 alertes/hora
- Pro+: 15 alertes/hora
- Business: 30 alertes/hora
- Enterprise: 100 alertes/hora
Quan es superen els caps de velocitat, els tuits addicionals s’agrupen en missatges resum i es lliuren cada 15 minuts. La teva integració d’API veurà aquests com a registres de notificació separats—un per a l’alerta immediata, i un per a cada lot de resum.
L’API en si no imposa límits de velocitat separats en la gestió de subscripcions o consultes de notificacions. No obstant això, evita bombardejar els endpoints amb peticions innecessàries—emmagatzema les llistes de subscripcions localment i agrupa les consultes de notificacions de manera eficient.
Gestió d’Errors i Resolució de Problemes
Patrons d’error comuns de l’API i com gestionar-los:
Fallades d’autenticació (401):
- Verifica que la teva clau API sigui correcta i no hagi estat revocada
- Assegura’t que estiguis utilitzant la capçalera
x-api-key, noAuthorization
Conflictes de subscripció (409):
- Compte ja monitoritzat: La subscripció existeix, tracta com a èxit
- Compte protegit/privat: WALLAWHATS els rebutja per disseny
Limitació de velocitat (429):
- Redueix exponencialment abans de reintenter
- Comprova si t’acostes als límits del pla en comptes monitoritzats
Problemes de verificació de canal:
- Els nous canals requereixen verificació OTP abans de rebre alertes
- Els canals afegits programàticament no funcionaran fins que l’usuari completi la verificació
Monitoratge i Alertes de les Teves Integracions
Com que WALLAWHATS es converteix en infraestructura crítica quan s’integra en fluxos de negoci, monitora la salut de la teva integració:
Detecció de Deriva de Subscripcions:
// Comprovar si les subscripcions esperades encara estan actives
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(`Subscripcions que falten: ${missing.join(', ')}`);
}
return missing;
}Monitoratge de Taxa d’Èxit de Lliurament:
def check_delivery_health():
# Comprovar les últimes 6 hores
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 al teu equip d'operacions
print(f"AVÍS: La taxa d'èxit de lliurament ha baixat al {success_rate:.1f}%")
return success_ratePatrons d’Integració i Millors Pràctiques
Processament Estil Webhook: Tot i que WALLAWHATS no proporciona webhooks directament, pots consultar l’endpoint de notificacions per alertes noves i processar-les en temps quasi 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') {
// Processar l'alerta - enviar a Slack, actualitzar base de dades, etc.
await processAlert(notification);
}
}
localStorage.setItem('lastNotificationCheck', now);
}
// Consultar cada 30 segons
setInterval(pollForNewAlerts, 30000);Gestió Condicional de Subscripcions: Afegeix o elimina subscripcions dinàmicament basant-te en disparadors externs:
def update_competitor_monitoring(portfolio_companies):
"""Actualitzar el monitoratge de X basat en la cartera actual"""
current_subs = {s['xUsername'] for s in api.list_subscriptions()}
# Comptes que hauríem de monitorar
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'])
# Afegir subscripcions que falten
for account in target_accounts - current_subs:
try:
api.add_subscription(account)
print(f"Hem començat a monitorar @{account}")
except Exception as e:
print(f"Error en afegir @{account}: {e}")
# Eliminar subscripcions obsoletes
for account in current_subs - target_accounts:
api.remove_subscription(account)
print(f"Hem deixat de monitorar @{account}")L’API de WALLAWHATS transforma les alertes de X en temps real d’una eina de panell manual a un component d’infraestructura programable. Ja sigui que estiguis construint fluxos d’intel·ligència personalitzats, automatitzant el monitoratge de marca, o creant serveis de notificació de marca blanca, l’API proporciona el control i les capacitats d’auditoria necessàries per a la integració en producció.
Vols expandir el teu monitoratge més enllà dels competidors? Consulta la nostra guia sobre monitorar Twitter cripto per senyals de mercat o aprèn com els periodistes utilitzen WALLAWHATS per al monitoratge de fonts en temps real.
Mai més et perdis un post important. Crea un compte gratuït — 1 número de WhatsApp, alertes en temps real, no cal targeta de crèdit.
