WebSocket API Documentation

The ZeebeeAI WebSocket API allows for real-time, bidirectional communication between clients and the ZeebeeAI service. This is particularly useful for streaming AI responses and building real-time chat applications.

Connection

To connect to the WebSocket server, use the following endpoint:

wss://api.zeebee.ai/v1/chat/ws

Authentication

You need to include your API key in the connection request as a query parameter:

wss://api.zeebee.ai/v1/chat/ws?api_key=YOUR_API_KEY

Message Format

All messages sent and received through the WebSocket connection use JSON format.

Client Messages

Messages sent from the client to the server should follow this structure:

{
  "type": "message",
  "conversation_id": "optional-conversation-id",
  "message": "Your message here",
  "model": "gpt-4-turbo",
  "options": {
    "temperature": 0.7,
    "max_tokens": 1000
  }
}

Message Types

Server Messages

Messages received from the server follow this structure:

{
  "type": "message_chunk",
  "conversation_id": "conversation-id",
  "message_id": "message-id",
  "chunk": "AI response chunk",
  "is_final": false
}

When is_final is true, it indicates that the complete response has been delivered.

Server Message Types

Voice Chat Support

The WebSocket API also supports voice chat capabilities. You can send audio data through the WebSocket connection for real-time speech-to-text processing.

Audio Message Format

{
  "type": "audio",
  "audio_data": "base64-encoded-audio",
  "format": "wav",
  "sample_rate": 16000
}

Example Code

Here's a simple example of how to use the WebSocket API with JavaScript:

const API_KEY = 'your-api-key';
const ws = new WebSocket(`wss://api.zeebee.ai/v1/chat/ws?api_key=${API_KEY}`);

ws.onopen = () => {
  console.log('Connected to ZeebeeAI WebSocket');
  
  // Send a message to the AI
  ws.send(JSON.stringify({
    type: 'message',
    message: 'Hello, how can you help me today?',
    model: 'gpt-4-turbo'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'message_chunk') {
    // Display the chunk
    console.log(data.chunk);
    
    if (data.is_final) {
      console.log('Complete response received');
    }
  } else if (data.type === 'error') {
    console.error('Error:', data.error);
  }
};

ws.onclose = () => {
  console.log('Disconnected from WebSocket');
};

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

Error Handling

The server may send error messages in the following format:

{
  "type": "error",
  "error": {
    "code": "invalid_request",
    "message": "Invalid request format"
  }
}

Common Error Codes