· Nacho Coll · Guides · 9 min di lettura
API Avvisi X: Sottoscrizioni Programmatiche e Cronologia Notifiche
Costruisci integrazioni personalizzate su WALLAWHATS. Aggiungi e rimuovi sottoscrizioni X, indirizza avvisi ai canali, estrai cronologia notifiche — tutto via REST.
Quando gli avvisi X (Twitter) in tempo reale diventano mission-critical per il tuo business, la gestione manuale del dashboard raggiunge il limite. Che tu stia costruendo dashboard di intelligence clienti, automatizzando flussi di monitoraggio del brand, o creando sistemi di notifiche personalizzati per desk di trading, hai bisogno del controllo programmatico sulle tue sottoscrizioni di avvisi X.
WALLAWHATS fornisce una REST API che ti permette di creare, gestire e auditare le sottoscrizioni agli avvisi X senza toccare l’interfaccia web. Aggiungi o rimuovi account monitorati, estrai cronologia notifiche con stato di consegna, e integra avvisi X in tempo reale in qualsiasi sistema che parli HTTP.
Perché Usare l’API WALLAWHATS?
Il dashboard funziona benissimo per flussi manuali, ma l’accesso API sblocca scenari di automazione che scalano oltre la gestione umana:
Piattaforme di Intelligence Clienti: Sottoscrivi automaticamente a dirigenti competitor appena identificati, responsabili prodotto, o analisti di settore man mano che vengono scoperti tramite strumenti di ricerca o integrazioni CRM.
Flussi Trading e Finanziari: Monitora programmaticamente account regolatorie, handle CEO, o giornalisti settore-specifici basati su cambiamenti portfolio o eventi di mercato—senza gestione manuale sottoscrizioni.
Monitoraggio Brand su Scala: Aggiungi o rimuovi tracking menzioni brand mentre nuove campagne lanciano, prodotti spediscono, o situazioni di crisi si sviluppano.
Applicazioni SaaS Multi-Tenant: Monitoraggio X in tempo reale white-label per i tuoi clienti, con gestione sottoscrizioni programmatica dietro le quinte.
Sistemi Compliance e Audit: Estrai cronologia completa notifiche con stato di consegna per report regolatori, trail audit interni, o monitoraggio SLA.
Autenticazione e Accesso API
Ogni piano WALLAWHATS include accesso API con quote chiavi scalabili:
- Free: 1 chiave API
- Pro: 1 chiave API
- Pro+: 2 chiavi API
- Business: 5 chiavi API
- Enterprise: 20 chiavi API
L’autenticazione usa l’header x-api-key (non Authorization: Bearer). Genera le tue chiavi dalla sezione API del dashboard, e trattale come password—hanno pieni privilegi account.
curl -H "x-api-key: your_api_key_here" \
https://api.wallawhats.com/subscriptionsEndpoint API Principali
L’API WALLAWHATS fornisce cinque gruppi di risorse principali per costruire integrazioni:
Gestione Sottoscrizioni
Crea una nuova sottoscrizione:
POST /subscriptions
Content-Type: application/json
x-api-key: your_api_key_here
{
"xUsername": "elonmusk"
}Elenca tutte le sottoscrizioni:
GET /subscriptions
x-api-key: your_api_key_hereRimuovi una sottoscrizione:
DELETE /subscriptions/elonmusk
x-api-key: your_api_key_hereNota che l’endpoint delete prende l’handle X come parametro path—non un ID sottoscrizione interno.
Cronologia Notifiche e Audit
Estrai cronologia notifiche con stato di consegna:
GET /notifications?from=1704067200000&to=1704153600000
x-api-key: your_api_key_hereL’endpoint notifications restituisce risultati paginati con ogni riga che rappresenta un avviso consegnato a un canale. I valori di stato includono:
queued: Avviso accettato, in attesa di consegnasent: Inviato al provider del canaledelivered: Confermato ricevuto dalla destinazioneread: Aperto dal destinatario (solo WhatsApp, richiede conferme di lettura abilitate)failed: Tentativo di consegna non riuscito
Gestione Canali
Elenca canali configurati:
GET /channels
x-api-key: your_api_key_hereAggiungi un nuovo canale:
POST /channels
Content-Type: application/json
x-api-key: your_api_key_here
{
"type": "email",
"destination": "alerts@yourcompany.com"
}Rimuovi un canale:
DELETE /channels/channel_id_here
x-api-key: your_api_key_hereScreenshot Tweet
Accedi alla galleria screenshot:
GET /snapshots
x-api-key: your_api_key_hereElimina uno screenshot specifico:
DELETE /snapshots/tweet_id_here
x-api-key: your_api_key_hereCostruire Integrazioni: Esempi Codice
Integrazione Node.js
Ecco un esempio Node.js che aggiunge una sottoscrizione e controlla per nuove notifiche:
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}`);
}
}
}
// Esempio d'uso
async function monitorCompetitor() {
const client = new WallaWhatsClient('your_api_key_here');
// Aggiungi una nuova sottoscrizione
await client.addSubscription('vercel');
console.log('Ora monitoriamo @vercel');
// Controlla notifiche recenti
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
const notifications = await client.getNotifications(oneDayAgo, Date.now());
console.log(`Trovati ${notifications.items.length} avvisi recenti`);
notifications.items.forEach(notification => {
console.log(`${notification.xUsername}: ${notification.status} alle ${notification.timestamp}`);
});
}Integrazione Python
Per flussi Python, ecco una classe che gestisce gestione sottoscrizioni e polling notifiche:
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):
"""Aggiungi un nuovo account X da monitorare"""
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):
"""Rimuovi un account X dal monitoraggio"""
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):
"""Recupera cronologia notifiche con paginazione"""
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):
"""Recupera tutte le notifiche in un intervallo di tempo, gestendo la paginazione"""
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):
"""Ottieni tutte le sottoscrizioni attuali"""
response = requests.get(
f'{self.base_url}/subscriptions',
headers=self.headers
)
response.raise_for_status()
return response.json()
# Esempio: Report audit giornaliero
def generate_daily_report():
api = WallaWhatsAPI('your_api_key_here')
# Ottieni notifiche di ieri
end_time = int(time.time() * 1000)
start_time = end_time - (24 * 60 * 60 * 1000)
notifications = api.get_all_notifications(start_time, end_time)
# Raggruppa per account e stato
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
# Stampa riassunto
print(f"Report Avvisi Giornaliero - {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']} avvisi, {success_rate:.1f}% consegnati")Comprendere il Routing Canali
WALLAWHATS usa un modello di routing canali globale—ogni avviso da ogni sottoscrizione viene distribuito a tutti i canali abilitati e verificati. Non puoi indirizzare account specifici a destinazioni specifiche via API (tipo “@elonmusk → WhatsApp, @vercel → email”).
La selezione canali avviene a livello account nella pagina Canali. Quando aggiungi un canale via API, diventa disponibile per tutti gli avvisi una volta verificato. Quando rimuovi un canale, smette di ricevere avvisi da tutte le sottoscrizioni.
Questo design semplifica l’automazione prevenendo la frammentazione degli avvisi. Il tuo codice di integrazione non deve tracciare regole di routing per-sottoscrizione—gestisci solo quali account monitorare e quali canali abilitare.
Limiti di Velocità e Caps di Velocità
WALLAWHATS implementa caps di velocità a livello utente per prevenire spam di avvisi durante periodi ad alta attività:
- Free: 2 avvisi/ora
- Pro: 5 avvisi/ora
- Pro+: 15 avvisi/ora
- Business: 30 avvisi/ora
- Enterprise: 100 avvisi/ora
Quando i caps di velocità vengono superati, tweet aggiuntivi vengono bufferizzati in messaggi digest e consegnati ogni 15 minuti. La tua integrazione API vedrà questi come record di notifica separati—uno per l’avviso immediato, e uno per ogni batch digest.
L’API stessa non impone limiti di velocità separati su gestione sottoscrizioni o query notifiche. Tuttavia, evita di martellare gli endpoint con richieste non necessarie—metti in cache le liste sottoscrizioni localmente e raggruppa query notifiche efficientemente.
Gestione Errori e Risoluzione Problemi
Pattern comuni di errori API e come gestirli:
Fallimenti autenticazione (401):
- Verifica che la tua chiave API sia corretta e non sia stata revocata
- Assicurati di usare l’header
x-api-key, nonAuthorization
Conflitti sottoscrizione (409):
- Account già monitorato: La sottoscrizione esiste, tratta come successo
- Account protetto/privato: WALLAWHATS li rifiuta per design
Limitazione velocità (429):
- Riprova con backoff esponenziale
- Controlla se ti stai avvicinando ai limiti piano su account monitorati
Problemi verifica canali:
- Nuovi canali richiedono verifica OTP prima di ricevere avvisi
- Canali aggiunti programmaticamente non funzioneranno finché l’utente completa la verifica
Monitorare e Allertare le Tue Integrazioni
Dato che WALLAWHATS diventa infrastruttura critica quando integrato in flussi business, monitora la salute della tua integrazione:
Rilevamento Deriva Sottoscrizioni:
// Controlla se sottoscrizioni attese sono ancora attive
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(`Sottoscrizioni mancanti: ${missing.join(', ')}`);
}
return missing;
}Monitoraggio Tasso Successo Consegna:
def check_delivery_health():
# Controlla ultime 6 ore
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:
# Avvisa il tuo team ops
print(f"ATTENZIONE: Tasso successo consegna sceso al {success_rate:.1f}%")
return success_ratePattern di Integrazione e Best Practice
Elaborazione Stile-Webhook: Mentre WALLAWHATS non fornisce webhook direttamente, puoi fare polling dell’endpoint notifications per nuovi avvisi e processarli in quasi-tempo-reale:
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') {
// Processa l'avviso - invia a Slack, aggiorna database, ecc.
await processAlert(notification);
}
}
localStorage.setItem('lastNotificationCheck', now);
}
// Polling ogni 30 secondi
setInterval(pollForNewAlerts, 30000);Gestione Sottoscrizioni Condizionali: Aggiungi o rimuovi dinamicamente sottoscrizioni basate su trigger esterni:
def update_competitor_monitoring(portfolio_companies):
"""Aggiorna monitoraggio X basato su portfolio attuale"""
current_subs = {s['xUsername'] for s in api.list_subscriptions()}
# Account che dovremmo monitorare
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'])
# Aggiungi sottoscrizioni mancanti
for account in target_accounts - current_subs:
try:
api.add_subscription(account)
print(f"Iniziato monitoraggio @{account}")
except Exception as e:
print(f"Fallito aggiungere @{account}: {e}")
# Rimuovi sottoscrizioni obsolete
for account in current_subs - target_accounts:
api.remove_subscription(account)
print(f"Fermato monitoraggio @{account}")L’API WALLAWHATS trasforma gli avvisi X in tempo reale da uno strumento dashboard manuale in un componente infrastruttura programmabile. Che tu stia costruendo flussi intelligence personalizzati, automatizzando monitoraggio brand, o creando servizi notifiche white-label, l’API fornisce il controllo e le capacità audit necessarie per integrazione in produzione.
Cerchi di espandere il monitoraggio oltre i competitor? Controlla la nostra guida su monitorare crypto Twitter per segnali mercato o scopri come i giornalisti usano WALLAWHATS per monitoraggio fonti in tempo reale.
Non perderti mai più un post importante. Crea un account gratuito — 1 numero WhatsApp, avvisi in tempo reale, nessuna carta di credito richiesta.
