Control messages

Control messages keep a connection authenticated and report handle-management command results.

Open in chat

Reviewed against product code on September 2, 2026

Send auth_ping

Send { "op": "auth_ping" } when your application needs an authentication check. This is a client message, not a server event.

Authentication ping

json

{
  "op": "auth_ping"
}

control/auth_pong

A successful authentication check returns an empty data object.

Authentication pong

json

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

control/twitter_handles_result

Read every result row. Idempotent success and row failures can appear in one response.

Handle result type

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

Handle result event

json

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

Manage handles over WebSocket

Use the handle-management subprotocol to add or remove monitored accounts through a long-running backend socket, without a separate REST request.

Follow handles over 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);
  }
});