Channels API: configure agent communication

Manage agent communication channels. OpenClaw agents use runtime-managed channel catalog endpoints; legacy agents use Nora’s built-in channel adapters.

All channel endpoints require access to the agent. Direct owners, authorized workspace members, and platform admins can read or mutate according to their normal agent permissions.

Runtime behavior

Runtime	Backing system	Supported actions
OpenClaw	OpenClaw gateway config and pairing APIs	List catalog rows, load type metadata, save setup, link QR/CLI channels, logout supported channels, enable/disable configured rows
Legacy / non-OpenClaw	Nora `channels` table and adapter layer	Create, update, delete, test-message, inbound webhook logging, message history

OpenClaw channels do not expose Nora’s legacy test-message or message-history APIs. For OpenClaw, use the channel’s Setup, Link, Logout, and Enable/Disable actions.

List channels

Return the channel payload for an agent.

GET /agents/:id/channels

Response

string

openclaw or legacy.

string

Display title for the channel surface.

string

Display description for the channel surface.

object

Feature flags such as supportsTesting, supportsMessageHistory, and supportsLazyTypeDefinitions.

array

Configured rows for legacy agents, or OpenClaw catalog rows for OpenClaw agents.

array

Channel type metadata used by the dashboard setup form.

{
  "runtime": "openclaw",
  "title": "OpenClaw Channels",
  "capabilities": {
    "supportsTesting": false,
    "supportsMessageHistory": false,
    "supportsArbitraryNames": false,
    "supportsLazyTypeDefinitions": true
  },
  "channels": [
    {
      "id": "whatsapp",
      "type": "whatsapp",
      "name": "WhatsApp",
      "configured": false,
      "enabled": false,
      "actions": { "canQrLogin": true, "loginKind": "web", "canDelete": false }
    }
  ],
  "availableTypes": [{ "type": "whatsapp", "label": "WhatsApp (QR link)" }]
}

Get channel type metadata

Load setup metadata for one channel type.

GET /agents/:id/channels/types/:type

For OpenClaw agents, :type is the OpenClaw channel id such as whatsapp, telegram, slack, feishu, or zalouser. Nora returns docs-backed setup fields for built-in OpenClaw channels and uses the runtime schema as a best-effort fallback for custom channels.

Create or setup a channel

POST /agents/:id/channels

For OpenClaw agents, this saves setup into channels.<type> through the OpenClaw config API. For legacy agents, it creates a Nora channel row.

{
  "type": "telegram",
  "config": { "botToken": "123456:ABC-DEF" },
  "enabled": true
}

OpenClaw responses use the setup result shape:

{ "success": true, "channel": "telegram", "restart": "requested" }

Legacy responses return the stored channel record with an id.

Update a channel

PATCH /agents/:id/channels/:cid

For OpenClaw agents, :cid is the channel type id. Use this to save config changes or toggle enabled. For legacy agents, :cid is the channel UUID.

Link or pair an OpenClaw channel

POST /agents/:id/channels/:cid/connect
POST /agents/:id/channels/:cid/login
POST /agents/:id/channels/:cid/login/wait

These routes are available only for OpenClaw-managed channels. WhatsApp uses the web QR pairing provider. Feishu/Lark and Zalo Personal Account use the allowlisted OpenClaw CLI login flow.

Logout an OpenClaw channel

POST /agents/:id/channels/:cid/logout

Logout is exposed only for OpenClaw channel types Nora allows today: whatsapp, telegram, and qqbot.

Legacy-only actions

These routes remain available for legacy Nora adapter channels and return 409 for OpenClaw-managed channels.

DELETE /agents/:id/channels/:cid
POST /agents/:id/channels/:cid/test
GET /agents/:id/channels/:cid/messages?limit=50

Legacy test sends a real test message through the adapter. Legacy messages are ordered newest first and include direction, content, metadata, and created_at.

Inbound webhooks

Legacy adapters can receive inbound events through:

POST /api/webhooks/:channelId

Nora accepts the payload, logs it as inbound message history, and forwards it to the agent runtime if the agent is running. OpenClaw-managed channels use the OpenClaw runtime’s own inbound mechanisms instead of this legacy webhook logger.

Getting started

Concepts

Configuration

Guides

API Reference

Support

Channels

Channels API: configure agent communication

Runtime behavior

List channels

Response

Get channel type metadata

Create or setup a channel

Update a channel

Link or pair an OpenClaw channel

Logout an OpenClaw channel

Legacy-only actions

Inbound webhooks

​Channels API: configure agent communication

​Runtime behavior

​List channels

​Response

​Get channel type metadata

​Create or setup a channel

​Update a channel

​Link or pair an OpenClaw channel

​Logout an OpenClaw channel

​Legacy-only actions

​Inbound webhooks

Channels API: configure agent communication

Runtime behavior

List channels

Response

Get channel type metadata

Create or setup a channel

Update a channel

Link or pair an OpenClaw channel

Logout an OpenClaw channel

Legacy-only actions

Inbound webhooks