SDK Wire Protocol

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, and persona.

{
  "type": "register",
  "functions": [
    {
      "name": "getOrderStatus",
      "description": "Get order status",
      "params": { "orderId": { "type": "string" } },
      "safety": "read"
    }
  ],
  "states": [...],
  "policies": [...],
  "flows": [...],
  "persona": "You are a helpful assistant...",
  "sdkVersion": "0.1.1"
}

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_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

On this page