SDK Wire Protocol
WebSocket frames between the Aelio server and your SDK.
Endpoint: ws://your-server/sdk
Auth: Authorization: Bearer <AELIO_SDK_SECRET>
On connect, the SDK must send a register frame within 15 seconds.
SDK → Server
register
Sent immediately after WebSocket connect. Declares all tools, states, policies, flows, pipeline manifest, attributes, and persona.
{
"type": "register",
"functions": [
{
"name": "getOrderStatus",
"description": "Get order status",
"params": { "orderId": { "type": "string" } },
"safety": "read",
"intent": "order_inquiry"
}
],
"states": [...],
"policies": [...],
"flows": [
{
"id": "shopco_onboarding",
"state": "onboarding",
"description": "Profile intake then product tour",
"steps": [
{ "id": "collect_name", "type": "attribute", "goal": "Ask for name", "attribute": "display_name" },
{ "id": "review_orders", "type": "tool", "goal": "Show orders", "tool": "listOrders" }
]
}
],
"pipeline": {
"initial_stage": "unverified",
"stages": {
"unverified": {
"id": "unverified",
"description": "Brand-new visitor",
"flow": "welcome",
"allowedIntents": ["public"],
"next": "verified"
}
}
},
"attributes": [
{
"id": "display_name",
"label": "Display name",
"data_type": "string",
"sensitivity_tier": "pii",
"prompts": ["What should I call you?"]
}
],
"persona": "You are a helpful assistant...",
"productBrief": "We are an e-commerce platform...",
"sdkVersion": "0.1.1"
}Pipeline registration
pipeline, flows, and attributes are optional. When present, Aelio enables the pipeline engine for staged onboarding. Pipeline stages are also derived as lifecycle states automatically. See Pipeline YAML Manifest.
result
Response to an invoke frame.
{
"type": "result",
"invokeId": "inv_abc",
"ok": true,
"data": { "status": "shipped", "trackingNumber": "1Z..." }
}Error result:
{
"type": "result",
"invokeId": "inv_abc",
"ok": false,
"error": {
"code": "HANDLER_ERROR",
"message": "Order not found",
"retryable": false
}
}pong
Response to server ping (keepalive every 30s, timeout at 60s).
ingest
Push an inbound message from your own webhook.
{
"type": "ingest",
"channel": "whatsapp",
"from": "+1234567890",
"text": "Show me my orders",
"messageId": "msg_123"
}set_state
Push customer lifecycle state.
{
"type": "set_state",
"customerId": "user_123",
"stateId": "browsing",
"reason": "Started shopping session"
}set_global_stage
Push the customer's global pipeline stage (when not auto-advanced by the engine).
{
"type": "set_global_stage",
"customerId": "user_123",
"stage": "active",
"reason": "Manual override after CRM sync"
}set_attribute
Push a collected profile attribute value.
{
"type": "set_attribute",
"customerId": "user_123",
"attributeId": "verified_email",
"value": "user@example.com",
"source": "third_party_auth",
"verified": true
}set_flow_progress
Update guided flow progress.
{
"type": "set_flow_progress",
"customerId": "user_123",
"flowId": "shopping_purchase_journey",
"stepIndex": 2,
"completedSteps": ["discover_products", "select_item"]
}Server → SDK
invoke
Request to execute a registered tool.
{
"type": "invoke",
"invokeId": "inv_abc",
"function": "getOrderStatus",
"args": { "orderId": "ord_123" },
"context": {
"customerId": "user_123",
"sessionId": "sess_abc",
"channel": "web",
"channelAddress": "user@example.com"
}
}send
Request to deliver an outbound message (BYO channel).
{
"type": "send",
"channel": "whatsapp",
"to": "+1234567890",
"content": "Your order has shipped!"
}ping
Keepalive check. SDK must respond with pong.
error
{
"type": "error",
"code": "invalid_message",
"message": "Validation failed"
}ack
Successful side effect acknowledgment.
{
"type": "ack",
"op": "set_state"
}Error codes
| Code | Meaning |
|---|---|
FUNCTION_NOT_FOUND | Tool name not in register catalog |
HANDLER_ERROR | Exception in your handler |
NO_SEND_HANDLER | onSend not registered |
SEND_FAILED | Delivery handler failed (retryable) |
invalid_json | Malformed frame |
invalid_message | Zod validation failure |
not_registered | Action before register frame |
Connection limits
- Max 32 concurrent SDK connections (oldest evicted at limit)
- Frame size limit: 64KB
- Auto-reconnect: exponential backoff, max 30s delay