Channels
How to turn on and check the HTTP API, Telegram (bot and groups), the widget and the incoming MCP channel, and which team a message goes to.
A channel is where messages come into the cradle from. There are four channels; the HTTP API works from the first start, the others are turned on. In the console the settings are on the team page: the Integrations tab → the channel's card.
1. Which team a message goes to
| Channel | Team |
|---|---|
| HTTP API | the team of the key the request came with |
| MCP channel | the team of the key |
| Telegram, a group | the team chosen for the group in the Telegram card |
| Telegram, a private chat | the "channel team" |
| Widget | the "channel team" |
The "channel team" is stored in the channel's own settings; by default it is the
cradle's service team opencradle. In version 0.9.2 there is no screen or command to
change it. While opencradle has no agents the console does not show it. For
private Telegram chats and the widget to be answered by anybody, create an agent in
that team:
cradle teams use opencradle
cradle agents create --template support --name "Support"(an admin:* key is needed). Once the agent exists, the "OpenCradle" team is
visible on the "Teams" page. For the HTTP API and MCP this is not needed: the key
decides the team.
2. HTTP API
The channel is on at once and listens on 127.0.0.1:31416. The port and the
listening address are set by the server flags --port and --bind (the variable
CRADLE_BIND) at every start: the card does not override them. The "API key" field
in the card is only there so the channel can start (at least 16 characters): at
the first start the server puts a copy of the administrator key there, so do not
show the card to outsiders. Requests are authorized with the keys from cradle keys.
-
Issue a key for the team (Sign-in, people and keys):
cradle keys create --name "site" --scopes messages:read,messages:write --team <team-id> -
Send a message:
curl -sS -X POST http://127.0.0.1:31416/api/v1/messages \ -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"text":"Hello","chatId":"test-1"}'
The answer has ok, mode, chatId, conversationId, messageId, ticketId
(null if the reply went out without a human) and replies. The modes are sync
(the default, the reply comes in the same request), async (a 202 answer and a
drainUrl, the replies are collected with GET /api/v1/messages/<chatId>?wait=<ms>)
and webhook (the field webhookUrl; the signature is the header
X-Cradle-Signature: sha256=…, HMAC-SHA256 with the webhook secret or the channel
key). To continue a conversation use the same chatId.
How to check. The answer is "ok":true. Without a model the reply is
Запрос принят и передан оператору на проверку. Ответим в течение нескольких минут.
(the request is accepted and passed to an operator for review; the server writes it
in Russian), and ticketId is filled — the ticket waits for a human
(Waiting for decision). The "HTTP API" card shows "requests: N".
If it did not work.
- 401
unauthorized— the key is wrong; 403 withmissing—messages:writeis not granted. - 400
text length out of bounds (1..50000)—textis empty or too long. - 429 — more than 120 requests a minute from one address and key.
3. Telegram
- In Telegram create a bot with
@BotFatherand copy the token like1234567890:ABC-.... - In the console: Integrations → Telegram → the "Bot token" field → Save → Start.
The bot works over long polling: no incoming port has to be opened.
How to check. The card says "Connected as @bot_name"; write to the bot in a
private chat — a ticket appears in "Waiting for decision" of the channel team, or
the bot answers itself. The state of all channels: cradle channels list (the RUNNING
column).
If it did not work. The answer Failed to connect to Telegram: … — the token is wrong or the
server has no way out to api.telegram.org.
Groups
Add the bot to a Telegram group: it reads everything written there and answers
those who address it (an @bot mention, a reply to its message, a command). A
"Группы" (groups) list with a select for every group appears in the Telegram
card. Choose a team and press Save.
While a group has "Команда канала" (the channel team) selected, it is not bound:
the bot answers once Меня сюда не подключили. Попросите администратора привязать группу к команде в Cradle.
(I am not connected here; ask an administrator to bind the group to a team in
Cradle) and then stays silent.
If the card shows "Privacy mode включён" (privacy mode is on), the bot receives
only commands and mentions. For the bot to see everything: in @BotFather —
/setprivacy → Disable, then remove the bot from the group and add it again (or
make the bot an administrator of the group).
4. Widget
A floating chat with one <script> on your site. In the console: Integrations
→ Web Widget → Port (31415 by default), Accent color, API key (the
Generate button gives a key like wk_...), Allowed origins (comma-separated;
empty — any), Greeting → Save → Start. The ready code is in the "Embed
snippet" field (Copy to clipboard):
<script
src="https://<public-address>/widget.js"
data-cradle-widget
data-api-key="wk_..."
async></script>The widget listens on 127.0.0.1 only: for a page on the internet to see it,
publish the port through a reverse proxy or a tunnel. Besides, the widget.js
bundle is not part of the installer archive or the Docker image:
on such a server GET /widget.js
answers 503 "Widget bundle not built yet". Build it with bun run widget:build in
a repository clone and run the server from there.
How to check. curl -i http://127.0.0.1:31415/widget.js gives 200 and
application/javascript; the card says "Connections: N · Port: 31415".
If it did not work. 503 — the bundle is not built (see above); the widget does not open on the site — the site's domain is not in "Allowed origins".
5. The incoming MCP channel
Through it Claude Code, n8n or SmartNotes call the cradle as an MCP server. The channel is off by default. Turn it on in one of two ways.
At server start, with an environment variable (0.0.0.0 opens the channel to the
network, the port is set by CRADLE_MCP_PORT, 31417 by default):
CRADLE_MCP_BIND=127.0.0.1 cradle-server …On a running server there is neither a console screen nor a working CLI command
(cradle channels start is a stub), so the channel is turned on with
POST /api/v1/rpc/channels:start:
curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/channels:start \
-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"args":["mcp-server"]}'The address is http://127.0.0.1:31417/mcp (method POST), the key goes in the
header x-api-key or Authorization: Bearer; every tool needs its own scope:
| Tool | Scope |
|---|---|
cradle_search_kb, cradle_list_kbs | kb:read |
cradle_list_agents | agents:read |
cradle_execute_agent, cradle_summarize_notes | agents:execute |
cradle_get_ticket, cradle_list_tickets | tickets:read |
cradle_submit_issue | messages:write |
cradle_catalog, cradle_team_plan, cradle_team_export | teams:read |
cradle_team_apply | agents:write |
How to check.
curl http://127.0.0.1:31417/healthThe answer is {"ok":true,"running":true,"toolCount":12,…}.
If it did not work. ECONNREFUSED — the channel is not turned on; the tool
answer unauthorized — no key or the scope is missing. The "MCP servers" card in
the console is something else: through it agents call external servers, not the
other way round.