Platforms

SDK integration guides for every tech stack — Node, Next.js, React, Python, Go, Ruby, Rust.

Pick your backend framework and follow the step-by-step integration guide. Each guide covers SDK installation, tool registration, lifecycle states, connection, and widget embedding for that stack.

Official SDKs

These stacks have published, maintained SDK packages:

Platform	Package	Version	Guide
Node.js	`@aelio/sdk`	0.1.1	Node.js
Next.js	`@aelio/sdk` + `@aelio/chat`	0.1.1 / 0.1.3	Next.js
React	`@aelio/sdk` + `@aelio/chat`	0.1.1 / 0.1.3	React
Python	`aelio-sdk`	0.1.0	Python

Community / wire protocol

These stacks don't have official SDKs yet. You can implement the SDK yourself using the wire protocol (JSON over WebSocket, ~300 lines of code):

Platform	Status	Guide
Go	Protocol enum ready, SDK planned	Go
Ruby	Community guide	Ruby
Rust	Community guide	Rust

What every integration includes

Regardless of stack, every Aelio integration follows the same pattern:

1. Install SDK (or implement wire protocol)
2. Register tools with expose()
3. Declare lifecycle states, policies, flows (optional)
4. Set persona and product description
5. Connect with listen() — SDK dials out to server
6. Embed chat widget in frontend
7. Configure origin allowlist on server

SDK concepts (all platforms)

expose() — register a tool

aelio.expose('getOrderStatus', async (args, ctx) => {
  return await db.orders.findOne({ id: args.orderId, userId: ctx.customerId });
}, {
  description: 'Get the status of a customer order',
  params: { orderId: 'string' },
  safety: 'read',
});

Safety levels

Level	Behavior
`read`	Auto-allowed
`write`	Requires user confirmation
`destructive`	Blocked in V1

Handler context

Every handler receives a context object:

customerId    — your user ID
sessionId     — conversation session
channel       — 'web' | 'whatsapp' | custom
channelAddress — email or phone
locale        — optional
metadata      — optional key-value pairs

Connection

The SDK dials out to ws://your-server/sdk with Authorization: Bearer <secret>. Auto-reconnects with exponential backoff.

Working examples in the repo

Example	Path	Stack
Minimal Express	`examples/nodejs-express/`	Node.js
ShopCo SaaS demo	`examples/sample-saas/`	Node.js + Express
Shopping Testbed	`Aelio-Test/`	Node.js + Postgres
FastAPI	`examples/python-fastapi/`	Python
Django (stub)	`examples/python-django/`	Python

On this page