---
title: "WebSocket quickstart"
canonical_url: "https://tweetstream.io/docs/quickstart"
last_updated: 2026-09-24
---

# WebSocket quickstart

Add one monitored account, open a server-side WebSocket, and print each v1 envelope.

Canonical URL: https://tweetstream.io/docs/quickstart

## Run a 5-minute smoke test

Add one monitored account, copy the example, and run it. `TweetStream connected` confirms authentication. Events appear when that account posts.

### Run the TypeScript smoke test

```typescript
// bun add ws
// TWEETSTREAM_API_KEY=ts_... bun run smoke.ts
import WebSocket from "ws";

const apiKey = process.env.TWEETSTREAM_API_KEY;
if (!apiKey) {
  throw new Error("Missing TWEETSTREAM_API_KEY");
}

const ws = new WebSocket("wss://ws-global.tweetstream.io/ws", [
  "tweetstream.v1",
  `tweetstream.auth.token.${apiKey}`,
]);

ws.on("open", () => {
  console.log("TweetStream connected");
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  console.log(event.t, event.op, event.d);
});

ws.on("close", (code, reason) => {
  console.log("TweetStream closed", code, reason.toString());
});

ws.on("unexpected-response", (_request, response) => {
  console.error(
    "Connection rejected",
    response.statusCode,
    response.statusMessage,
  );
  response.resume();
  process.exitCode = 1;
});

ws.on("error", (error) => {
  console.error("WebSocket error", error.message);
});
```

## Route operations

Each event names its family in `t` and its operation in `op`. The delivery reference lists all 18 server operations.

- [All operations](https://tweetstream.io/docs/envelope-delivery-recovery-errors#operations): Family, operation, and meaning for every server event.

## Make it durable

- [Connection details](https://tweetstream.io/docs/connection-auth-heartbeat): Choose an endpoint and understand authentication and heartbeat behavior.
- [Production consumer](https://tweetstream.io/docs/production-consumer): Add reconnects, event routing, and recovery checkpoints.