WebSocket API Connection

Connect directly to NextEVI’s WebSocket API for maximum control and platform flexibility. This guide covers establishing connections, authentication, and basic message handling.

Quick Start

const ws = new WebSocket(
  `wss://api.nextevi.com/ws/voice/${connectionId}?api_key=oak_your_api_key&config_id=your_config_id`
);

ws.onopen = () => {
  console.log('Connected to NextEVI');
  
  // Configure session
  ws.send(JSON.stringify({
    type: "session_settings",
    timestamp: Date.now() / 1000,
    message_id: "settings-1",
    data: {
      emotion_detection: { enabled: true },
      turn_detection: { enabled: true, silence_threshold: 0.5 },
      audio: { sample_rate: 24000, channels: 1, encoding: "linear16" }
    }
  }));
};

WebSocket URL

wss://api.nextevi.com/ws/voice/{connection_id}

connection_id

string

required

Unique connection identifier. Generate a UUID v4 for each new connection.

Authentication Methods

API Key (Recommended)
JWT Token (Header)
JWT Token (Query Parameter)

Pass your organization API key as a query parameter:

wss://api.nextevi.com/ws/voice/{connection_id}?api_key=oak_your_api_key&config_id=your_config_id

Required Parameters:

api_key - Your organization API key (starts with oak_)
config_id - Voice configuration identifier
project_id - Project identifier (optional, auto-detected from config if not provided)

Pass JWT token via Authorization header (recommended for client applications):

Authorization: Bearer your_jwt_token

wss://api.nextevi.com/ws/voice/{connection_id}?config_id=your_config_id

Pass JWT token as query parameter (browser-compatible):

wss://api.nextevi.com/ws/voice/{connection_id}?authorization=Bearer%20your_jwt_token&config_id=your_config_id

Connection Examples

const connectionId = 'conn-' + Math.random().toString(36).substr(2, 9);

const ws = new WebSocket(
  `wss://api.nextevi.com/ws/voice/${connectionId}?api_key=oak_your_api_key&config_id=your_config_id`
);

ws.onopen = () => {
  console.log('Connected to NextEVI');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = (event) => {
  console.log('Disconnected:', event.code, event.reason);
};

Platform-Specific Examples

Browser
Node.js
Python
cURL (Testing)

const ws = new WebSocket('wss://api.nextevi.com/ws/voice/conn-123?api_key=oak_your_api_key&config_id=your_config_id');

// With reconnection library
import ReconnectingWebSocket from 'reconnecting-websocket';
const ws = new ReconnectingWebSocket('wss://api.nextevi.com/ws/voice/conn-123?api_key=oak_your_api_key&config_id=your_config_id');

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.nextevi.com/ws/voice/conn-123?api_key=oak_your_api_key&config_id=your_config_id');

import websockets
import asyncio
import json

async def connect():
    uri = "wss://api.nextevi.com/ws/voice/conn-123?api_key=oak_your_api_key&config_id=your_config_id"
    
    async with websockets.connect(uri) as websocket:
        # Send session settings
        await websocket.send(json.dumps({
            "type": "session_settings",
            "timestamp": time.time(),
            "message_id": "settings-1",
            "data": {
                "emotion_detection": {"enabled": True},
                "audio": {"sample_rate": 24000, "channels": 1, "encoding": "linear16"}
            }
        }))
        
        # Listen for messages
        async for message in websocket:
            data = json.loads(message)
            print(f"Received: {data}")

asyncio.run(connect())

# Test WebSocket connection with cURL
curl -i -N -H "Connection: Upgrade" \
     -H "Upgrade: websocket" \
     -H "Sec-WebSocket-Version: 13" \
     -H "Sec-WebSocket-Key: $(echo -n 'test' | base64)" \
     -H "Authorization: Bearer your_jwt_token" \
     "wss://api.nextevi.com/ws/voice/conn-123?config_id=your_config_id"

Connection Flow

WebSocket Handshake: Client initiates WebSocket connection
Authentication: Server validates API key or JWT token
Connection Metadata: Server sends connection details
Session Settings: Client configures audio and feature settings
Ready: Connection ready for voice communication

Next Steps

Message Protocol

Learn the complete WebSocket message format

Audio Handling

See examples of sending and receiving audio

Troubleshooting

Connection Issues

Ensure your API key starts with oak_
Verify your config_id is valid
Check network connectivity and firewall settings

Authentication Errors

Double-check API key format and permissions
Ensure JWT token is properly formatted and not expired
Verify project_id matches your configuration

See Error Reference for complete error codes and solutions.

Getting Started

Speech-to-Speech

API Reference

WebSocket Connection

WebSocket API Connection

Quick Start

WebSocket URL

Authentication Methods

Connection Examples

Platform-Specific Examples

Connection Flow

Next Steps

Message Protocol

Audio Handling

Troubleshooting

Connection Issues

Authentication Errors

Getting Started

Speech-to-Speech

API Reference

​WebSocket API Connection

​Quick Start

​WebSocket URL

​Authentication Methods

​Connection Examples

​Platform-Specific Examples

​Connection Flow

​Next Steps

Message Protocol

Audio Handling

​Troubleshooting

​Connection Issues

​Authentication Errors

WebSocket API Connection

Quick Start

WebSocket URL

Authentication Methods

Connection Examples

Platform-Specific Examples

Connection Flow

Next Steps

Troubleshooting

Connection Issues

Authentication Errors