Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

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 for the Bot that a channel reaches and Set up a chat app 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.

GET /api/v1/agent/bots/{id}/channel-settings

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
settingsobjectYesSettings explicitly set on the Bot. Other settings use their default.
settings.channels_pausedbooleanNoStops every chat app of the Bot while preserving each channel’s own enabled value.
settings.hide_secretsbooleanNoHides stored chat-app credentials from the agent’s tools and, where supported, from shells started afterwards. It does not stop root or sudo.
settings.langstringNoLanguage of fixed lines: en, de, fr, es, pt, it, ja, or zh. The Bot’s answers are not translated.
settings.max_channelsintegerNoMaximum number of chat apps, from 1 to 8.
settings.rate_bot_per_dayintegerNoMessages all chat apps may deliver each day, from 0 to 3000. 0 means no limit.
settings.shared_identitystringNoWhether several Bots may share one chat app. Only off is available.
effectiveobjectYesEffective settings and their sources.
effective.channels_pausedobjectNoEffective value and source for channels_paused.
effective.channels_paused.valuebooleanYesEffective value.
effective.channels_paused.sourcestringYesEither bot or default.
effective.hide_secretsobjectNoEffective value and source for hide_secrets.
effective.hide_secrets.valuebooleanYesEffective value.
effective.hide_secrets.sourcestringYesEither bot or default.
effective.langobjectNoEffective value and source for lang.
effective.lang.valuestringYesOne of en, de, fr, es, pt, it, ja, or zh.
effective.lang.sourcestringYesEither bot or default.
effective.max_channelsobjectNoEffective value and source for max_channels.
effective.max_channels.valueintegerYesEffective value, from 1 to 8.
effective.max_channels.sourcestringYesEither bot or default.
effective.rate_bot_per_dayobjectNoEffective value and source for rate_bot_per_day.
effective.rate_bot_per_day.valueintegerYesEffective value, from 0 to 3000.
effective.rate_bot_per_day.sourcestringYesEither bot or default.
effective.shared_identityobjectNoEffective value and source for shared_identity.
effective.shared_identity.valuestringYesAlways off.
effective.shared_identity.sourcestringYesEither bot or default.
effective.notesarrayYesNotes about effective values.
effective.notes[].codestringYesWhat the note concerns.
effective.notes[].fieldstringYesThe setting concerned.
effective.notes[].reasonstringNoAdditional reason, when the code has one.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channel-settings"

Media type: application/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": []
}
}

PATCH /api/v1/agent/bots/{id}/channel-settings

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
channels_pausedbooleanNoStops every chat app of the Bot while preserving each channel’s own enabled value. Send null to remove the setting.
hide_secretsbooleanNoHides 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.
langstringNoFixed-line language: en, de, fr, es, pt, it, ja, zh, or null. The Bot’s answers are not translated.
max_channelsintegerNoMaximum number of chat apps, from 1 to 8. Send null to remove the setting.
rate_bot_per_dayintegerNoMessages all chat apps may deliver each day, from 0 to 3000. 0 means no limit. Send null to remove the setting.
shared_identitystringNoWhether several Bots may share one chat app. Only off or null is available.
unsetarray of stringNoSettings to restore to their defaults: lang, rate_bot_per_day, hide_secrets, channels_paused, shared_identity, or max_channels.

The response contains the Bot settings and effective values described by GET /api/v1/agent/bots/{id}/channel-settings, plus these required fields:

FieldTypeRequiredDescription
appliedstringYeslive means the settings are in effect now. restart means they take effect after the channels reconnect.
warningsarrayYesAdvisory notes about the new settings.
Terminal window
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"}'

Media type: application/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": []
}

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.<field>.value and effective.<field>.source; both are required. The source is bot, channel, or default.

FieldRequest typeEffective value typeAllowed values and limitsDescription
allowed_chatsarray or nullarrayPlatform chat ids, at most 200When not empty, only these chats are served. With group_mode set to allowlist, only listed groups approved by the owner are served.
blocked_chatsarray or nullarrayPlatform chat ids, at most 200Messages from these chats are dropped.
blocked_usersarray or nullarrayPlatform user ids, at most 200Messages from these users are dropped in every chat.
channel_leaseboolean or nullbooleantrue or falseKeeps the agent running while the chat app is enabled. When false, an open Bot session still keeps it running.
chat_commandsarray or nullarrayAny subset of status, stop, bind, unbind, and helpCommands that work. A command not listed is treated as ordinary text.
command_denied_replystring or nullstringhint or silentWhat a sender without the control right hears when sending a command. hint sends one line per hour per sender and chat.
command_prefixstring or nullstring!, ., ;, ~, or /Character that starts a chat command. Telegram defaults to /; other platforms default to !.
connection_opens_per_hourinteger or nullinteger1 to 120Slack only. Connections the channel may open per hour, including failed attempts.
decide_in_groupsboolean or nullbooleantrue or falseWhether approvals may be shown and decided in a group chat.
default_rightsarray or nullarrayAny subset of chat, control, and gatesRights given to a person added to the allowlist. It is also the default for pairing_rights. Open guests can only chat.
delivery_expiry_hoursinteger or nullinteger1 to 168Hours after which an answer that could not be delivered is abandoned.
dm_policystring or nullstringowner, allowlist, pairing, or openControls 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.
enabledboolean or nullbooleantrue or falseRuns the chat app. When false, it stops and sends nothing. Set this only through the top-level enabled field of a channel update.
formatstring or nullstringrich or plainSends answers with platform markup or as plain text.
gate_cardsstring or nullstringon, links, or offControls how an approval is presented: a card with buttons, a card with text only, or no card. gate_deciders controls who may decide.
gate_decidersstring or nullstringnone, owner, named, or principalsControls who may decide approvals: nobody, owners, people with the gates right, or everyone with the chat right. A guest never decides.
gate_detailstring or nullstringsummary or minimalControls whether an approval card shows a summary or only the tool name.
gate_ttl_minutesinteger or nullinteger0 to 10080Minutes before an approval card expires. 0 means it never expires.
group_modestring or nullstringoff, owner_approves, allowlist, or openControls 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_secretsboolean or nullbooleantrue or falseHides stored chat-app credentials from the agent’s tools and, where supported, from shells started afterwards. It does not stop root or sudo.
home_chatstring or nullstringA direct-message or approved-group chat idChat 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_dayinteger or nullinteger1 to 500Discord only. Gateway logins the channel may attempt per day.
identify_per_hourinteger or nullinteger1 to 60Discord only. Gateway logins the channel may attempt per hour.
langstring or nullstringen, de, fr, es, pt, it, ja, or zhLanguage of fixed lines. The Bot’s answers are not translated.
max_partsinteger or nullinteger1 to 20Maximum number of parts used to send one answer. Longer answers are cut.
max_principalsinteger or nullinteger1 to 32Maximum number of people kept by a channel. Pairing, allowlist additions, and owner enrolment beyond the limit are refused.
max_text_bytesinteger or nullinteger256 to 65536Longest accepted message in bytes. A character outside basic Latin uses 2 to 4 bytes.
mention_onlyboolean or nullbooleantrue or falseIn 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_doorsboolean or nullbooleantrue or falseSends replies to messages from other places to the home chat.
no_reply_noticeboolean or nullbooleantrue or falseSends one line when a Bot turn ends without an answer.
outbound_ratenumber or nullnumberAt least 0.001 and no more than the platform limitMessages per second sent to one chat. The platform limit is the default.
overflow_noteboolean or nullbooleantrue or falseEnds a cut answer with a line saying it continues in the session.
pairing_code_burn_triesinteger or nullinteger5 to 200Total wrong codes allowed before the active code stops working.
pairing_rightsarray or nullarrayAny subset of chat, control, and gatesRights granted by a pairing code that names no rights. When unset, default_rights applies.
pairing_ttl_minutesinteger or nullinteger1 to 1440Minutes that a pairing or owner-enrolment code remains valid.
pairing_user_burn_minutesinteger or nullinteger1 to 1440Minutes that a person who sent too many wrong codes is refused. A correct code is refused during this period.
pairing_user_burn_triesinteger or nullinteger1 to 20Wrong codes one person may send before that person is refused.
parse_modestring or nullstringhtml or plainTelegram only. Markup used for rich answers.
part_charsinteger or nullinteger200 to the platform limitpart_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_detailstring or nullstringbrief or fullControls 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_eventsarray or nullarrayAny subset of report, gate, gone, stop, waiter, limit, budget, error, provider, not_sent, and resetBot updates sent to the home chat on their own.
rate_chat_per_mininteger or nullinteger0 to 600Messages one chat may send per minute across all senders. 0 means no limit.
rate_user_per_dayinteger or nullinteger0 to 20000Messages one person may send per day. 0 means no limit.
rate_user_per_hourinteger or nullinteger0 to 3600Messages one person may send per hour. 0 means no limit.
rate_user_per_mininteger or nullinteger0 to 600Messages one person may send per minute. 0 means no limit.
reconnect_backoff_max_secondsinteger or nullinteger5 to 600Longest normal reconnect wait in seconds. A connection-open limit or platform retry delay may cause a longer wait.
reply_stylestring or nullstringthread, reply, or plainControls how an answer is attached to the message it answers.
show_sender_nameboolean or nullbooleantrue or falseGives the Bot the sender’s display name with group messages. It is an unverified hint and direct messages never carry it.
split_atstring or nullstringparagraph, line, or wordControls where a long answer is split into parts.
typingboolean or nullbooleantrue or falseShows a typing indicator while the Bot works. Telegram and Discord support it; Slack does not.
unpaired_replystring or nullstringhint or silentWhat 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_repliesboolean or nullbooleantrue or falseSends replies to the Bot’s own updates to the home chat.

