Custom UI Adapter Guide

Use this path when developers want to embed Rooaak messaging into their own app UI.

Reference implementation:

• rooaak-custom-ui-sample-app

Architecture

1. Browser/app sends message to your backend (POST /api/chat in sample).
2. Backend calls Rooaak POST /v1/agents/:id/messages.
3. Backend returns response immediately (responded) or waits/polls for completion.
4. UI renders final assistant response.

Required env

• ROOAAK_API_KEY
• ROOAAK_AGENT_ID
• optional: ROOAAK_BASE_URL

Message contract

Use stable sessionId per conversation and include metadata:

{
  "sessionId": "customer-123-thread-1",
  "message": "hello",
  "metadata": {
    "channel": { "type": "custom_ui" },
    "correlationId": "req-123"
  }
}

Production requirements

1. Send Idempotency-Key on writes.
2. Verify your own app auth before forwarding user messages.
3. Log messageId, sessionId, and correlationId for traceability.
4. Handle pending status (poll/webhook completion).

Smoke test

curl -X POST https://<your-host>/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"qa-custom-ui",
    "message":"Reply exactly: custom-ui-smoke-ok",
    "idempotencyKey":"qa-custom-ui-1",
    "correlationId":"qa-custom-ui-1"
  }'

Expected:

• HTTP 200
• JSON with status: "responded" and assistant response text