· Nacho Coll · Guides  · 13 分钟阅读

X 提醒 API：程序化订阅管理和通知历史

在 WALLAWHATS 基础上构建自定义集成。添加和删除 X 订阅，将提醒路由到频道，获取通知历史——全部通过 REST API 实现。

在 WALLAWHATS 基础上构建自定义集成。添加和删除 X 订阅，将提醒路由到频道，获取通知历史——全部通过 REST API 实现。

当实时 X (Twitter) 提醒成为你业务的关键组件时，手动仪表板管理会遇到瓶颈。无论你是在构建客户情报仪表板、自动化品牌监控工作流，还是为交易台创建自定义通知系统，你都需要对 X 提醒订阅进行程序化控制。

WALLAWHATS 提供 REST API，让你能够创建、管理和审计 X 提醒订阅，无需接触网页界面。添加或删除监控账户、获取带投递状态的通知历史，并将实时 X 提醒集成到任何支持 HTTP 的系统中。

API keys management page with create / revoke controls

为什么使用 WALLAWHATS API？

仪表板对于手动工作流程很好用，但 API 访问解锁了超出人工管理规模的自动化场景：

客户情报平台：自动订阅通过研究工具或 CRM 集成新发现的竞争对手高管、产品负责人或行业分析师。

交易和金融工作流：根据投资组合变化或市场事件，程序化监控监管账户、CEO 账号或特定行业记者——无需手动订阅管理。

大规模品牌监控：随着新活动启动、产品发布或危机情况发展，添加或删除品牌提及追踪。

多租户 SaaS 应用程序：为你的客户提供白标实时 X 监控，后台进行程序化订阅管理。

合规和审计系统：获取包含投递状态的完整通知历史，用于监管报告、内部审计跟踪或 SLA 监控。

API 身份验证和访问

每个 WALLAWHATS 计划都包含 API 访问权限，具有不同的密钥配额：

  • Free：1 个 API 密钥
  • Pro：1 个 API 密钥
  • Pro+：2 个 API 密钥
  • Business：5 个 API 密钥
  • Enterprise：20 个 API 密钥

身份验证使用 x-api-key 标头（不是 Authorization: Bearer）。从仪表板的 API 部分生成你的密钥，并像密码一样对待它们——它们拥有完整的账户权限。

curl -H "x-api-key: your_api_key_here" \
     https://api.wallawhats.com/subscriptions

核心 API 端点

WALLAWHATS API 提供五个主要资源组用于构建集成：

订阅管理

创建新订阅：

POST /subscriptions
Content-Type: application/json
x-api-key: your_api_key_here

{
  "xUsername": "elonmusk"
}

列出所有订阅：

GET /subscriptions
x-api-key: your_api_key_here

删除订阅：

DELETE /subscriptions/elonmusk
x-api-key: your_api_key_here

注意删除端点使用 X 用户名作为路径参数——不是内部订阅 ID。

通知历史和审计

获取带投递状态的通知历史：

GET /notifications?from=1704067200000&to=1704153600000
x-api-key: your_api_key_here

通知端点返回分页结果，每行代表向一个频道投递的一个提醒。状态值包括：

  • queued：提醒已接受，等待投递
  • sent：已调度到频道提供商
  • delivered：目标已确认接收
  • read：收件人已打开（仅 WhatsApp，需要启用已读回执）
  • failed：投递尝试不成功

频道管理

列出已配置的频道：

GET /channels
x-api-key: your_api_key_here

添加新频道：

POST /channels
Content-Type: application/json
x-api-key: your_api_key_here

{
  "type": "email",
  "destination": "alerts@yourcompany.com"
}

删除频道：

DELETE /channels/channel_id_here
x-api-key: your_api_key_here

推文快照

访问快照图库：

GET /snapshots
x-api-key: your_api_key_here

删除特定快照：

DELETE /snapshots/tweet_id_here
x-api-key: your_api_key_here

构建集成：代码示例

Node.js 集成

