Skip to main content

WebSocket Integration

The Chat API provides real-time messaging capabilities through WebSocket connections. This allows for immediate message delivery and streaming AI responses that enhance the user experience.

Connection Setup

Endpoint

Authentication Parameters

WebSocket connections require authentication through query parameters or headers: Required Parameters:
  • api_key: Your tenant’s API key
  • user_id: User identifier
  • chat_id: Chat UUID (must exist from REST API)

Connection Methods

Query Parameters

Headers

Message Format

Sending Messages

Send messages as JSON with minimal required fields:
With Metadata:

Receiving Events

All WebSocket events follow this structure:

Event Types

1. Connection Established

Sent immediately when WebSocket connection is successful:

2. User Created

Sent when a new user entity is automatically created:

3. Message Received

Confirms your message was received and saved:

4. AI Stream Started

Indicates the AI has started generating a response:

5. AI Stream Token

Real-time tokens as the AI generates its response:

6. AI Stream Ended

Complete AI response with final message details:

7. Error Events

Authentication Error

Chat Not Found

Missing Parameters

Implementation Examples

Basic JavaScript Client

React Hook Implementation

Python Client Example

Best Practices

Connection Management

  1. Reconnection Logic: Implement automatic reconnection with exponential backoff
  2. Heartbeat: Send periodic ping messages to keep the connection alive
  3. Graceful Shutdown: Always close connections properly

Error Handling

  1. Network Issues: Handle temporary disconnections gracefully
  2. Authentication Failures: Refresh API keys if needed
  3. Rate Limiting: Respect rate limits and backoff when needed

Performance

  1. Message Batching: Avoid sending messages too rapidly
  2. Stream Processing: Process tokens incrementally for better UX
  3. Memory Management: Clear old messages to prevent memory leaks

Security

  1. API Key Storage: Never expose API keys in client-side code
  2. Input Validation: Validate message content before sending
  3. Connection Limits: Monitor and limit concurrent connections

Rate Limits

  • Messages: 10 messages per second per connection
  • Concurrent Connections: 50 per tenant
  • Connection Duration: No hard limit, but idle connections may be closed

Troubleshooting

Common Issues

  1. Connection Refused: Check if the chat exists via REST API first
  2. Authentication Errors: Verify API key and user permissions
  3. Message Not Received: Check network connectivity and rate limits
  4. Streaming Interrupted: Implement reconnection logic

Debugging

Enable WebSocket debugging in your browser or client: