· Nacho Coll · Guides · 9 min de leitura
API de Alertas do X: Assinaturas Programáticas e Histórico de Notificações
Construa integrações personalizadas em cima do WALLAWHATS. Adicione e remova assinaturas do X, roteie alertas para canais, puxe histórico de notificações — tudo via REST.
Quando alertas do X (Twitter) em tempo real se tornam mission-critical para seu negócio, gerenciar manualmente pelo painel atinge um limite. Seja construindo dashboards de inteligência de clientes, automatizando workflows de monitoramento de marca, ou criando sistemas de notificação personalizados para mesas de operação, você precisa de controle programático sobre suas assinaturas de alertas do X.
O WALLAWHATS fornece uma API REST que permite criar, gerenciar e auditar assinaturas de alertas do X sem tocar na interface web. Adicione ou remova contas monitoradas, puxe histórico de notificações com status de entrega, e integre alertas do X em tempo real em qualquer sistema que fale HTTP.
Por Que Usar a API do WALLAWHATS?
O painel funciona muito bem para workflows manuais, mas o acesso via API libera cenários de automação que escalam além do gerenciamento humano:
Plataformas de Inteligência de Clientes: Automaticamente assine executivos concorrentes recém-identificados, líderes de produto ou analistas da indústria conforme são descobertos através de ferramentas de pesquisa ou integrações CRM.
Workflows de Trading e Financeiros: Monitore programaticamente contas regulatórias, handles de CEOs ou jornalistas específicos de setores baseado em mudanças de portfólio ou eventos de mercado—sem gerenciamento manual de assinaturas.
Monitoramento de Marca em Escala: Adicione ou remova rastreamento de menções à marca conforme novas campanhas são lançadas, produtos são enviados ou situações de crise se desenvolvem.
Aplicações SaaS Multi-Tenant: Monitoramento do X em tempo real com marca própria para seus clientes, com gerenciamento programático de assinaturas nos bastidores.
Sistemas de Compliance e Auditoria: Puxe histórico completo de notificações com status de entrega para relatórios regulatórios, trilhas de auditoria internas ou monitoramento de SLA.
Autenticação e Acesso à API
Cada plano do WALLAWHATS inclui acesso à API com cotas de chaves escaloná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 header x-api-key (não Authorization: Bearer). Gere suas chaves na seção API do painel, e trate-as como senhas—elas carregam todos os privilégios da conta.
curl -H "x-api-key: sua_chave_api_aqui" \
https://api.wallawhats.com/subscriptionsEndpoints Principais da API
A API do WALLAWHATS fornece cinco grupos principais de recursos para construir integrações:
Gerenciamento de Assinaturas
Criar uma nova assinatura:
POST /subscriptions
Content-Type: application/json
x-api-key: sua_chave_api_aqui
{
"xUsername": "elonmusk"
}Listar todas as assinaturas:
GET /subscriptions
x-api-key: sua_chave_api_aquiRemover uma assinatura:
DELETE /subscriptions/elonmusk
x-api-key: sua_chave_api_aquiNote que o endpoint de delete recebe o handle do X como parâmetro de path—não um ID interno de assinatura.
Histórico de Notificações e Auditoria
Puxar histórico de notificações com status de entrega:
GET /notifications?from=1704067200000&to=1704153600000
x-api-key: sua_chave_api_aquiO endpoint de notificações retorna resultados paginados com cada linha representando um alerta entregue a um canal. Os valores de status incluem:
queued: Alerta aceito, aguardando entregasent: Despachado para o provedor do canaldelivered: Confirmado como recebido pelo destinoread: Aberto pelo destinatário (apenas WhatsApp, requer confirmações de leitura habilitadas)failed: Tentativa de entrega malsucedida
Gerenciamento de Canais
Listar canais configurados:
GET /channels
x-api-key: sua_chave_api_aquiAdicionar um novo canal:
POST /channels
Content-Type: application/json
x-api-key: sua_chave_api_aqui
{
"type": "email",
"destination": "alerts@suaempresa.com"
}Remover um canal:
DELETE /channels/id_do_canal_aqui
x-api-key: sua_chave_api_aquiSnapshots de Tweets
Acessar a galeria de snapshots:
GET /snapshots
x-api-key: sua_chave_api_aquiDeletar um snapshot específico:
DELETE /snapshots/id_do_tweet_aqui
x-api-key: sua_chave_api_aquiConstruindo Integrações: Exemplos de Código
Integração Node.js
Aqui está um exemplo Node.js que adiciona uma assinatura e busca 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(`Falha ao adicionar assinatura: ${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(`Falha ao buscar notificações: ${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(`Falha ao listar assinaturas: ${error.response?.data?.message || error.message}`);
}
}
}
// Exemplo de uso
async function monitorCompetitor() {
const client = new WallaWhatsClient('sua_chave_api_aqui');
// Adicionar uma nova assinatura
await client.addSubscription('vercel');
console.log('Agora monitorando @vercel');
// Verificar notificações recentes
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
const notifications = await client.getNotifications(oneDayAgo, Date.now());
console.log(`Encontradas ${notifications.items.length} alertas recentes`);
notifications.items.forEach(notification => {
console.log(`${notification.xUsername}: ${notification.status} em ${notification.timestamp}`);
});
}Integração Python
Para workflows Python, aqui está uma classe que lida com gerenciamento de assinaturas e busca de 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 monitorar"""
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 do monitoramento"""
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):
"""Buscar 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):
"""Buscar todas as notificações em um intervalo de tempo, lidando com 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 assinaturas atuais"""
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('sua_chave_api_aqui')
# 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 status
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 Diário 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}% entregues")Entendendo o Roteamento de Canais
O WALLAWHATS usa um modelo de roteamento de canal global—cada alerta de cada assinatura é distribuído para todos os canais habilitados e verificados. Você não pode rotear contas específicas para destinos específicos via API (como “@elonmusk → WhatsApp, @vercel → email”).
A seleção de canais acontece no nível da conta na página Canais. Quando você adiciona um canal via API, ele se torna disponível para todos os alertas uma vez verificado. Quando você remove um canal, ele para de receber alertas de todas as assinaturas.
Este design simplifica a automação enquanto previne fragmentação de alertas. Seu código de integração não precisa rastrear regras de roteamento por assinatura—apenas gerencie quais contas monitorar e quais canais habilitar.
Limites de Taxa e Caps de Velocidade
O WALLAWHATS implementa caps de velocidade no nível do usuário para prevenir spam de alertas durante períodos de alta atividade:
- Free: 2 alertas/hora
- Pro: 5 alertas/hora
- Pro+: 15 alertas/hora
- Business: 30 alertas/hora
- Enterprise: 100 alertas/hora
Quando os caps de velocidade são excedidos, tweets adicionais são agrupados em mensagens digest e entregues a cada 15 minutos. Sua integração API verá estes como registros de notificação separados—um para o alerta imediato, e um para cada lote digest.
A própria API não impõe limites de taxa separados no gerenciamento de assinaturas ou consultas de notificações. No entanto, evite bombardear os endpoints com requisições desnecessárias—faça cache de listas de assinaturas localmente e agrupe consultas de notificações de forma eficiente.
Tratamento de Erros e Solução de Problemas
Padrões comuns de erros da API e como lidar com eles:
Falhas de autenticação (401):
- Verifique se sua chave API está correta e não foi revogada
- Garanta que você está usando o header
x-api-key, nãoAuthorization
Conflitos de assinatura (409):
- Conta já monitorada: A assinatura existe, trate como sucesso
- Conta protegida/privada: WALLAWHATS recusa estas por design
Limitação de taxa (429):
- Use backoff exponencial antes de tentar novamente
- Verifique se você está se aproximando dos limites do plano em contas monitoradas
Problemas de verificação de canal:
- Novos canais requerem verificação OTP antes de receber alertas
- Canais adicionados programaticamente não funcionarão até que o usuário complete a verificação
Monitoramento e Alertas de Suas Integrações
Já que o WALLAWHATS se torna infraestrutura crítica quando integrado em workflows de negócio, monitore a saúde da sua integração:
Detecção de Deriva de Assinaturas:
// Verificar se assinaturas esperadas ainda estão ativas
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(`Assinaturas faltando: ${missing.join(', ')}`);
}
return missing;
}Monitoramento 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 sua equipe de ops
print(f"AVISO: Taxa de sucesso de entrega caiu 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 diretamente, você pode buscar 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, atualizar banco de dados, etc.
await processAlert(notification);
}
}
localStorage.setItem('lastNotificationCheck', now);
}
// Buscar a cada 30 segundos
setInterval(pollForNewAlerts, 30000);Gerenciamento Condicional de Assinaturas: Adicione ou remova dinamicamente assinaturas baseado em gatilhos externos:
def update_competitor_monitoring(portfolio_companies):
"""Atualizar monitoramento do X baseado no portfólio atual"""
current_subs = {s['xUsername'] for s in api.list_subscriptions()}
# Contas que deveríamos estar monitorando
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 assinaturas faltando
for account in target_accounts - current_subs:
try:
api.add_subscription(account)
print(f"Começou a monitorar @{account}")
except Exception as e:
print(f"Falha ao adicionar @{account}: {e}")
# Remover assinaturas desatualizadas
for account in current_subs - target_accounts:
api.remove_subscription(account)
print(f"Parou de monitorar @{account}")A API do WALLAWHATS transforma alertas do X em tempo real de uma ferramenta de painel manual em um componente de infraestrutura programável. Seja construindo workflows de inteligência personalizados, automatizando monitoramento de marca ou criando serviços de notificação com marca própria, a API fornece as capacidades de controle e auditoria necessárias para integração em produção.
Quer expandir seu monitoramento além de concorrentes? Confira nosso guia sobre monitoramento do Twitter cripto para sinais de mercado ou aprenda como jornalistas usam o WALLAWHATS para monitoramento de fontes em tempo real.
Nunca perca um post importante novamente. Crie uma conta gratuita — 1 número WhatsApp, alertas em tempo real, sem cartão de crédito necessário.
