控制消息

控制消息用于检查连接认证并返回账号管理命令结果。

运行五分钟快速开始

在聊天中打开

ChatGPT Claude Cursor

按产品代码校对：2026年9月2日

发送 auth_ping

应用需要检查认证时，发送 { "op": "auth_ping" }。这是客户端消息，不是服务端事件。

认证 ping

json

{
  "op": "auth_ping"
}

control/auth_pong

认证检查成功时，会返回空的 data 对象。

认证 pong

json

{
  "v": 1,
  "t": "control",
  "op": "auth_pong",
  "ts": 1772000001060,
  "d": {}
}

control/twitter_handles_result

读取每一行结果。同一响应中可能同时包含幂等成功和逐行失败。

账号处理结果类型

typescript

type TwitterHandlesResult = {
  action: 'follow' | 'unfollow';
  requestId: string | null;
  results: Array<{
    input: string;
    state:
      | 'added'
      | 'already_following'
      | 'invalid_input'
      | 'duplicate'
      | 'not_found'
      | 'failed'
      | 'removed'
      | 'not_following';
    message?: string;
  }>;
  error: string | null;
};

账号处理结果事件

json

{
  "v": 1,
  "t": "control",
  "op": "twitter_handles_result",
  "ts": 1772000001060,
  "d": {
    "action": "follow",
    "error": null,
    "requestId": "req-1",
    "results": [
      {
        "input": "@one",
        "state": "added"
      }
    ]
  }
}

通过 WebSocket 管理账号

长期运行的后端连接可使用账号管理子协议添加或移除监控账号，无需另发 REST 请求。

通过 WebSocket 关注账号

typescript

import WebSocket from "ws";
 
type HandleManagementEvent = {
  t?: string;
  op?: string;
  d?: {
    error?: string | null;
    results?: Array<{ input: string; state: string }>;
  };
};
 
const ws = new WebSocket("wss://ws-global.tweetstream.io/ws", [
  "tweetstream.handle-management",
  `tweetstream.auth.token.${process.env.TWEETSTREAM_API_KEY}`,
]);
 
ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "twitter_handles",
    action: "follow",
    handles: ["marketdesk", "realDonaldTrump"],
    requestId: crypto.randomUUID(),
  }));
});
 
ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString()) as HandleManagementEvent;
  if (event.t === "control" && event.op === "twitter_handles_result") {
    console.log(event.d?.results, event.d?.error);
  }
});