These fields apply to a single channel and to each item in a channel list.

FieldTypeRequiredDescription
idstringYesChannel id.
kindstringYesChat app: discord, slack, or telegram.
labelstringYesName assigned to the channel.
statestringYesconnecting, connected, awaiting_owner, degraded, standby, conflict, auth_failed, paused, realm_unserved, stopping, or stopped.
state_reasonstringNoWhy the channel is in its state.
needs_ownerbooleanYesWhether the channel still needs an owner enrolment code.
identityobjectYesBot account in the chat app.
identity.platform_idstringNoPlatform identifier of the bot account.
identity.namestringNoDisplay name of the bot account.
identity.usernamestringNoUsername of the bot account.
identity.teamstringNoSlack only. Team where the app is installed.
identity.invite_urlstringNoDiscord only. Link that adds the bot to a server.
settingsobjectYesSettings explicitly set on this channel. Other settings are inherited.
effectiveobjectYesEffective settings, their sources, and notes.
principalsarrayYesPeople paired with the channel.
chatsarrayYesChats in which the bot is present.
last_errorobjectNoLast connection error.
last_error.codestringNoMachine-readable connection error code.
last_error.messagestringNoConnection error message.
last_error.atstringNoTime of the error.
last_gapobjectNoLast interval in which messages may have been lost.
last_gap.fromstringYesStart of the interval in RFC 3339 format.
last_gap.tostringYesEnd of the interval in RFC 3339 format.
last_gap.possiblebooleanNoWhether messages may have been lost.
created_atstringYesCreation time in RFC 3339 format.
enrolmentobjectNoOwner enrolment code returned only by the create operation.
enrolment.codestringNoOne-time enrolment code.
enrolment.expires_atstringNoExpiration time in RFC 3339 format.
enrolment.instructionsstringNoInstructions for using the code.
appliedstringYesRequired by update responses. live or restart.
warningsarrayYesRequired 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.

FieldTypeRequiredDescription
principals[].idstringYesPerson id on this channel.
principals[].platform_userstringYesUser id in the chat app.
principals[].namestringNoName assigned to the person.
principals[].rightsarrayYesAny subset of chat, control, and gates.
principals[].ownerbooleanNoWhether the person owns the channel and has every right.
principals[].langstringNoPerson-specific language.
principals[].paired_atstringNoPairing time in RFC 3339 format.
FieldTypeRequiredDescription
chats[].idstringYesChat id.
chats[].platform_chatstringNoChat id in the chat app.
chats[].kindstringYesdm or group.
chats[].titlestringNoChat title in the chat app.
chats[].statestringYesCurrent chat state.
chats[].settingsobjectNoSettings set for this chat.
chats[].can_readbooleanNoWhether the bot sees every group message. It is absent when this is not known.

Effective settings may contain these notes:

CodeFieldReasonDescription
hide_secrets_partialhide_secretslandlock or unsandboxedThe agent’s file tools refuse the secret files, but its shell can still read them.
telegram_privacy_ongroup_modegroups_get_only_messages_to_the_botTelegram 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_missingmention_onlyunmentioned_messages_need_history_scopesThe Slack bot token lacks channels:history or groups:history. Add the scopes and message events, reinstall the app, and provide the new token.

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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
pagequeryintegerNoOne-based page number.
limitqueryintegerNoMaximum items per page. 0 or omission means 8, and larger values are served as 8.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
itemsarrayYesChannels in the requested page. Each item uses the channel object fields above.
metaobjectYesPagination metadata.
meta.totalintegerNoTotal number of channels across all pages.
meta.pageintegerNoOne-based page number.
meta.limitintegerNoPage size used by the request.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels?page=1&limit=8"

