# Agent: Bot chat channels **Page:** api/agent/bots/channels [Download Raw Markdown](./api/agent/bots/channels.md) --- # Agent: Bot chat channels A chat channel connects one Bot to one bot account in Telegram, Slack, or Discord. Use these endpoints to read platform setup steps, connect a channel, pair people, control direct-message and group access, configure approvals, and manage channel-specific settings. See the [Bot API](/api/agent/bots/) for the Bot that a channel reaches and [Set up a chat app](/kit/agent/chat-apps/) for the step-by-step guide. In the Hub at hub.hoody.com, open Bots, select a Bot and open Chat apps. Choose Add a chat app, select Telegram, Slack or Discord and follow the setup steps: paste the required tokens and press Connect, then send the owner code to the bot in a direct message. Open the app's People or Chats section to manage access. All routes use this base URL: `https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com` Access to these routes is governed by the computer's proxy permission rules. Do not send an account token to this host. A Bot lives in one realm. Use `X-Hoody-Realm` or the `realm` query parameter to select `global` or a 24-character hexadecimal realm id. When omitted, the agent's current realm is used. A realm the login does not serve, or a Bot id the realm does not hold, returns `not_found`. The value `all` is accepted only by `GET /api/v1/agent/bots` and `POST /api/v1/agent/bots/resume`. ## Bot channel settings ### `GET /api/v1/agent/bots/{id}/channel-settings` Gets the settings set on the Bot and inherited by every channel. The response also gives each effective value and whether it comes from the Bot or the default. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `settings` | object | Yes | Settings explicitly set on the Bot. Other settings use their default. | | `settings.channels_paused` | boolean | No | Stops every chat app of the Bot while preserving each channel's own `enabled` value. | | `settings.hide_secrets` | boolean | No | Hides stored chat-app credentials from the agent's tools and, where supported, from shells started afterwards. It does not stop root or sudo. | | `settings.lang` | string | No | Language of fixed lines: `en`, `de`, `fr`, `es`, `pt`, `it`, `ja`, or `zh`. The Bot's answers are not translated. | | `settings.max_channels` | integer | No | Maximum number of chat apps, from 1 to 8. | | `settings.rate_bot_per_day` | integer | No | Messages all chat apps may deliver each day, from 0 to 3000. `0` means no limit. | | `settings.shared_identity` | string | No | Whether several Bots may share one chat app. Only `off` is available. | | `effective` | object | Yes | Effective settings and their sources. | | `effective.channels_paused` | object | No | Effective value and source for `channels_paused`. | | `effective.channels_paused.value` | boolean | Yes | Effective value. | | `effective.channels_paused.source` | string | Yes | Either `bot` or `default`. | | `effective.hide_secrets` | object | No | Effective value and source for `hide_secrets`. | | `effective.hide_secrets.value` | boolean | Yes | Effective value. | | `effective.hide_secrets.source` | string | Yes | Either `bot` or `default`. | | `effective.lang` | object | No | Effective value and source for `lang`. | | `effective.lang.value` | string | Yes | One of `en`, `de`, `fr`, `es`, `pt`, `it`, `ja`, or `zh`. | | `effective.lang.source` | string | Yes | Either `bot` or `default`. | | `effective.max_channels` | object | No | Effective value and source for `max_channels`. | | `effective.max_channels.value` | integer | Yes | Effective value, from 1 to 8. | | `effective.max_channels.source` | string | Yes | Either `bot` or `default`. | | `effective.rate_bot_per_day` | object | No | Effective value and source for `rate_bot_per_day`. | | `effective.rate_bot_per_day.value` | integer | Yes | Effective value, from 0 to 3000. | | `effective.rate_bot_per_day.source` | string | Yes | Either `bot` or `default`. | | `effective.shared_identity` | object | No | Effective value and source for `shared_identity`. | | `effective.shared_identity.value` | string | Yes | Always `off`. | | `effective.shared_identity.source` | string | Yes | Either `bot` or `default`. | | `effective.notes` | array | Yes | Notes about effective values. | | `effective.notes[].code` | string | Yes | What the note concerns. | | `effective.notes[].field` | string | Yes | The setting concerned. | | `effective.notes[].reason` | string | No | Additional reason, when the code has one. | ### Request ```bash curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channel-settings" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const settings = await client.agent.bots.channels.getSettings(botId); ``` ### Responses Media type: application/json ```json { "settings": { "lang": "de" }, "effective": { "channels_paused": { "value": false, "source": "default" }, "hide_secrets": { "value": true, "source": "default" }, "lang": { "value": "de", "source": "bot" }, "max_channels": { "value": 8, "source": "default" }, "rate_bot_per_day": { "value": 0, "source": "default" }, "shared_identity": { "value": "off", "source": "default" }, "notes": [] } } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot does not exist in the selected realm. | Verify the Bot id and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `PATCH /api/v1/agent/bots/{id}/channel-settings` Changes the Bot-wide settings inherited by every channel. Unknown fields are refused. If a setting value is invalid, nothing is applied. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `channels_paused` | boolean | No | Stops every chat app of the Bot while preserving each channel's own `enabled` value. Send `null` to remove the setting. | | `hide_secrets` | boolean | No | Hides stored chat-app credentials from the agent's tools and, where supported, from shells started afterwards. It does not stop root or sudo. Send `null` to remove the setting. | | `lang` | string | No | Fixed-line language: `en`, `de`, `fr`, `es`, `pt`, `it`, `ja`, `zh`, or `null`. The Bot's answers are not translated. | | `max_channels` | integer | No | Maximum number of chat apps, from 1 to 8. Send `null` to remove the setting. | | `rate_bot_per_day` | integer | No | Messages all chat apps may deliver each day, from 0 to 3000. `0` means no limit. Send `null` to remove the setting. | | `shared_identity` | string | No | Whether several Bots may share one chat app. Only `off` or `null` is available. | | `unset` | array of string | No | Settings to restore to their defaults: `lang`, `rate_bot_per_day`, `hide_secrets`, `channels_paused`, `shared_identity`, or `max_channels`. | ### Response fields The response contains the Bot settings and effective values described by `GET /api/v1/agent/bots/{id}/channel-settings`, plus these required fields: | Field | Type | Required | Description | |---|---|---|---| | `applied` | string | Yes | `live` means the settings are in effect now. `restart` means they take effect after the channels reconnect. | | `warnings` | array | Yes | Advisory notes about the new settings. | ### Request ```bash curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channel-settings" \ -H "Content-Type: application/json" \ --data '{"lang":"de"}' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const settings = await client.agent.bots.channels.updateSettings(botId, { lang: 'de' }); ``` ### Responses Media type: application/json ```json { "settings": { "lang": "de" }, "effective": { "channels_paused": { "value": false, "source": "default" }, "hide_secrets": { "value": true, "source": "default" }, "lang": { "value": "de", "source": "bot" }, "max_channels": { "value": 8, "source": "default" }, "rate_bot_per_day": { "value": 0, "source": "default" }, "shared_identity": { "value": "off", "source": "default" }, "notes": [] }, "applied": "live", "warnings": [] } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, or included an undeclared top-level body field. | Correct the request body and parameters, and remove undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot does not exist in the selected realm. | Verify the Bot id and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "setting_invalid", "message": "setting max_channels refused: out_of_range" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `setting_invalid` | Setting invalid | A setting value is out of range, has the wrong type, is not settable at this scope, or is not available yet. Nothing was applied. | Correct the field named in `details` and send the change again. | | `setting_conflict` | Setting conflict | Two resulting settings contradict each other. Nothing was applied. | Change both settings together, or change the other setting first. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ## Channels The following channel setting fields are available on channel objects and, where noted, in channel request bodies. In every effective-settings response, each row appears as `effective..value` and `effective..source`; both are required. The source is `bot`, `channel`, or `default`. | Field | Request type | Effective value type | Allowed values and limits | Description | |---|---|---|---|---| | `allowed_chats` | array or null | array | Platform chat ids, at most 200 | When not empty, only these chats are served. With `group_mode` set to `allowlist`, only listed groups approved by the owner are served. | | `blocked_chats` | array or null | array | Platform chat ids, at most 200 | Messages from these chats are dropped. | | `blocked_users` | array or null | array | Platform user ids, at most 200 | Messages from these users are dropped in every chat. | | `channel_lease` | boolean or null | boolean | `true` or `false` | Keeps the agent running while the chat app is enabled. When `false`, an open Bot session still keeps it running. | | `chat_commands` | array or null | array | Any subset of `status`, `stop`, `bind`, `unbind`, and `help` | Commands that work. A command not listed is treated as ordinary text. | | `command_denied_reply` | string or null | string | `hint` or `silent` | What a sender without the `control` right hears when sending a command. `hint` sends one line per hour per sender and chat. | | `command_prefix` | string or null | string | `!`, `.`, `;`, `~`, or `/` | Character that starts a chat command. Telegram defaults to `/`; other platforms default to `!`. | | `connection_opens_per_hour` | integer or null | integer | 1 to 120 | Slack only. Connections the channel may open per hour, including failed attempts. | | `decide_in_groups` | boolean or null | boolean | `true` or `false` | Whether approvals may be shown and decided in a group chat. | | `default_rights` | array or null | array | Any subset of `chat`, `control`, and `gates` | Rights given to a person added to the allowlist. It is also the default for `pairing_rights`. Open guests can only chat. | | `delivery_expiry_hours` | integer or null | integer | 1 to 168 | Hours after which an answer that could not be delivered is abandoned. | | `dm_policy` | string or null | string | `owner`, `allowlist`, `pairing`, or `open` | Controls direct messages. `owner` allows owners, `allowlist` allows paired or added people, `pairing` allows a person with a valid code when the code grants `chat`, and `open` allows anyone as a guest. | | `enabled` | boolean or null | boolean | `true` or `false` | Runs the chat app. When `false`, it stops and sends nothing. Set this only through the top-level `enabled` field of a channel update. | | `format` | string or null | string | `rich` or `plain` | Sends answers with platform markup or as plain text. | | `gate_cards` | string or null | string | `on`, `links`, or `off` | Controls how an approval is presented: a card with buttons, a card with text only, or no card. `gate_deciders` controls who may decide. | | `gate_deciders` | string or null | string | `none`, `owner`, `named`, or `principals` | Controls who may decide approvals: nobody, owners, people with the `gates` right, or everyone with the `chat` right. A guest never decides. | | `gate_detail` | string or null | string | `summary` or `minimal` | Controls whether an approval card shows a summary or only the tool name. | | `gate_ttl_minutes` | integer or null | integer | 0 to 10080 | Minutes before an approval card expires. `0` means it never expires. | | `group_mode` | string or null | string | `off`, `owner_approves`, `allowlist`, or `open` | Controls group admission. `off` ignores groups, `owner_approves` requires owner approval, `allowlist` requires an approved listed group, and `open` admits any addressed group with guest members. | | `hide_secrets` | boolean or null | boolean | `true` or `false` | Hides stored chat-app credentials from the agent's tools and, where supported, from shells started afterwards. It does not stop root or sudo. | | `home_chat` | string or null | string | A direct-message or approved-group chat id | Chat that receives the Bot's own updates. `null` sends none. Set this only through the top-level `home_chat` field of a channel update. | | `identify_per_day` | integer or null | integer | 1 to 500 | Discord only. Gateway logins the channel may attempt per day. | | `identify_per_hour` | integer or null | integer | 1 to 60 | Discord only. Gateway logins the channel may attempt per hour. | | `lang` | string or null | string | `en`, `de`, `fr`, `es`, `pt`, `it`, `ja`, or `zh` | Language of fixed lines. The Bot's answers are not translated. | | `max_parts` | integer or null | integer | 1 to 20 | Maximum number of parts used to send one answer. Longer answers are cut. | | `max_principals` | integer or null | integer | 1 to 32 | Maximum number of people kept by a channel. Pairing, allowlist additions, and owner enrolment beyond the limit are refused. | | `max_text_bytes` | integer or null | integer | 256 to 65536 | Longest accepted message in bytes. A character outside basic Latin uses 2 to 4 bytes. | | `mention_only` | boolean or null | boolean | `true` or `false` | In groups, reads only messages that address the Bot. When `false`, it reads every message in an approved group and needs the platform's message-content permission. | | `mirror_other_doors` | boolean or null | boolean | `true` or `false` | Sends replies to messages from other places to the home chat. | | `no_reply_notice` | boolean or null | boolean | `true` or `false` | Sends one line when a Bot turn ends without an answer. | | `outbound_rate` | number or null | number | At least 0.001 and no more than the platform limit | Messages per second sent to one chat. The platform limit is the default. | | `overflow_note` | boolean or null | boolean | `true` or `false` | Ends a cut answer with a line saying it continues in the session. | | `pairing_code_burn_tries` | integer or null | integer | 5 to 200 | Total wrong codes allowed before the active code stops working. | | `pairing_rights` | array or null | array | Any subset of `chat`, `control`, and `gates` | Rights granted by a pairing code that names no rights. When unset, `default_rights` applies. | | `pairing_ttl_minutes` | integer or null | integer | 1 to 1440 | Minutes that a pairing or owner-enrolment code remains valid. | | `pairing_user_burn_minutes` | integer or null | integer | 1 to 1440 | Minutes that a person who sent too many wrong codes is refused. A correct code is refused during this period. | | `pairing_user_burn_tries` | integer or null | integer | 1 to 20 | Wrong codes one person may send before that person is refused. | | `parse_mode` | string or null | string | `html` or `plain` | Telegram only. Markup used for rich answers. | | `part_chars` | integer or null | integer | 200 to the platform limit | `part_chars` is the maximum length of one message part in UTF-16 code units, from 200 to the platform limit (Telegram 4096, Slack 3900, Discord 2000), which is the default. A character outside the Basic Multilingual Plane (most emoji) counts as two units and every other character counts as one. | | `push_detail` | string or null | string | `brief` or `full` | Controls whether an update is written as one line or in full. A full update is split into at most `max_parts` messages of at most `part_chars` each. | | `push_events` | array or null | array | Any subset of `report`, `gate`, `gone`, `stop`, `waiter`, `limit`, `budget`, `error`, `provider`, `not_sent`, and `reset` | Bot updates sent to the home chat on their own. | | `rate_chat_per_min` | integer or null | integer | 0 to 600 | Messages one chat may send per minute across all senders. `0` means no limit. | | `rate_user_per_day` | integer or null | integer | 0 to 20000 | Messages one person may send per day. `0` means no limit. | | `rate_user_per_hour` | integer or null | integer | 0 to 3600 | Messages one person may send per hour. `0` means no limit. | | `rate_user_per_min` | integer or null | integer | 0 to 600 | Messages one person may send per minute. `0` means no limit. | | `reconnect_backoff_max_seconds` | integer or null | integer | 5 to 600 | Longest normal reconnect wait in seconds. A connection-open limit or platform retry delay may cause a longer wait. | | `reply_style` | string or null | string | `thread`, `reply`, or `plain` | Controls how an answer is attached to the message it answers. | | `show_sender_name` | boolean or null | boolean | `true` or `false` | Gives the Bot the sender's display name with group messages. It is an unverified hint and direct messages never carry it. | | `split_at` | string or null | string | `paragraph`, `line`, or `word` | Controls where a long answer is split into parts. | | `typing` | boolean or null | boolean | `true` or `false` | Shows a typing indicator while the Bot works. Telegram and Discord support it; Slack does not. | | `unpaired_reply` | string or null | string | `hint` or `silent` | What a sender who may not talk to the Bot hears. `hint` asks them to get a pairing code from the owner once per hour. | | `wake_replies` | boolean or null | boolean | `true` or `false` | Sends replies to the Bot's own updates to the home chat. | ### Channel object fields These fields apply to a single channel and to each item in a channel list. | Field | Type | Required | Description | |---|---|---|---| | `id` | string | Yes | Channel id. | | `kind` | string | Yes | Chat app: `discord`, `slack`, or `telegram`. | | `label` | string | Yes | Name assigned to the channel. | | `state` | string | Yes | `connecting`, `connected`, `awaiting_owner`, `degraded`, `standby`, `conflict`, `auth_failed`, `paused`, `realm_unserved`, `stopping`, or `stopped`. | | `state_reason` | string | No | Why the channel is in its state. | | `needs_owner` | boolean | Yes | Whether the channel still needs an owner enrolment code. | | `identity` | object | Yes | Bot account in the chat app. | | `identity.platform_id` | string | No | Platform identifier of the bot account. | | `identity.name` | string | No | Display name of the bot account. | | `identity.username` | string | No | Username of the bot account. | | `identity.team` | string | No | Slack only. Team where the app is installed. | | `identity.invite_url` | string | No | Discord only. Link that adds the bot to a server. | | `settings` | object | Yes | Settings explicitly set on this channel. Other settings are inherited. | | `effective` | object | Yes | Effective settings, their sources, and notes. | | `principals` | array | Yes | People paired with the channel. | | `chats` | array | Yes | Chats in which the bot is present. | | `last_error` | object | No | Last connection error. | | `last_error.code` | string | No | Machine-readable connection error code. | | `last_error.message` | string | No | Connection error message. | | `last_error.at` | string | No | Time of the error. | | `last_gap` | object | No | Last interval in which messages may have been lost. | | `last_gap.from` | string | Yes | Start of the interval in RFC 3339 format. | | `last_gap.to` | string | Yes | End of the interval in RFC 3339 format. | | `last_gap.possible` | boolean | No | Whether messages may have been lost. | | `created_at` | string | Yes | Creation time in RFC 3339 format. | | `enrolment` | object | No | Owner enrolment code returned only by the create operation. | | `enrolment.code` | string | No | One-time enrolment code. | | `enrolment.expires_at` | string | No | Expiration time in RFC 3339 format. | | `enrolment.instructions` | string | No | Instructions for using the code. | | `applied` | string | Yes | Required by update responses. `live` or `restart`. | | `warnings` | array | Yes | Required by update responses. Advisory notes about the applied change. | `state_reason` may be `identity_in_use`, `other_poller`, `webhook_set`, `stop_stuck`, `payload_too_large`, `credentials_missing`, `unauthorized`, `missing_scope`, `missing_intent`, `mismatched_app`, `unreachable`, `app_unverified`, `missing_access`, `guild_unavailable`, `message_content_missing`, `binding_changed`, `rate_limited`, `storage_failing`, `gateway_refused`, `lock_unavailable`, `lock_lost`, `channel_disabled`, `bot_paused`, or `not_running`. #### Principal fields | Field | Type | Required | Description | |---|---|---|---| | `principals[].id` | string | Yes | Person id on this channel. | | `principals[].platform_user` | string | Yes | User id in the chat app. | | `principals[].name` | string | No | Name assigned to the person. | | `principals[].rights` | array | Yes | Any subset of `chat`, `control`, and `gates`. | | `principals[].owner` | boolean | No | Whether the person owns the channel and has every right. | | `principals[].lang` | string | No | Person-specific language. | | `principals[].paired_at` | string | No | Pairing time in RFC 3339 format. | #### Chat fields | Field | Type | Required | Description | |---|---|---|---| | `chats[].id` | string | Yes | Chat id. | | `chats[].platform_chat` | string | No | Chat id in the chat app. | | `chats[].kind` | string | Yes | `dm` or `group`. | | `chats[].title` | string | No | Chat title in the chat app. | | `chats[].state` | string | Yes | Current chat state. | | `chats[].settings` | object | No | Settings set for this chat. | | `chats[].can_read` | boolean | No | Whether the bot sees every group message. It is absent when this is not known. | Effective settings may contain these notes: | Code | Field | Reason | Description | |---|---|---|---| | `hide_secrets_partial` | `hide_secrets` | `landlock` or `unsandboxed` | The agent's file tools refuse the secret files, but its shell can still read them. | | `telegram_privacy_on` | `group_mode` | `groups_get_only_messages_to_the_bot` | Telegram sends only commands and replies addressed to the bot. Turn privacy mode off with `@BotFather`, remove and re-add the bot, or make it a group administrator. | | `slack_history_scopes_missing` | `mention_only` | `unmentioned_messages_need_history_scopes` | The Slack bot token lacks `channels:history` or `groups:history`. Add the scopes and message events, reinstall the app, and provide the new token. | ### `GET /api/v1/agent/bots/{id}/channels` Lists the Bot's channels, including their state, paired people, chats, and effective settings. Credentials are never returned. The HTTP endpoint returns one page per request. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `page` | query | integer | No | One-based page number. | | `limit` | query | integer | No | Maximum items per page. `0` or omission means 8, and larger values are served as 8. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `items` | array | Yes | Channels in the requested page. Each item uses the channel object fields above. | | `meta` | object | Yes | Pagination metadata. | | `meta.total` | integer | No | Total number of channels across all pages. | | `meta.page` | integer | No | One-based page number. | | `meta.limit` | integer | No | Page size used by the request. | ### Request ```bash curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels?page=1&limit=8" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); for await (const item of client.agent.bots.channels.listIterator(botId, { page: 1, limit: 8 })) { console.log(item); } ``` ### Responses Media type: application/json ```json { "items": [ { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "team", "state": "awaiting_owner", "needs_owner": true, "identity": { "platform_id": "5151", "name": "Ops Bot", "username": "ops_helper_bot" }, "settings": {}, "effective": { "hide_secrets": { "value": true, "source": "default" }, "lang": { "value": "en", "source": "default" }, "notes": [] }, "principals": [], "chats": [], "created_at": "2026-10-14T10:00:00Z" } ], "meta": { "total": 1, "page": 1, "limit": 8 } } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot does not exist in the selected realm. | Verify the Bot id and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `POST /api/v1/agent/bots/{id}/channels` Connects a Bot to a chat app and stores the supplied credentials. The credentials are checked but never returned. A channel created with `enabled` set to `false`, or while the Bot's channels are paused, is only checked. It does not take the bot account and does not run until it is enabled and the Bot's channels run. Slack requires both a bot token beginning with `xoxb-` and an app token beginning with `xapp-`. A Telegram bot with a webhook is refused unless `delete_webhook` is `true`. Discord intents are not checked during creation and are reported in the channel state after it connects. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `Idempotency-Key` | header | string | No | Opaque retry key containing 1 to 255 printable ASCII characters without whitespace. Repeating the same create with the same key returns the same channel. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `kind` | string | Yes | Chat app: `discord`, `slack`, or `telegram`. | | `label` | string | No | Name assigned to the channel. | | `token` | string | Yes | Bot token. The value is write-only and is never returned. | | `app_token` | string | No | Slack only. App-level token beginning with `xapp-`. The value is write-only and is never returned. | | `settings` | object | No | Initial channel settings. Use the channel setting fields above. Unknown names are refused. `home_chat` is set later by an update. | | `delete_webhook` | boolean | No | Telegram only. Removes a configured webhook, including for a channel created with `enabled` set to `false`. Defaults to `false`. | | `enrolment` | object | No | Options for the owner enrolment code. | | `enrolment.make_home` | boolean | No | When the owner redeems the code, their direct message becomes the home chat. It only takes effect when an owner code is issued. Defaults to `false`. | ### Response fields The response uses the channel object fields above. It may also contain `enrolment.code`, `enrolment.expires_at`, and `enrolment.instructions` when an owner enrolment code is issued. The code is shown only in the response that creates the channel. ### Request ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: create-team-telegram-20261014" \ --data '{ "kind": "telegram", "label": "Team", "token": "TELEGRAM_BOT_TOKEN_PLACEHOLDER", "settings": { "dm_policy": "owner", "lang": "en" } }' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const channel = await client.agent.bots.channels.create(botId, { kind: 'telegram', label: 'Team', token: 'TELEGRAM_BOT_TOKEN_PLACEHOLDER', settings: { dm_policy: 'owner', lang: 'en' } }, { idempotencyKey: 'create-team-telegram-20261014' }); ``` ### Responses Media type: application/json ```json { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "Team", "state": "awaiting_owner", "needs_owner": true, "identity": { "platform_id": "5151", "name": "Ops Bot", "username": "ops_helper_bot" }, "settings": { "dm_policy": "owner", "lang": "en" }, "effective": { "dm_policy": { "value": "owner", "source": "channel" }, "lang": { "value": "en", "source": "channel" }, "notes": [] }, "principals": [], "chats": [], "created_at": "2026-10-14T10:00:00Z", "enrolment": { "code": "K7QXM2PA", "expires_at": "2026-10-14T10:15:00Z", "instructions": "Send K7QXM2PA to @ops_helper_bot in a direct message before 2026-10-14T10:15:00Z." } } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, or included an undeclared top-level body field. | Correct the request body and parameters, and remove undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot does not exist in the selected realm. | Verify the Bot id and realm selector. | Media type: application/json ```json { "code": "channel_conflict", "message": "the bot has a webhook set; send delete_webhook true to remove it", "details": { "reason": "webhook_set" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `channel_exists` | Channel exists | The Bot already has a channel for this bot account. | Use `details.channel_id` or delete the existing channel first. | | `channel_identity_in_use` | Identity in use | Another channel already runs this bot account. | Turn off or delete the other channel, or use another bot account. | | `channel_conflict` | Chat app conflict | The channel cannot be created as requested. `details.reason` may be `webhook_set` or `bot_paused`. Nothing was created. | For `webhook_set`, send `delete_webhook` as `true`. For `bot_paused`, resume the Bot's channels and send the request again. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "idempotency_replay_gone", "message": "the channel this Idempotency-Key created was deleted" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `idempotency_replay_gone` | Created channel deleted | The channel created by this `Idempotency-Key` has since been deleted. | Send the create with a new `Idempotency-Key`. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "channel_credentials_invalid", "message": "the chat app refused the credentials (unauthorized)", "details": { "kind": "telegram", "reason": "unauthorized" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `channel_credentials_invalid` | Credentials invalid | The chat app refused the credentials or could not be reached to check them. Nothing was stored. | Check the token and app token, then send them again. For a missing Slack scope, add it, reinstall the app, and provide the new token. | | `setting_invalid` | Setting invalid | A setting value is out of range, has the wrong type, is not settable at this scope, or is not available yet. Nothing was applied. | Correct the field named in `details` and send the create again. | | `setting_conflict` | Setting conflict | Two resulting settings contradict each other. Nothing was applied. | Change both settings together, or change the other setting first. | | `idempotency_key_reused` | Idempotency key reused | The `Idempotency-Key` was already used for a different channel create. Nothing was created. | Use a fresh key, or resend the identical create to retrieve its channel. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | | `channels_exhausted` | Limit reached | The Bot reached `max_channels`, or the channel reached `max_principals`. | Delete a channel or person first, or raise the limit. | | `idempotency_keys_exhausted` | Too many keys | Too many recent `Idempotency-Key` values are stored. | Retry later, or send the create without a key. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `GET /api/v1/agent/bots/{id}/channels/setup` Returns the steps for creating a bot account in Telegram, Slack, or Discord and the credential fields the create operation needs. Slack responses may include an app manifest. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `kind` | query | string | Yes | Chat app: `discord`, `slack`, or `telegram`. | | `name` | query | string | No | Name of the bot account to create. It is echoed in the response. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `kind` | string | Yes | Chat app: `discord`, `slack`, or `telegram`. | | `steps` | array | Yes | Ordered setup instructions. | | `needs` | array | Yes | Create fields that receive the credentials. | | `available` | boolean | Yes | Whether the agent can connect this chat app now. | | `name` | string | No | Name requested for the bot account. | | `manifest` | string | No | Slack only. JSON app manifest to paste while creating the app. | ### Request ```bash curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/setup?kind=telegram&name=Ops%20Bot" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const setup = await client.agent.bots.channels.getSetup(botId, { kind: 'telegram', name: 'Ops Bot' }); ``` ### Responses Media type: application/json ```json { "kind": "telegram", "name": "Ops Bot", "needs": [ "token" ], "available": true, "steps": [ "Open a chat with @BotFather in Telegram and send /newbot.", "Choose a display name and a username ending in \"bot\".", "Copy the token BotFather gives you.", "In groups Telegram sends the bot only commands for it and replies to it while its privacy mode is on: send /setprivacy to @BotFather and choose Disable, then remove the bot from the group and add it again; or make the bot an admin of the group." ] } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot does not exist in the selected realm. | Verify the Bot id and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `GET /api/v1/agent/bots/{id}/channels/{cid}` Gets one channel, its paired people, and its chats. Credentials are never returned. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields The response uses the channel object fields described under [Channel object fields](#channel-object-fields). ### Request ```bash curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const channel = await client.agent.bots.channels.get(botId, channelId); ``` ### Responses Media type: application/json ```json { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "team", "state": "awaiting_owner", "needs_owner": true, "identity": { "platform_id": "5151", "name": "Ops Bot", "username": "ops_helper_bot" }, "settings": {}, "effective": { "hide_secrets": { "value": true, "source": "default" }, "lang": { "value": "en", "source": "default" }, "notes": [] }, "principals": [], "chats": [], "created_at": "2026-10-14T10:00:00Z" } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `PATCH /api/v1/agent/bots/{id}/channels/{cid}` Renames a channel, turns it on or off, sets its home chat, or changes its settings. Turning a channel on takes the bot account again. If the channel cannot be enabled or a setting is refused, nothing changes. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `label` | string | No | New name for the channel. | | `enabled` | boolean | No | Turns the channel on or off. `settings.enabled` and `unset` entries for `enabled` are refused. | | `home_chat` | string | No | Chat that receives Bot updates. Send `null` to remove it. `settings.home_chat` and `unset` entries for `home_chat` are refused. | | `delete_webhook` | boolean | No | Telegram only, with `enabled` set to `true`. Removes the bot's webhook. | | `settings` | object | No | Settings to set. Use the channel setting fields above. `enabled` and `home_chat` are not settable here. | | `unset` | array of string | No | Settings to remove so they are inherited again. A name cannot be both set and unset. | `unset` accepts `dm_policy`, `group_mode`, `mention_only`, `default_rights`, `blocked_users`, `blocked_chats`, `allowed_chats`, `unpaired_reply`, `command_denied_reply`, `pairing_ttl_minutes`, `pairing_rights`, `max_principals`, `pairing_user_burn_tries`, `pairing_user_burn_minutes`, `pairing_code_burn_tries`, `gate_cards`, `gate_deciders`, `decide_in_groups`, `gate_detail`, `gate_ttl_minutes`, `push_events`, `push_detail`, `wake_replies`, `mirror_other_doors`, `typing`, `reply_style`, `format`, `parse_mode`, `part_chars`, `split_at`, `max_parts`, `overflow_note`, `lang`, `show_sender_name`, `no_reply_notice`, `delivery_expiry_hours`, `max_text_bytes`, `rate_user_per_min`, `rate_user_per_hour`, `rate_user_per_day`, `rate_chat_per_min`, `outbound_rate`, `reconnect_backoff_max_seconds`, `identify_per_hour`, `identify_per_day`, `connection_opens_per_hour`, `command_prefix`, `chat_commands`, `hide_secrets`, or `channel_lease`. ### Response fields The response uses the channel object fields described under [Channel object fields](#channel-object-fields). The `applied` and `warnings` fields are required on this update response. ### Request ```bash curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d" \ -H "Content-Type: application/json" \ --data '{"label":"Operations"}' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const channel = await client.agent.bots.channels.update(botId, channelId, { label: 'Operations' }); ``` ### Responses Media type: application/json ```json { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "Operations", "state": "awaiting_owner", "needs_owner": true, "identity": { "platform_id": "5151", "name": "Ops Bot", "username": "ops_helper_bot" }, "settings": {}, "effective": { "hide_secrets": { "value": true, "source": "default" }, "lang": { "value": "en", "source": "default" }, "notes": [] }, "principals": [], "chats": [], "created_at": "2026-10-14T10:00:00Z", "applied": "live", "warnings": [] } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, included an undeclared top-level body field, or tried to set `enabled` or `home_chat` in the wrong location. | Correct the request body and use the top-level `enabled` and `home_chat` fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "channel_conflict", "message": "the bot has a webhook set; send delete_webhook true to remove it", "details": { "reason": "webhook_set" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `channel_identity_in_use` | Identity in use | Another channel already runs this bot account. | Turn off or delete the other channel, or use another bot account. | | `channel_identity_changed` | Identity changed | The stored credentials now name another bot account. Nothing changed. | Replace the credentials with those of the channel's bot account, or create a channel for the other account. | | `channel_conflict` | Chat app conflict | The channel cannot be turned on as requested. `details.reason` may be `webhook_set` or `bot_paused`. Nothing changed. | For `webhook_set`, send `delete_webhook` as `true`. For `bot_paused`, resume the Bot's channels and send the change again. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "setting_invalid", "message": "setting max_channels refused: out_of_range" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `channel_credentials_invalid` | Credentials invalid | The chat app refused the stored credentials or could not be reached while the channel was being enabled. Nothing changed. | Check the stored credentials, replace them if necessary, and retry. | | `setting_invalid` | Setting invalid | A setting value is out of range, has the wrong type, is not settable at this scope, or is not available yet. Nothing was applied. | Correct the field named in `details` and send the change again. | | `setting_conflict` | Setting conflict | Two resulting settings contradict each other. Nothing was applied. | Change both settings together, or change the other setting first. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `DELETE /api/v1/agent/bots/{id}/channels/{cid}` Disconnects and deletes a channel, including its credentials, paired people, and chats. The request waits up to about 10 seconds for the connection to stop. If it stops in time, the response is `200`. Otherwise, the response is `202`, and the channel is deleted when its connection stops. A `503` response can mean either that the channel store is unavailable and the channel remains, or that the channel was deleted but its files could not be removed. Call `GET /api/v1/agent/bots/{id}/channels/{cid}` to distinguish them. A `200` means the channel remains, while `404` means it was deleted. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request ```bash curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const result = await client.agent.bots.channels.delete(botId, channelId); ``` ### Responses Media type: application/json ```json { "deleted": true } ``` Media type: application/json ```json { "deleted": false, "state": "stopping" } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The channel store is temporarily unavailable, or the channel was deleted but its files could not be removed. | Check the channel with `GET /api/v1/agent/bots/{id}/channels/{cid}` to determine whether it remains. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ## Credentials ### `PUT /api/v1/agent/bots/{id}/channels/{cid}/credentials` Checks and stores replacement credentials. The credentials must belong to the same bot account as the channel. Credentials are never returned. For Slack, omitting `app_token` keeps the stored app token and replaces only the bot token. Supplying `app_token` replaces and checks it. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `token` | string | Yes | New bot token. The value is write-only and is never returned. | | `app_token` | string | No | Slack only. New app-level token beginning with `xapp-`. When omitted, the stored app token is kept. The value is write-only and is never returned. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `applied` | string | Yes | `restart` means the channel restarted with the new credentials. `next_start` means the channel is not running or could not restart, and uses the credentials when it next starts. | ### Request ```bash curl -X PUT "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/credentials" \ -H "Content-Type: application/json" \ --data '{"token":"TELEGRAM_BOT_TOKEN_PLACEHOLDER"}' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const result = await client.agent.bots.channels.setCredentials(botId, channelId, { token: 'TELEGRAM_BOT_TOKEN_PLACEHOLDER' }); ``` ### Responses Media type: application/json ```json { "applied": "restart" } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, or included an undeclared top-level body field. | Correct the request body and remove undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `channel_identity_changed` | Identity changed | The new credentials belong to another bot account. Nothing changed. | Send credentials for the channel's bot account, or create a channel for the other account. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "channel_credentials_invalid", "message": "the chat app refused the credentials (unauthorized)", "details": { "kind": "telegram", "reason": "unauthorized" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `channel_credentials_invalid` | Credentials invalid | The chat app refused the credentials or could not be reached to check them. Nothing was stored. | Check the token and app token, then send them again. For a missing Slack scope, add it, reinstall the app, and provide the new token. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ## Chats ### `PATCH /api/v1/agent/bots/{id}/channels/{cid}/chats/{chat}` Approves or mutes a chat, or changes its settings. Approving a group requires `acknowledge_group_readers` set to `true`, because everyone in the group can then read the Bot's replies there. When a group asks to be approved, the bot sends each owner a direct message with Approve and Ignore buttons. Approve there performs the same action as this route with `acknowledge_group_readers` set to `true`. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `chat` | path | string | Yes | The chat. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `state` | string | No | `approved` lets the Bot answer there. `muted` prevents it from answering. | | `acknowledge_group_readers` | boolean | No | Required to approve a group because everyone in the group can read the Bot's replies there. | | `settings` | object | No | Chat settings to set. Send `null` for a setting to remove it and inherit the channel value. | | `settings.format` | string | No | `rich` or `plain`. | | `settings.mention_only` | boolean | No | In groups, reads only messages that address the Bot. When `false`, it reads every message in an approved group and needs the platform's message-content permission. | | `settings.rate_chat_per_min` | integer | No | Messages one chat may send per minute across all senders, from 0 to 600. `0` means no limit. | | `settings.rate_user_per_day` | integer | No | Messages one person may send per day, from 0 to 20000. `0` means no limit. | | `settings.rate_user_per_hour` | integer | No | Messages one person may send per hour, from 0 to 3600. `0` means no limit. | | `settings.rate_user_per_min` | integer | No | Messages one person may send per minute, from 0 to 600. `0` means no limit. | | `settings.reply_style` | string | No | `thread`, `reply`, or `plain`. | | `unset` | array of string | No | Chat settings to remove so they are inherited: `mention_only`, `reply_style`, `format`, `rate_user_per_min`, `rate_user_per_hour`, `rate_user_per_day`, or `rate_chat_per_min`. A name cannot be both set and unset. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `id` | string | Yes | Chat id. | | `platform_chat` | string | No | Chat id in the chat app. | | `kind` | string | Yes | `dm` or `group`. | | `title` | string | No | Chat title in the chat app. | | `state` | string | Yes | Current chat state. | | `settings` | object | Yes | Chat settings after the change. | | `applied` | string | Yes | `live` or `restart`. | | `warnings` | array | Yes | Advisory notes about the applied change. | ### Request ```bash curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/chats/chat_9a1be4c07d2f4c11" \ -H "Content-Type: application/json" \ --data '{ "settings": { "mention_only": true, "rate_chat_per_min": 30 } }' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const chat = await client.agent.bots.channels.updateChat(botId, channelId, chatId, { settings: { mention_only: true, rate_chat_per_min: 30 } }); ``` ### Responses Media type: application/json ```json { "id": "chat_9a1be4c07d2f4c11", "platform_chat": "-100123", "kind": "group", "title": "Team chat", "state": "approved", "settings": { "mention_only": true, "rate_chat_per_min": 30 }, "applied": "live", "warnings": [] } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, included an undeclared top-level body field, or set and unset the same name. | Correct the request body and remove the conflicting or undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot, channel, or chat does not exist in the selected realm. | Verify the Bot id, channel id, chat id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "acknowledgement_required", "message": "everyone in the group can read the Bot's replies there; send acknowledge_group_readers true to approve it" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `acknowledgement_required` | Acknowledgement required | Approving a group lets everyone in it read the Bot's replies there. | Send `acknowledge_group_readers` as `true` with the approval. | | `setting_invalid` | Setting invalid | A setting value is out of range, has the wrong type, is not settable at this scope, or is not available yet. Nothing was applied. | Correct the field named in `details` and send the change again. | | `setting_conflict` | Setting conflict | Two resulting settings contradict each other. Nothing was applied. | Change both settings together, or change the other setting first. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `DELETE /api/v1/agent/bots/{id}/channels/{cid}/chats/{chat}` Forgets a chat and its settings. If the bot remains in the chat, the chat appears again as a new request. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `chat` | path | string | Yes | The chat. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `deleted` | boolean | Yes | Whether the chat was forgotten. | ### Request ```bash curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/chats/chat_9a1be4c07d2f4c11" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const result = await client.agent.bots.channels.deleteChat(botId, channelId, chatId); ``` ### Responses Media type: application/json ```json { "deleted": true } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot, channel, or chat does not exist in the selected realm. | Verify the Bot id, channel id, chat id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ## Pairing ### `POST /api/v1/agent/bots/{id}/channels/{cid}/pairing` Creates a pairing code that a person sends to the bot in a direct message. The code replaces the previous code and is shown once. Set `owner` to `true` to create the first owner's enrolment code. An owner code is refused when the channel already has an owner. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `rights` | array of string | No | Rights granted by the code: `chat`, `control`, or `gates`. When omitted, the channel's `pairing_rights` applies. | | `make_home` | boolean | No | Makes the person's direct message the channel's home chat when the code is redeemed. | | `owner` | boolean | No | Creates the owner's code with every right. Refused when the channel already has an owner. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `code` | string | Yes | Pairing code, shown once. | | `expires_at` | string | Yes | Expiration time in RFC 3339 format. | | `instructions` | string | Yes | Instructions for sending the code to the bot. | ### Request ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/pairing" \ -H "Content-Type: application/json" \ --data '{"rights":["chat"]}' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const pairing = await client.agent.bots.channels.createPairing(botId, channelId, { rights: ['chat'] }); ``` ### Responses Media type: application/json ```json { "code": "K7QX-M2PA", "expires_at": "2026-10-14T10:15:00Z", "instructions": "Send K7QX-M2PA to @ops_helper_bot in a direct message before 2026-10-14T10:15:00Z." } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, or included an undeclared top-level body field. | Correct the request body and remove undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | | `channels_exhausted` | Limit reached | The Bot reached `max_channels`, or the channel reached `max_principals`. | Delete a channel or person first, or raise the limit. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `DELETE /api/v1/agent/bots/{id}/channels/{cid}/pairing` Cancels the current pairing code. The code stops working. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `cancelled` | boolean | Yes | Whether the pairing code was cancelled. | ### Request ```bash curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/pairing" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const result = await client.agent.bots.channels.cancelPairing(botId, channelId); ``` ### Responses Media type: application/json ```json { "cancelled": true } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ## People ### `POST /api/v1/agent/bots/{id}/channels/{cid}/principals` Pairs a person with a channel by their user id in the chat app, without using a pairing code. The first owner must pair with an owner code. After the channel has an owner, an owner can use this operation to transfer ownership. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `platform_user` | string | Yes | User id in the chat app. | | `name` | string | No | Name assigned to the person. | | `rights` | array of string | No | Rights granted to the person: `chat`, `control`, or `gates`. When omitted, the channel's `default_rights` applies. An empty array grants no rights. | | `owner` | boolean | No | Makes the person the owner with every right. The previous owner stops being the owner. Send no `rights` with this field. The first owner must pair with an owner code. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `id` | string | Yes | Person id on this channel. | | `platform_user` | string | Yes | User id in the chat app. | | `name` | string | No | Name assigned to the person. | | `rights` | array | Yes | Any subset of `chat`, `control`, and `gates`. | | `owner` | boolean | No | Whether the person owns the channel and has every right. | | `lang` | string | No | Person-specific language. | | `paired_at` | string | No | Pairing time in RFC 3339 format. | ### Request ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/principals" \ -H "Content-Type: application/json" \ --data '{ "platform_user": "424242", "name": "Jordan Lee", "rights": ["chat", "gates"] }' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const person = await client.agent.bots.channels.addPrincipal(botId, channelId, { platform_user: '424242', name: 'Jordan Lee', rights: ['chat', 'gates'] }); ``` ### Responses Media type: application/json ```json { "id": "prn_3f2a9c1e5b7d40a1", "owner": false, "paired_at": "2026-10-14T10:00:00Z", "platform_user": "424242", "name": "Jordan Lee", "rights": ["chat", "gates"] } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, or included an undeclared top-level body field. | Correct the request body and remove undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot or channel does not exist in the selected realm. | Verify the Bot id, channel id, and realm selector. | Media type: application/json ```json { "code": "owner_needs_pairing", "message": "this channel has no owner yet: its first owner pairs with an owner code" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `owner_needs_pairing` | Owner needs pairing | The channel has no owner, and its first owner must pair with an owner code. | Create a pairing code with `owner` set to `true` and have the person send it to the bot. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | | `channels_exhausted` | Limit reached | The Bot reached `max_channels`, or the channel reached `max_principals`. | Delete a channel or person first, or raise the limit. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `PATCH /api/v1/agent/bots/{id}/channels/{cid}/principals/{pid}` Changes a paired person's rights, language, name, or ownership. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `pid` | path | string | Yes | The principal id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `rights` | array of string | No | Rights granted to the person: `chat`, `control`, or `gates`. | | `lang` | string | No | Person-specific language: `en`, `de`, `fr`, `es`, `pt`, `it`, `ja`, `zh`, or `null`. Send `null` to remove it and use the channel language. Omit it to leave it unchanged. | | `name` | string | No | New name for the person. | | `owner` | boolean | No | Makes the person the owner and removes ownership from the previous owner. The first owner must pair with an owner code. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `id` | string | Yes | Person id on this channel. | | `platform_user` | string | Yes | User id in the chat app. | | `name` | string | No | Name assigned to the person. | | `rights` | array | Yes | Any subset of `chat`, `control`, and `gates`. | | `owner` | boolean | No | Whether the person owns the channel and has every right. | | `lang` | string | No | Person-specific language. | | `paired_at` | string | No | Pairing time in RFC 3339 format. | ### Request ```bash curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/principals/prn_3f2a9c1e5b7d40a1" \ -H "Content-Type: application/json" \ --data '{"rights":["chat","gates"]}' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const person = await client.agent.bots.channels.updatePrincipal(botId, channelId, principalId, { rights: ['chat', 'gates'] }); ``` ### Responses Media type: application/json ```json { "id": "prn_3f2a9c1e5b7d40a1", "owner": false, "paired_at": "2026-10-14T10:00:00Z", "platform_user": "424242", "name": "Jordan Lee", "rights": ["chat", "gates"] } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed, carried invalid parameters, or included an undeclared top-level body field. | Correct the request body and remove undeclared fields. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot, channel, or person does not exist in the selected realm. | Verify the Bot id, channel id, principal id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `owner_needs_pairing` | Owner needs pairing | The channel has no owner, and its first owner must pair with an owner code. | Create a pairing code with `owner` set to `true` and have the person send it to the bot. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `payload_too_large` | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit. | Media type: application/json ```json { "code": "setting_invalid", "message": "setting max_channels refused: out_of_range" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `setting_invalid` | Setting invalid | A person setting is out of range, has the wrong type, is not settable at this scope, or is not available yet. Nothing was applied. | Correct the field named in `details` and send the change again. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. | ### `DELETE /api/v1/agent/bots/{id}/channels/{cid}/principals/{pid}` Unpairs a person and removes their stored rights. With `dm_policy` set to `open`, an unpaired person can still message the Bot as a guest. Add the person's platform user id to `blocked_users` to stop their messages. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | The Bot id. | | `cid` | path | string | Yes | The channel id. | | `pid` | path | string | Yes | The principal id. | | `X-Hoody-Realm` | header | string | No | Per-request realm selector. Use `global` or a 24-character hexadecimal realm id. | | `realm` | query | string | No | Query alias for `X-Hoody-Realm`, read only when the header is absent. Use `global` or a 24-character hexadecimal realm id. | ### Response fields | Field | Type | Required | Description | |---|---|---|---| | `deleted` | boolean | Yes | Whether the person was unpaired. | ### Request ```bash curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/principals/prn_3f2a9c1e5b7d40a1" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' }); const result = await client.agent.bots.channels.removePrincipal(botId, channelId, principalId); ``` ### Responses Media type: application/json ```json { "deleted": true } ``` Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `bad_request` | Bad request | The request was malformed or carried invalid parameters. This endpoint does not accept a request body. | Correct the request parameters and send the request without a body. | | `realm_scope_unsupported` | Realm scope unsupported | The requested realm scope is not supported, or the agent is pinned to another realm. | Omit the realm scope or use the realm to which the agent is pinned. | | `invalid_realm` | Invalid realm selector | The realm selector is malformed. | Pass `global` or a 24-character hexadecimal realm id. | Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `forbidden` | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. | Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `not_found` | Not found | The Bot, channel, or person does not exist in the selected realm. | Verify the Bot id, channel id, principal id, and realm selector. | Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `realm_blocked` | Realm blocked | The selected realm is blocked or corrupt. The request fails before dispatch. | Select a valid, reachable realm. | | `bot_owned_elsewhere` | Bot served by another agent | Another agent process serves the Bot, or its owner lock cannot be taken. Nothing was read or changed. | Retry after `Retry-After`, or use the agent that serves the Bot. | Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `rate_limited` | Too many requests | The per-client request rate limit was exceeded. | Honor `Retry-After` and retry at a lower rate. | Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `internal_error` | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. | Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `service_unavailable` | Service unavailable | The agent could not service the request, or the Bot's channel store is temporarily unavailable. | Honor `Retry-After` and retry. | | `restriction_unknown` | Login restriction unknown | The agent cannot yet read which realms the login may serve, so it refuses the realm-scoped request. | Retry after the restriction becomes readable. |