Twitter WebSocket API 快速开始

几分钟内连接 TweetStream 的实时 Twitter 流式替代方案

开始使用

使用 WebSocket 子协议进行认证。无需 HTTP 头或查询参数——创建连接时把 API Key 放进协议列表即可。

本快速开始展示如何用 WebSocket 实时流式推文。如果你在评估 Twitter 流式 API 替代方案，从这里开始。

连接详情

端点	`wss://ws.tweetstream.io/ws`
协议 1	`tweetstream.v1`
协议 2	`tweetstream.auth.token.YOUR_API_KEY`

快速开始示例

复制以下代码即可立即连接：

const API_KEY = 'YOUR_API_KEY'; // Get your key from the dashboard
const WS_URL = 'wss://ws.tweetstream.io/ws';

const protocols = [
  'tweetstream.v1',
  `tweetstream.auth.token.${API_KEY}`,
];

const ws = new WebSocket(WS_URL, protocols);

ws.onopen = () => {
  console.log('Connected to TweetStream!');
};

ws.onmessage = (event) => {
  const envelope = JSON.parse(event.data);

  if (envelope.t === 'tweet' && envelope.op === 'content') {
    const tweet = envelope.d;
    const author = tweet.author?.handle ?? tweet.author?.name ?? 'unknown';
    console.log(`[${author}] ${tweet.text}`);
  }
};

ws.onclose = () => {
  console.log('WebSocket closed');
};

ws.onerror = (error) => {
  console.error('WebSocket error', error);
};

生产示例

生产环境请加入重连处理：

const API_KEY = process.env.TWEETSTREAM_API_KEY ?? 'YOUR_API_KEY';
const WS_URL = 'wss://ws.tweetstream.io/ws';
const PROTOCOLS = ['tweetstream.v1', `tweetstream.auth.token.${API_KEY}`];

let ws: WebSocket | null = null;
let reconnectTimer: ReturnType<typeof setTimeout> | undefined;

function connect() {
  ws = new WebSocket(WS_URL, PROTOCOLS);

  ws.onopen = () => {
    console.log('Connected to TweetStream');
  };

  ws.onmessage = (event) => {
    const envelope = JSON.parse(event.data);

    if (envelope.t === 'tweet') {
      if (envelope.op === 'content') {
        const tweet = envelope.d;
        const author = tweet.author?.handle ?? tweet.author?.name ?? 'unknown';
        console.log(`[TWEET] ${author}: ${tweet.text}`);
      } else if (envelope.op === 'update') {
        const update = envelope.d;
        console.log(`[UPDATE] ${update.tweetId}`, update);
      }
      return;
    }

    if (envelope.t === 'control' && envelope.op === 'twitter_handles_result') {
      const payload = envelope.d;
      console.log('[HANDLES RESULT]', payload);
    }
  };

  ws.onclose = (event) => {
    console.warn('WebSocket closed', event.code, event.reason);
    scheduleReconnect();
  };

  ws.onerror = (error) => {
    console.error('WebSocket error', error);
    ws?.close();
  };
}

function scheduleReconnect() {
  if (reconnectTimer) return;
  reconnectTimer = setTimeout(() => {
    reconnectTimer = undefined;
    connect();
  }, 5_000);
}

connect();

封装格式

所有消息都使用一致的封装结构：

v - 协议版本（始终为 1）
t - 消息类型：tweet 或 control
op - 操作：content、meta、update
ts - 毫秒级 Unix 时间戳
d - 载荷数据（随类型与操作变化）

常见问题

认证失败：确认 API Key 来自有效订阅
连接数已达上限：关闭现有连接或升级套餐
没有收到推文：确认已在控制台跟踪账号

立即开启实时 Twitter WebSocket 提醒

内置 WebSocket 交付、OCR 与代币检测的 Twitter API 替代方案。

开始 1 天试用

起价 $199/月 · 含 1 天试用 · OCR + 代币检测