Skip to main content
This guide covers what you need to build a production-ready WebSocket integration. For message types and parameters, see the WebSocket protocol reference. Prerequisites:

​
Best Practices

Items 1 and 2 are required for any production integration. Items 3-6 improve quality and resilience.

​
1. Connection Management

Implement Reconnection Logic: 
class ResilientWebSocket {
  constructor(url) {
    this.url = url;
    this.backoff = 1000;
    this.maxBackoff = 30000;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url);

    this.ws.onclose = () => {
      console.log(`Reconnecting in ${this.backoff}ms`);
      setTimeout(() => this.connect(), this.backoff);
      this.backoff = Math.min(this.backoff * 2, this.maxBackoff);
    };

    this.ws.onopen = () => {
      console.log("Connected");
      this.backoff = 1000; // Reset backoff on successful connection
    };
  }
}

​
2. Error Handling

Always handle errors gracefully: 
ws.onerror = (error) => {
  console.error("WebSocket error:", error);
  // Notify user, attempt recovery
};

ws.onmessage = (event) => {
  if (typeof event.data === "string") {
    const message = JSON.parse(event.data);
    if (message.type === "error") {
      handleServerError(message.code, message.message);
    }
  }
};

​
3. Buffer Management (TTS)

Use flush strategically to control latency vs. quality: 
// For low latency: flush after each sentence
ws.send(JSON.stringify({ type: "text", text: sentence }));
ws.send(JSON.stringify({ type: "flush" }));

// For better quality: batch multiple sentences
ws.send(JSON.stringify({ type: "text", text: paragraph }));
// ... send more text ...
ws.send(JSON.stringify({ type: "flush" })); // Flush at the end

​
4. Audio Format Consistency

Ensure your audio format matches configuration: 
// Configuration
{
  encoding: 'linear16',    // 16-bit PCM
  sample_rate: 16000       // 16kHz
}

// Audio capture must match:
// - 16-bit samples
// - 16000 Hz sample rate
// - Single channel (mono)

​
5. Heartbeat/Keep-Alive

Send keep-alive messages to prevent idle disconnection. For STT sessions, use the built-in keepalive message type. For TTS, use a WebSocket ping frame: 
// STT: use the protocol-level keepalive message
let keepaliveInterval = setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: "keepalive" }));
  }
}, 10000); // Every 10 seconds

ws.onclose = () => {
  clearInterval(keepaliveInterval);
};

​
6. Interruption Handling (TTS)

SLNG Voice Agents handle interruptions automatically via enable_interruptions. This only applies if you manage TTS WebSocket connections yourself.
When building your own voice agent, stop TTS output as soon as the user starts speaking:
  • Send { "type": "close" } to stop server-side generation and end the session
  • Send { "type": "clear" } to discard queued audio (keeps the session open)
  • Clear your local audio buffer and stop playback
For complete patterns (immediate interrupt, clear-and-restart, fade-out, voice agent loop), see TTS WebSocket examples.

​
Troubleshooting

For WebSocket error codes and fixes for connection drops, choppy audio, delayed transcriptions, and authentication failures, see Error Codes & Troubleshooting.

​
Next Steps

WebSocket protocol

Message types, parameters, and connection URLs

Protocol comparison

HTTP vs. WebSocket: when to use each

TTS examples

JavaScript and Python code for real-time TTS

STT examples

JavaScript and Python code for real-time STT