Media type: application/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
}
}

Connects a Bot to a chat app and stores the supplied credentials. The credentials are checked but never returned.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
Idempotency-KeyheaderstringNoOpaque 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-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
kindstringYesChat app: discord, slack, or telegram.
labelstringNoName assigned to the channel.
tokenstringYesBot token. The value is write-only and is never returned.
app_tokenstringNoSlack only. App-level token beginning with xapp-. The value is write-only and is never returned.
settingsobjectNoInitial channel settings. Use the channel setting fields above. Unknown names are refused. home_chat is set later by an update.
delete_webhookbooleanNoTelegram only. Removes a configured webhook, including for a channel created with enabled set to false. Defaults to false.
enrolmentobjectNoOptions for the owner enrolment code.
enrolment.make_homebooleanNoWhen 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.

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.

Terminal window
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"
}
}'

Media type: application/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."
}
}

GET /api/v1/agent/bots/{id}/channels/setup

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
kindquerystringYesChat app: discord, slack, or telegram.
namequerystringNoName of the bot account to create. It is echoed in the response.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
kindstringYesChat app: discord, slack, or telegram.
stepsarrayYesOrdered setup instructions.
needsarrayYesCreate fields that receive the credentials.
availablebooleanYesWhether the agent can connect this chat app now.
namestringNoName requested for the bot account.
manifeststringNoSlack only. JSON app manifest to paste while creating the app.
Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/setup?kind=telegram&name=Ops%20Bot"

Media type: application/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."
]
}

GET /api/v1/agent/bots/{id}/channels/{cid}

Section titled “GET /api/v1/agent/bots/{id}/channels/{cid}”

Gets one channel, its paired people, and its chats. Credentials are never returned.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.

The response uses the channel object fields described under Channel object fields.

Terminal window
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d"

Media type: application/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"
}

PATCH /api/v1/agent/bots/{id}/channels/{cid}

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
labelstringNoNew name for the channel.
enabledbooleanNoTurns the channel on or off. settings.enabled and unset entries for enabled are refused.
home_chatstringNoChat that receives Bot updates. Send null to remove it. settings.home_chat and unset entries for home_chat are refused.
delete_webhookbooleanNoTelegram only, with enabled set to true. Removes the bot’s webhook.
settingsobjectNoSettings to set. Use the channel setting fields above. enabled and home_chat are not settable here.
unsetarray of stringNoSettings 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.

The response uses the channel object fields described under Channel object fields. The applied and warnings fields are required on this update response.

Terminal window
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"}'

Media type: application/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": []
}

DELETE /api/v1/agent/bots/{id}/channels/{cid}

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d"

Media type: application/json

{
"deleted": true
}

PUT /api/v1/agent/bots/{id}/channels/{cid}/credentials

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
tokenstringYesNew bot token. The value is write-only and is never returned.
app_tokenstringNoSlack 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.
FieldTypeRequiredDescription
appliedstringYesrestart 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.
Terminal window
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"}'

Media type: application/json

{
"applied": "restart"
}

PATCH /api/v1/agent/bots/{id}/channels/{cid}/chats/{chat}

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
chatpathstringYesThe chat.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
statestringNoapproved lets the Bot answer there. muted prevents it from answering.
acknowledge_group_readersbooleanNoRequired to approve a group because everyone in the group can read the Bot’s replies there.
settingsobjectNoChat settings to set. Send null for a setting to remove it and inherit the channel value.
settings.formatstringNorich or plain.
settings.mention_onlybooleanNoIn 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_minintegerNoMessages one chat may send per minute across all senders, from 0 to 600. 0 means no limit.
settings.rate_user_per_dayintegerNoMessages one person may send per day, from 0 to 20000. 0 means no limit.
settings.rate_user_per_hourintegerNoMessages one person may send per hour, from 0 to 3600. 0 means no limit.
settings.rate_user_per_minintegerNoMessages one person may send per minute, from 0 to 600. 0 means no limit.
settings.reply_stylestringNothread, reply, or plain.
unsetarray of stringNoChat 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.
FieldTypeRequiredDescription
idstringYesChat id.
platform_chatstringNoChat id in the chat app.
kindstringYesdm or group.
titlestringNoChat title in the chat app.
statestringYesCurrent chat state.
settingsobjectYesChat settings after the change.
appliedstringYeslive or restart.
warningsarrayYesAdvisory notes about the applied change.
Terminal window
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
}
}'

