---
title: "控制消息"
canonical_url: "https://tweetstream.io/zh-cn/docs/control"
last_updated: 2026-09-24
---

# 控制消息

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

Canonical URL: https://tweetstream.io/zh-cn/docs/control

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