WebSocket Quickstart Guide

Connect to TweetStream's real-time Twitter alert stream in minutes

Getting Started

Connect to TweetStream using WebSocket subprotocols for authentication. No HTTP headers or query strings needed - just include your API key in the protocol list when creating the connection.

Connection Details

Endpoint	`wss://ws.tweetstream.io/ws`
Protocol 1	`tweetstream.v1`
Protocol 2	`tweetstream.auth.token.YOUR_API_KEY`

Quick Start Example

Copy and paste this code to get connected immediately:

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

Production Example

For production use, add reconnection handling:

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();

Envelope Format

All messages use a consistent envelope structure:

v - Protocol version (always 1)
t - Message type: tweet or control
op - Operation: content, meta, update, delete
ts - Unix timestamp in milliseconds
d - Payload data (varies by type and operation)

Common Issues

Authentication failed: Verify your API key is from an active subscription
Connection limit reached: Close existing connections or upgrade your plan
No tweets appearing: Check that accounts are tracked in your dashboard

Ready to get started?

Try TweetStream free for 1 day. No commitment required.

Start 1-Day Trial

Payloads, Detections & OCR WebSocket for Trading Bots TweetStream vs Twitter API