Getting started

// 1. on connect — handshake with your current subscriptions
{ "type": "connected", "subscribed": ["elonmusk", "vitalikbuterin"] }

// 2. a live post (NO "type" field; identified by tweet_id)
{ "kol": "elonmusk", "tweet_id": "1929...", "user": "elonmusk",
  "display_name": "Elon Musk", "content": "...", "url": "https://x.com/...",
  "like_count": 1203, "retweet_count": 88, "reply_count": 42,
  "view_count": 90512, "is_retweet": false, "is_reply": false }

// 3. backpressure notice (stream too fast; N messages dropped — you stay connected)
{ "type": "lagged", "dropped": 17 }

import WebSocket from "ws";   // npm i ws

function connect() {
  const ws = new WebSocket("wss://socialapi.tech/v1/stream/ws?api_key=YOUR_API_KEY");

  ws.on("open", () => console.log("connected"));
  ws.on("message", (raw) => {
    const msg = JSON.parse(raw.toString());
    if (msg.type === "connected") return;      // handshake
    if (msg.type === "lagged") return;         // server dropped N on backpressure
    // else: a live post from an account you subscribed to
    console.log("@" + msg.user, "→", msg.content);
  });
  ws.on("error", (e) => console.error("ws error:", e.message));
  // auto-reconnect on drop
  ws.on("close", () => setTimeout(connect, 1000));
}

connect();

import json, websocket   # pip install websocket-client

def on_message(ws, raw):
    msg = json.loads(raw)
    if msg.get("type"):                       # connected / lagged control frames
        return
    print("@" + msg["user"], "→", msg["content"])

ws = websocket.WebSocketApp(
    "wss://socialapi.tech/v1/stream/ws?api_key=YOUR_API_KEY",
    on_message=on_message,
)
ws.run_forever(ping_interval=30, reconnect=5)  # keep-alive + auto-reconnect

# websocat (github.com/vi/websocat) — quick test from the shell
websocat "wss://socialapi.tech/v1/stream/ws?api_key=YOUR_API_KEY"