Twitter WebSocket API Quickstart

Connect to TweetStream's real-time Twitter streaming API alternative in minutes

Getting Started

Authenticate via WebSocket subprotocols—include your API key in the protocol list when opening the connection. No HTTP headers or query strings required.

Stream tweets in real time via WebSocket. Evaluating Twitter API alternatives? Start here.

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

Start real-time Twitter WebSocket alerts today

WebSocket delivery, OCR, and token detection—no infrastructure to build.

Start 1-Day Trial

From $199/mo · 1-day trial included · OCR + token detection included

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