Media type: application/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": []
}

DELETE /api/v1/agent/bots/{id}/channels/{cid}/chats/{chat}

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
chatpathstringYesThe chat.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
deletedbooleanYesWhether the chat was forgotten.
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/chats/chat_9a1be4c07d2f4c11"

Media type: application/json

{
"deleted": true
}

POST /api/v1/agent/bots/{id}/channels/{cid}/pairing

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
rightsarray of stringNoRights granted by the code: chat, control, or gates. When omitted, the channel’s pairing_rights applies.
make_homebooleanNoMakes the person’s direct message the channel’s home chat when the code is redeemed.
ownerbooleanNoCreates the owner’s code with every right. Refused when the channel already has an owner.
FieldTypeRequiredDescription
codestringYesPairing code, shown once.
expires_atstringYesExpiration time in RFC 3339 format.
instructionsstringYesInstructions for sending the code to the bot.
Terminal window
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"]}'

Media type: application/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."
}

DELETE /api/v1/agent/bots/{id}/channels/{cid}/pairing

Section titled “DELETE /api/v1/agent/bots/{id}/channels/{cid}/pairing”

Cancels the current pairing code. The code stops working.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
cancelledbooleanYesWhether the pairing code was cancelled.
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/pairing"

Media type: application/json

{
"cancelled": true
}

POST /api/v1/agent/bots/{id}/channels/{cid}/principals

Section titled “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.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
platform_userstringYesUser id in the chat app.
namestringNoName assigned to the person.
rightsarray of stringNoRights granted to the person: chat, control, or gates. When omitted, the channel’s default_rights applies. An empty array grants no rights.
ownerbooleanNoMakes 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.
FieldTypeRequiredDescription
idstringYesPerson id on this channel.
platform_userstringYesUser id in the chat app.
namestringNoName assigned to the person.
rightsarrayYesAny subset of chat, control, and gates.
ownerbooleanNoWhether the person owns the channel and has every right.
langstringNoPerson-specific language.
paired_atstringNoPairing time in RFC 3339 format.
Terminal window
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"]
}'

Media type: application/json

{
"id": "prn_3f2a9c1e5b7d40a1",
"owner": false,
"paired_at": "2026-10-14T10:00:00Z",
"platform_user": "424242",
"name": "Jordan Lee",
"rights": ["chat", "gates"]
}

PATCH /api/v1/agent/bots/{id}/channels/{cid}/principals/{pid}

Section titled “PATCH /api/v1/agent/bots/{id}/channels/{cid}/principals/{pid}”

Changes a paired person’s rights, language, name, or ownership.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
pidpathstringYesThe principal id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
rightsarray of stringNoRights granted to the person: chat, control, or gates.
langstringNoPerson-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.
namestringNoNew name for the person.
ownerbooleanNoMakes the person the owner and removes ownership from the previous owner. The first owner must pair with an owner code.
FieldTypeRequiredDescription
idstringYesPerson id on this channel.
platform_userstringYesUser id in the chat app.
namestringNoName assigned to the person.
rightsarrayYesAny subset of chat, control, and gates.
ownerbooleanNoWhether the person owns the channel and has every right.
langstringNoPerson-specific language.
paired_atstringNoPairing time in RFC 3339 format.
Terminal window
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"]}'

Media type: application/json

{
"id": "prn_3f2a9c1e5b7d40a1",
"owner": false,
"paired_at": "2026-10-14T10:00:00Z",
"platform_user": "424242",
"name": "Jordan Lee",
"rights": ["chat", "gates"]
}

DELETE /api/v1/agent/bots/{id}/channels/{cid}/principals/{pid}

Section titled “DELETE /api/v1/agent/bots/{id}/channels/{cid}/principals/{pid}”

Unpairs a person and removes their stored rights.

NameInTypeRequiredDescription
idpathstringYesThe Bot id.
cidpathstringYesThe channel id.
pidpathstringYesThe principal id.
X-Hoody-RealmheaderstringNoPer-request realm selector. Use global or a 24-character hexadecimal realm id.
realmquerystringNoQuery alias for X-Hoody-Realm, read only when the header is absent. Use global or a 24-character hexadecimal realm id.
FieldTypeRequiredDescription
deletedbooleanYesWhether the person was unpaired.
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/bot_2f4c9a7e1d3b/channels/ch_1a2b3c4d/principals/prn_3f2a9c1e5b7d40a1"

Media type: application/json

{
"deleted": true
}