API Reference
Widget WebSocket Protocol
WebSocket frames between the chat widget and Aelio server.
Endpoint: ws://your-server/widget/ws
Auth: Origin allowlist + optional session token on init
Client → Server
init
Sent on WebSocket connect to authenticate and identify the customer.
{
"type": "init",
"customerId": "user_123",
"authToken": "eyJ...",
"email": "user@example.com"
}message
Send a chat message.
{
"type": "message",
"content": "What is my order status?"
}Max message length: 4096 characters.
Server → Client
ready
Sent after successful init. Includes chat history.
{
"type": "ready",
"customerId": "user_123",
"history": [
{ "role": "user", "content": "Hello", "timestamp": "..." },
{ "role": "assistant", "content": "Hi! How can I help?", "timestamp": "..." }
]
}typing
Typing indicator while the LLM processes.
{
"type": "typing",
"active": true
}message
Assistant reply.
{
"type": "message",
"role": "assistant",
"content": "Your order #A123 is shipped!",
"turnId": "turn_abc"
}confirmation
Write action requires user confirmation.
{
"type": "confirmation",
"prompt": "Cancel order #A123? Reply **yes** to confirm.",
"turnId": "turn_abc"
}The widget renders Confirm/Cancel buttons for this frame.
error
{
"type": "error",
"message": "Origin not allowed",
"code": "origin_not_allowed"
}Error codes
| Code | Auto-retry | Meaning |
|---|---|---|
origin_not_allowed | No | Page origin not in allowlist |
auth_required | No | Token required but not provided |
identity_mismatch | No | Token doesn't match customerId |
Connection behavior
- Handshake timeout: ~8 seconds
- Auto-reconnect: exponential backoff, max 10 attempts
- Origin policy failures do not auto-retry
- Status UI: Connecting → Connected → Reconnecting → Failed (with Retry)