Documentation Index
Fetch the complete documentation index at: https://docs.ansa.so/llms.txt
Use this file to discover all available pages before exploring further.
Ansa uses WebSocket connections (via Socket.IO) to provide real-time features like typing indicators, agent presence, and instant message delivery.
Features
| Feature | Description |
|---|
| Typing Indicators | Show when users or agents are typing |
| Agent Presence | See when human agents join conversations |
| Message Delivery | Instant message updates without polling |
| Reconnection | Automatic reconnect with message replay |
How It Works
The widget automatically establishes a WebSocket connection when opened. The connection handles:
- Bi-directional typing indicators between users and dashboard agents
- Real-time message delivery for human agent responses
- Presence updates when agents join or leave conversations
- Automatic reconnection with message history replay
Events
Client → Server
| Event | Payload | Description |
|---|
join-conversation | { conversationId } | Subscribe to conversation updates |
typing-start | { conversationId } | User started typing |
typing-stop | { conversationId } | User stopped typing |
Server → Client
| Event | Payload | Description |
|---|
typing | { conversationId, isTyping, userId } | Typing indicator update |
agent-joined | { conversationId, agentName } | Human agent joined |
message-replay | Message[] | Messages since disconnect |
Rate Limiting
To prevent abuse, WebSocket events are rate-limited:
| Event Type | Limit |
|---|
| Messages | 10 per minute |
| Typing | 3 per second |
| Overall | 50 events per minute |
rate-limit-exceeded event is sent:
{
"type": "rate-limit-exceeded",
"retryAfter": 5000
}
Custom Integration
If you’re building a custom chat interface, you can connect directly to the WebSocket:
import { io } from "socket.io-client";
const socket = io("wss://api.ansa.so", {
path: "/socket",
auth: {
token: "your-api-key",
conversationId: "conv_xxx"
}
});
// Join a conversation
socket.emit("join-conversation", { conversationId: "conv_xxx" });
// Listen for typing indicators
socket.on("typing", ({ isTyping, userId }) => {
if (isTyping) {
showTypingIndicator(userId);
} else {
hideTypingIndicator(userId);
}
});
// Send typing status
let typingTimeout;
input.addEventListener("input", () => {
socket.emit("typing-start", { conversationId });
clearTimeout(typingTimeout);
typingTimeout = setTimeout(() => {
socket.emit("typing-stop", { conversationId });
}, 2000);
});
// Handle agent joining
socket.on("agent-joined", ({ agentName }) => {
showSystemMessage(`${agentName} joined the conversation`);
});
// Handle reconnection
socket.on("message-replay", (messages) => {
messages.forEach(appendMessage);
});
Connection States
| State | Description |
|---|
connecting | Initial connection attempt |
connected | WebSocket active |
disconnected | Connection lost, will retry |
reconnecting | Attempting to reconnect |
failed | Max retries exceeded |
- Exponential backoff for reconnection attempts
- Message queuing during disconnection
- Automatic replay of missed messages
Dashboard Integration
Human agents in the dashboard see:
- User typing indicators — When customers are typing
- Connection status — Whether the user is online
- Read receipts — When messages are delivered
Next Steps
Widget API
Control widget programmatically
Webhooks
Server-side event notifications
