Agent setup

Connect any backend AI agent to the CloudBot frontend voice service.

CloudBot handles the customer conversation, room, tenant context, dashboard, and voice runtime. Your backend agent handles tools, files, workflows, sub-agents, and deeper work through one HTTP gateway contract.

Setup path

The customer flow should feel like talking to the frontend agent.

01Create or choose a shared gateway API key. This is the key CloudBot sends as X-API-Key when it calls your backend.
02Expose a public HTTPS gateway URL that CloudBot can reach.
03Implement GET /cloudbot/voice/health so CloudBot can verify the gateway before sending live traffic.
04Implement POST /cloudbot/voice/inbound so the CloudBot frontend voice agent can send messages to the backend agent.
05Return a synchronous reply when wait_for_reply is true, or accept the message and deliver the response to your configured callback URL.
06Preserve tenant_id, room_name, frontend_agent_id, route_id, backend_agent_id, request_id, worker_id, and response_mode in logs and replies so CloudBot can sync message state.
07Use the CloudBot dashboard Agent Routing tab to save the gateway URL, gateway API key, backend profile, and frontend-to-backend routes.
08Run the dashboard health check. A healthy result means the frontend registration and backend gateway are paired.

Registration

CloudBot stores the backend gateway before it sends live traffic.

The dashboard Agent Routing tab saves the backend gateway URL, a shared gateway key, backend agent profile, response mode, and frontend-to-backend routes. CloudBot tests /cloudbot/voice/healthbefore treating the gateway as healthy.

Gateway health contract

GET /cloudbot/voice/health
X-API-Key: <shared_gateway_key>

200 OK
{
  "status": "healthy",
  "channel": "cloudbot-voice",
  "auth_configured": true,
  "timestamp": "2026-07-13T00:00:00.000Z"
}

Message relay

The frontend voice agent sends work to the backend agent with correlation fields.

Any agent framework can connect if it accepts the inbound HTTP payload, authenticatesX-API-Key, preserves the correlation fields, and returns or posts the backend response.

Inbound request

POST /cloudbot/voice/inbound
Content-Type: application/json
X-API-Key: <shared_gateway_key>

{
  "message": "Summarize the current customer request and run the needed tool.",
  "route_id": "frontend_backend_route_uuid",
  "backend_agent_id": "backend_agent_profile_uuid",
  "external_agent_id": "n8n_workflow_or_worker_id",
  "worker_id": "kw1",
  "tenant_id": "tenant_slug_or_id",
  "room_name": "cb_tenant_1720000000",
  "frontend_agent_id": "frontend_voice_agent_id",
  "request_id": "cbbe_1720000000_ab12cd34",
  "response_mode": "sync",
  "wait_for_reply": true
}

Synchronous reply

200 OK
{
  "status": "ok",
  "messageId": "cbv_1720000000_ab12cd",
  "sessionKey": "agent:main:cloudbot-voice:direct:cloudbot:kw1",
  "worker_id": "kw1",
  "tenant_id": "tenant_slug_or_id",
  "room_name": "cb_tenant_1720000000",
  "frontend_agent_id": "frontend_voice_agent_id",
  "route_id": "frontend_backend_route_uuid",
  "backend_agent_id": "backend_agent_profile_uuid",
  "request_id": "cbbe_1720000000_ab12cd34",
  "reply": "Here is the result to speak back to the user."
}

OpenClaw

OpenClaw can use the CloudBot voice channel plugin directly.

The OpenClaw plugin exposes the same health and inbound endpoints. Configure its shared key to match the key saved in CloudBot, then let the dashboard health check verify the pairing.

openclaw.json

{
  "plugins": {
    "allow": ["cloudbot-voice"],
    "entries": {
      "cloudbot-voice": {
        "enabled": true,
        "config": {
          "apiKey": "<shared_gateway_key>",
          "externalAgentId": "kenny",
          "responseMode": "sync"
        }
      }
    }
  },
  "channels": {
    "cloudbot-voice": {
      "enabled": true,
      "callbackUrl": "https://your-agent.example.com/cloudbot/callback",
      "accounts": {
        "default": { "enabled": true }
      }
    }
  }
}

Sync

Runtime observability keeps the frontend, backend, and dashboard aligned.

CloudBot runtime services can write redacted backend traffic events into the website runtime API. Use the same request id across outbound request, inbound response, errors, and timeouts so the dashboard can show what happened.

Runtime traffic event

POST /api/runtime/agent/{frontend_agent_id}/backend-events
Content-Type: application/json
X-Runtime-API-Key: <cloudbot_runtime_key>
X-Tenant-ID: <tenant_slug_or_id>

{
  "request_id": "cbbe_1720000000_ab12cd34",
  "connection_id": "openclaw_connection_uuid",
  "backend_agent_profile_id": "backend_agent_profile_uuid",
  "route_id": "frontend_backend_route_uuid",
  "room_name": "cb_tenant_1720000000",
  "backend_peer_id": "cloudbot:kw1",
  "direction": "inbound",
  "event_type": "response",
  "status": "ok",
  "status_code": 200,
  "latency_ms": 842,
  "payload": {
    "reply_preview": "Here is the result..."
  }
}

Contract

Fields that must move through the whole system.

request_id

Correlates the request, backend response, error, and dashboard traffic row.

tenant_id

Keeps the backend action scoped to the right CloudBot customer.

room_name

Links the backend action to the live conversation or session.

frontend_agent_id

Identifies the CloudBot frontend voice agent that initiated the work.

route_id

Identifies the dashboard route that linked the frontend agent to the backend agent.

backend_agent_id

Identifies the registered backend agent profile that should do the work.

response_mode

Tells the backend whether CloudBot expects a sync reply, async callback, or both.

worker_id

Routes parallel work to a worker lane such as kw1 when present.