这是一个 Node.js 示例，添加订阅并轮询新通知：

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}`);
    }
  }
}

// 使用示例
async function monitorCompetitor() {
  const client = new WallaWhatsClient('your_api_key_here');
  
  // 添加新订阅
  await client.addSubscription('vercel');
  console.log('现在监控 @vercel');
  
  // 检查最近的通知
  const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
  const notifications = await client.getNotifications(oneDayAgo, Date.now());
  
  console.log(`发现 ${notifications.items.length} 个最近提醒`);
  notifications.items.forEach(notification => {
    console.log(`${notification.xUsername}: ${notification.status} at ${notification.timestamp}`);
  });
}

Python 集成

对于 Python 工作流，这是一个处理订阅管理和通知轮询的类：

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):
        """添加新的 X 账户进行监控"""
        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):
        """从监控中删除 X 账户"""
        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):
        """获取带分页的通知历史"""
        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):
        """获取时间范围内的所有通知，处理分页"""
        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):
        """获取所有当前订阅"""
        response = requests.get(
            f'{self.base_url}/subscriptions',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# 示例：每日审计报告
def generate_daily_report():
    api = WallaWhatsAPI('your_api_key_here')
    
    # 获取昨天的通知
    end_time = int(time.time() * 1000)
    start_time = end_time - (24 * 60 * 60 * 1000)
    
    notifications = api.get_all_notifications(start_time, end_time)
    
    # 按账户和状态分组
    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
    
    # 打印摘要
    print(f"每日提醒报告 - {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']} 个提醒，{success_rate:.1f}% 已投递")

理解频道路由

WALLAWHATS 使用全局频道路由模型——每个订阅的每个提醒都会扇出到所有启用和验证的频道。你不能通过 API 将特定账户路由到特定目标（如”@elonmusk → WhatsApp，@vercel → 电子邮件”）。

频道选择在频道页面的账户级别进行。当你通过 API 添加频道时，一旦验证就对所有提醒可用。当你删除频道时，它会停止接收来自所有订阅的提醒。

这种设计简化了自动化，同时防止提醒碎片化。你的集成代码不需要追踪每订阅路由规则——只需管理要监控的账户和要启用的频道。

速率限制和速度上限

WALLAWHATS 实施用户级速度上限，以防止高活动期间的提醒垃圾：

  • Free：2 次提醒/小时
  • Pro：5 次提醒/小时
  • Pro+：15 次提醒/小时
  • Business：30 次提醒/小时
  • Enterprise：100 次提醒/小时

当超过速度上限时，额外的推文会缓冲到摘要消息中，每 15 分钟投递一次。你的 API 集成会将这些视为单独的通知记录——一个用于即时提醒，一个用于每个摘要批次。

API 本身不会对订阅管理或通知查询施加单独的速率限制。但是，避免用不必要的请求轰炸端点——在本地缓存订阅列表并高效批处理通知查询。

错误处理和故障排除

常见的 API 错误模式及其处理方法：

身份验证失败 (401)：

  • 验证你的 API 密钥是否正确且未被撤销
  • 确保你使用的是 x-api-key 标头，而不是 Authorization

订阅冲突 (409)：

  • 账户已被监控：订阅存在，视为成功
  • 账户受保护/私有：WALLAWHATS 按设计拒绝这些

速率限制 (429)：

  • 指数退避后重试
  • 检查是否接近监控账户的计划限制

频道验证问题：

  • 新频道需要 OTP 验证才能接收提醒
  • 程序化添加的频道在用户完成验证前不会工作

监控和提醒你的集成

由于 WALLAWHATS 在集成到业务工作流程时成为关键基础设施，监控你的集成健康状况：

订阅漂移检测：

// 检查预期的订阅是否仍然活跃
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(`缺失订阅：${missing.join(', ')}`);
  }
  
  return missing;
}

投递成功率监控：

def check_delivery_health():
    # 检查过去 6 小时
    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:
        # 提醒你的运维团队
        print(f"警告：投递成功率下降到 {success_rate:.1f}%")
    
    return success_rate

集成模式和最佳实践

Webhook 风格处理：虽然 WALLAWHATS 不直接提供 webhooks，但你可以轮询通知端点获取新提醒并进行近实时处理：

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') {
      // 处理提醒 - 发送到 Slack、更新数据库等
      await processAlert(notification);
    }
  }
  
  localStorage.setItem('lastNotificationCheck', now);
}

// 每 30 秒轮询一次
setInterval(pollForNewAlerts, 30000);

条件订阅管理：根据外部触发器动态添加或删除订阅：

def update_competitor_monitoring(portfolio_companies):
    """根据当前投资组合更新 X 监控"""
    current_subs = {s['xUsername'] for s in api.list_subscriptions()}
    
    # 我们应该监控的账户
    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'])
    
    # 添加缺失的订阅
    for account in target_accounts - current_subs:
        try:
            api.add_subscription(account)
            print(f"开始监控 @{account}")
        except Exception as e:
            print(f"添加 @{account} 失败：{e}")
    
    # 删除过时的订阅
    for account in current_subs - target_accounts:
        api.remove_subscription(account)
        print(f"停止监控 @{account}")

WALLAWHATS API 将实时 X 提醒从手动仪表板工具转变为可编程的基础设施组件。无论你是在构建自定义情报工作流、自动化品牌监控，还是创建白标通知服务，API 都提供生产集成所需的控制和审计能力。

希望将你的监控范围扩展到竞争对手之外？查看我们关于监控加密货币 Twitter 获取市场信号的指南，或了解记者如何使用 WALLAWHATS 进行实时信源监控。

再也不会错过重要的帖子。创建免费账户——1 个 WhatsApp 号码，实时提醒，无需信用卡。

Share:
返回博客

相关文章

查看所有文章 »