· Nacho Coll · Guides · 9 min de leitura
API de Alertas do X: Subscrições Programáticas e Histórico de Notificações
Constrói integrações personalizadas sobre o WALLAWHATS. Adiciona e remove subscrições do X, encaminha alertas para canais, consulta histórico de notificações — tudo via REST.
Quando os alertas do X (Twitter) em tempo real se tornam críticos para o teu negócio, a gestão manual do painel de controlo atinge um limite. Seja a construir painéis de inteligência de cliente, automatizar fluxos de monitorização de marca, ou criar sistemas de notificação personalizados para equipas de trading, precisas de controlo programático sobre as tuas subscrições de alertas do X.
O WALLAWHATS oferece uma API REST que te permite criar, gerir e auditar subscrições de alertas do X sem tocar na interface web. Adiciona ou remove contas monitorizadas, consulta histórico de notificações com estado de entrega, e integra alertas do X em tempo real em qualquer sistema que fale HTTP.
Porquê Usar a API do WALLAWHATS?
O painel funciona muito bem para fluxos manuais, mas o acesso à API desbloqueia cenários de automação que escalam além da gestão humana:
Plataformas de Inteligência de Cliente: Subscreve automaticamente executivos da concorrência recém-identificados, líderes de produto, ou analistas da indústria conforme são descobertos através de ferramentas de investigação ou integrações CRM.
Fluxos de Trading e Financeiros: Monitoriza programaticamente contas regulamentares, perfis de CEOs, ou jornalistas específicos de sectores baseados em mudanças de portfólio ou eventos de mercado—sem gestão manual de subscrições.
Monitorização de Marca em Escala: Adiciona ou remove rastreamento de menções de marca conforme novas campanhas são lançadas, produtos são enviados, ou situações de crise se desenvolvem.
Aplicações SaaS Multi-inquilino: Monitorização do X em tempo real de marca própria para os teus clientes, com gestão programática de subscrições nos bastidores.
Sistemas de Conformidade e Auditoria: Consulta histórico completo de notificações com estado de entrega para relatórios regulamentares, trilhas de auditoria internas, ou monitorização de SLA.
Autenticação e Acesso à API
Todos os planos do WALLAWHATS incluem acesso à API com quotas de chaves escaláveis:
- Free: 1 chave API
- Pro: 1 chave API
- Pro+: 2 chaves API
- Business: 5 chaves API
- Enterprise: 20 chaves API
A autenticação usa o cabeçalho x-api-key (não Authorization: Bearer). Gera as tuas chaves na secção API do painel, e trata-as como palavras-passe—têm privilégios completos da conta.
curl -H "x-api-key: your_api_key_here" \
https://api.wallawhats.com/subscriptionsEndpoints Principais da API
A API do WALLAWHATS oferece cinco grupos principais de recursos para construir integrações:
Gestão de Subscrições
Criar uma nova subscrição:
POST /subscriptions
Content-Type: application/json
x-api-key: your_api_key_here
{
"xUsername": "elonmusk"
}Listar todas as subscrições:
GET /subscriptions
x-api-key: your_api_key_hereRemover uma subscrição:
DELETE /subscriptions/elonmusk
x-api-key: your_api_key_hereNota que o endpoint de eliminação usa o identificador do X como parâmetro de caminho—não um ID de subscrição interno.
Histórico de Notificações e Auditoria
Consultar histórico de notificações com estado de entrega:
GET /notifications?from=1704067200000&to=1704153600000
x-api-key: your_api_key_hereO endpoint de notificações retorna resultados paginados com cada linha representando um alerta entregue a um canal. Os valores de estado incluem:
queued: Alerta aceite, aguardando entregasent: Enviado para o fornecedor do canaldelivered: Confirmada a receção no destinoread: Aberto pelo destinatário (apenas WhatsApp, requer confirmações de leitura activadas)failed: Tentativa de entrega falhada
Gestão de Canais
Listar canais configurados:
GET /channels
x-api-key: your_api_key_hereAdicionar um novo canal:
POST /channels
Content-Type: application/json
x-api-key: your_api_key_here
{
"type": "email",
"destination": "alerts@yourcompany.com"
}Remover um canal:
DELETE /channels/channel_id_here
x-api-key: your_api_key_hereCapturas de Ecrã de Tweets
Aceder à galeria de capturas:
GET /snapshots
x-api-key: your_api_key_hereEliminar uma captura específica:
DELETE /snapshots/tweet_id_here
x-api-key: your_api_key_hereConstruir Integrações: Exemplos de Código
Integração Node.js
Aqui está um exemplo Node.js que adiciona uma subscrição e consulta novas notificações:
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}`);
}
}
}
// Exemplo de uso
async function monitorCompetitor() {
const client = new WallaWhatsClient('your_api_key_here');
// Adicionar uma nova subscrição
await client.addSubscription('vercel');
console.log('Agora a monitorizar @vercel');
// Verificar notificações recentes
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
const notifications = await client.getNotifications(oneDayAgo, Date.now());
console.log(`Encontrados ${notifications.items.length} alertas recentes`);
notifications.items.forEach(notification => {
console.log(`${notification.xUsername}: ${notification.status} às ${notification.timestamp}`);
});
}Integração Python
Para fluxos Python, aqui está uma classe que gere subscrições e consulta notificações:
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):
"""Adicionar uma nova conta do 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):
"""Remover uma conta do X da monitorização"""
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):
"""Consultar histórico de notificações com paginação"""
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):
"""Consultar todas as notificações num intervalo de tempo, gerindo paginação"""
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):
"""Obter todas as subscrições actuais"""
response = requests.get(
f'{self.base_url}/subscriptions',
headers=self.headers
)
response.raise_for_status()
return response.json()
# Exemplo: Relatório de auditoria diário
def generate_daily_report():
api = WallaWhatsAPI('your_api_key_here')
# Obter notificações de ontem
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 conta e 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 resumo
print(f"Relatório de Alertas Diário - {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}% entregues")Compreender o Encaminhamento de Canais
O WALLAWHATS usa um modelo global de encaminhamento de canais—cada alerta de cada subscrição é distribuído para todos os canais activados e verificados. Não podes encaminhar contas específicas para destinos específicos via API (como “@elonmusk → WhatsApp, @vercel → email”).
A selecção de canais acontece ao nível da conta na página Canais. Quando adicionas um canal via API, fica disponível para todos os alertas uma vez verificado. Quando removes um canal, deixa de receber alertas de todas as subscrições.
Este design simplifica a automação evitando fragmentação de alertas. O teu código de integração não precisa de rastrear regras de encaminhamento por subscrição—apenas gere quais contas monitorizar e quais canais activar.
Limites de Taxa e Limites de Velocidade
O WALLAWHATS implementa limites de velocidade por utilizador para prevenir spam de alertas durante períodos de alta actividade:
- Free: 2 alertas/hora
- Pro: 5 alertas/hora
- Pro+: 15 alertas/hora
- Business: 30 alertas/hora
- Enterprise: 100 alertas/hora
Quando os limites de velocidade são excedidos, tweets adicionais são agrupados em mensagens resumo e entregues a cada 15 minutos. A tua integração API verá estes como registos de notificação separados—um para o alerta imediato, e um para cada lote de resumo.
A API em si não impõe limites de taxa separados na gestão de subscrições ou consultas de notificações. No entanto, evita bombardear os endpoints com pedidos desnecessários—armazena listas de subscrições localmente em cache e agrupa consultas de notificações eficientemente.
Gestão de Erros e Resolução de Problemas
Padrões comuns de erros da API e como geri-los:
Falhas de autenticação (401):
- Verifica que a tua chave API está correcta e não foi revogada
- Assegura que estás a usar o cabeçalho
x-api-key, nãoAuthorization
Conflitos de subscrição (409):
- Conta já monitorizada: A subscrição existe, trata como sucesso
- Conta protegida/privada: O WALLAWHATS recusa-as por design
Limitação de taxa (429):
- Recua exponencialmente antes de tentar novamente
- Verifica se estás a aproximar-te dos limites do plano em contas monitorizadas
Problemas de verificação de canal:
- Novos canais requerem verificação OTP antes de receber alertas
- Canais adicionados programaticamente não funcionarão até o utilizador completar a verificação
Monitorizar e Alertar as Tuas Integrações
Como o WALLAWHATS se torna infraestrutura crítica quando integrado em fluxos de negócio, monitoriza a saúde da tua integração:
Detecção de Deriva de Subscrições:
// Verificar se subscrições esperadas ainda estão 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(`Subscrições em falta: ${missing.join(', ')}`);
}
return missing;
}Monitorização de Taxa de Sucesso 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 tua equipa de operações
print(f"AVISO: Taxa de sucesso de entrega desceu para {success_rate:.1f}%")
return success_ratePadrões de Integração e Melhores Práticas
Processamento Estilo Webhook: Embora o WALLAWHATS não forneça webhooks directamente, podes consultar o endpoint de notificações para novos alertas e processá-los em quase tempo 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 o alerta - enviar para Slack, actualizar base de dados, etc.
await processAlert(notification);
}
}
localStorage.setItem('lastNotificationCheck', now);
}
// Consultar a cada 30 segundos
setInterval(pollForNewAlerts, 30000);Gestão Condicional de Subscrições: Adiciona ou remove subscrições dinamicamente baseado em triggers externos:
def update_competitor_monitoring(portfolio_companies):
"""Actualizar monitorização do X baseada no portfólio actual"""
current_subs = {s['xUsername'] for s in api.list_subscriptions()}
# Contas que deveríamos estar a monitorizar
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'])
# Adicionar subscrições em falta
for account in target_accounts - current_subs:
try:
api.add_subscription(account)
print(f"Começou a monitorizar @{account}")
except Exception as e:
print(f"Falha ao adicionar @{account}: {e}")
# Remover subscrições desactualizadas
for account in current_subs - target_accounts:
api.remove_subscription(account)
print(f"Parou de monitorizar @{account}")A API do WALLAWHATS transforma alertas do X em tempo real de uma ferramenta manual de painel numa componente de infraestrutura programável. Seja a construir fluxos personalizados de inteligência, automatizar monitorização de marca, ou criar serviços de notificação de marca própria, a API oferece o controlo e capacidades de auditoria necessárias para integração em produção.
Procuras expandir a tua monitorização além de concorrentes? Consulta o nosso guia sobre monitorizar crypto Twitter para sinais de mercado ou aprende como jornalistas usam o WALLAWHATS para monitorização de fontes em tempo real.
Nunca percas um post importante novamente. Cria uma conta gratuita — 1 número WhatsApp, alertas em tempo real, sem cartão de crédito necessário.
