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

Every chat app setting has a safe default. Change only what you need.

Settings live at three levels:

  • Bot: applies to every chat app of the Bot. Read and change it with GET and PATCH /api/v1/agent/bots/{id}/channel-settings.
  • Chat app: one connection to Telegram, Slack or Discord. Change it with PATCH /api/v1/agent/bots/{id}/channels/{cid} and a settings object. enabled and home_chat go beside settings, not inside it.
  • Chat: one direct message or group the chat app knows. Change it with PATCH /api/v1/agent/bots/{id}/channels/{cid}/chats/{chat} and a settings object.

In the Hub, open Bots, select the Bot and open the Chat apps tab. For the Bot level, choose More actions > Settings for all chat apps. For one chat app, press Manage on its row and open Settings (Main settings, then All settings for the rest). For one chat, open the Chats section of the chat app and choose Chat settings on its row. Save with Save settings. hide_secrets, shared_identity and channel_lease are shown read-only there.

A value set on a chat overrides the chat app’s value, subject to platform capability checks. The answers of the Bot’s settings (GET and PATCH) and of a chat app (create, list, GET and PATCH) carry effective: the value in force for each setting and where it comes from (source). A chat’s answer has no effective: it carries the chat’s own stored settings, with applied and warnings. On Discord, a stored mention_only: false stays effectively true, including as a chat override, until Message Content Intent is known to be available.

To remove an override: on a chat app or a chat, send the setting as null inside settings; on the Bot, list its name in unset. The inherited value or default then applies. Two chat app fields go beside settings: send home_chat: null to remove the home chat, and enabled: true to turn the chat app back on, which is the default. enabled: null leaves its current value unchanged.

Applies says when a change takes effect: at once, or after the chat app reconnects (the answer says applied: "restart"). Connection limits can delay reconnection.

56 settings in total.

Who can talk to the Bot, in which chats.

SettingDefaultValuesSet onAppliesWhat it does
allowed_chatsemptylist, at most 200chat appat onceWhen not empty, only these platform chat ids are served; with group_mode allowlist only the listed groups the owner has approved are served (at most 200).
blocked_chatsemptylist, at most 200chat appat oncePlatform chat ids whose messages are dropped (at most 200).
blocked_usersemptylist, at most 200chat appat oncePlatform user ids whose messages are dropped in every chat, whatever the other access settings say (at most 200).
command_denied_reply"hint""hint", "silent"chat appat onceWhat an admitted sender hears when the chat app refuses their command, for example without the control right: hint (one line per hour per sender and chat) or silent. The help command answers either way.
default_rights["chat"]list of "chat", "control", "gates"chat appat onceRights a person gets when added to the allowlist, and the default for pairing_rights: any subset of chat, control, gates. Open guests can only chat.
dm_policy"owner""owner", "allowlist", "pairing", "open"chat appat onceWho may talk to the Bot in a direct message: owner (owners only), allowlist (people the owner added or paired; they may talk only if their rights include chat), pairing (a person with a valid pairing code is added, and may talk to the Bot only if the code grants chat), open (anyone; a person not paired is a guest, people already paired keep their rights).
group_mode"owner_approves""off", "owner_approves", "allowlist", "open"chat appat onceHow group chats are admitted: off (groups are ignored), owner_approves (after the owner approves the group), allowlist (only groups listed in allowed_chats, once the owner has approved them), open (any group, without approval; while mention_only is true only messages that address the Bot are read; unpaired members are guests, people already paired keep their rights).
max_principals81 to 32chat appat onceMost people a chat app keeps (1 to 32); pairing, an allowlist add and owner enrolment beyond it are refused.
mention_onlytruetrue, falsechat app, chatat onceIn a group, read only messages that address the Bot (a mention, a reply to the Bot, or the command prefix). false reads every message of an approved group or an open group and needs the platform’s message-content permission.
pairing_code_burn_tries205 to 200chat appat onceWrong codes in total before the active code stops working (5 to 200).
pairing_rightssame as default_rightslist of "chat", "control", "gates"chat appat onceRights a pairing code grants when the request names none: a subset of chat, control, gates. Unset, it follows default_rights.
pairing_ttl_minutes151 to 1440chat appat onceHow long a pairing or owner enrolment code stays valid, in minutes (1 to 1440).
pairing_user_burn_minutes601 to 1440chat appat onceHow long a person who sent too many wrong codes is refused, in minutes (1 to 1440); a correct code is refused too.
pairing_user_burn_tries51 to 20chat appat onceWrong codes from one person before that person is refused for pairing_user_burn_minutes (1 to 20).
unpaired_reply"hint""hint", "silent"chat appat onceWhat a sender who may not talk to the Bot hears: hint (one line per hour asking them to get a pairing code from the owner) or silent.

How approval and question cards are sent and who may decide them.

SettingDefaultValuesSet onAppliesWhat it does
decide_in_groupsfalsetrue, falsechat appat onceWhether approvals may be shown and decided in a group chat. false keeps cards, gate updates and gate decisions out of groups.
gate_cards"on""on", "links", "off"chat appat onceHow a pending approval is shown: on (a card with buttons), links (a card with the text only), off (no card). Presentation only: who may decide is gate_deciders.
gate_deciders"owner""none", "owner", "named", "principals"chat appat onceWho may decide an approval from this chat app: none, owner (owners), named (people with the gates right), principals (everyone with the chat right). A guest never decides.
gate_detail"summary""summary", "minimal"chat appat onceWhat an approval card shows: summary (the tool, the target and shortened details) or minimal (the tool name only).
gate_ttl_minutes00 or 1 to 10080chat appat onceMinutes after which an approval card is shown as expired and its buttons refuse (0 = never, else 1 to 10080).

What the Bot sends on its own, and where.

SettingDefaultValuesSet onAppliesWhat it does
delivery_expiry_hours241 to 168chat appat onceHours after which an answer that could not be delivered is given up (1 to 168).
home_chatnonetextchat appat onceThe chat (a direct message or an approved group of this chat app) that receives the Bot’s own updates; null sends none. Set it with an update of the chat app, as home_chat beside settings, not inside it, once that chat exists. A create does not take it.
mirror_other_doorsfalsetrue, falsechat appat onceAlso send the Bot’s replies to messages from other places (the app, the API) to the home chat.
no_reply_noticetruetrue, falsechat appat onceSend one line to the chat that asked when the Bot’s turn ends without an answer.
push_detail"brief""brief", "full"chat appat onceHow a pushed update is written: brief (one line) or full (the whole update, split into at most max_parts messages of up to part_chars each).
push_eventsemptylist of "report", "gate", "gone", "stop", "waiter", "limit", "budget", "error", "provider", "not_sent", "reset"chat appat onceBot updates sent to the home chat on their own, any subset of: report (a delegate finished a turn), gate (the Bot or a delegate asks for an approval or an answer, or that request ended), gone (a delegate was closed), stop (a stop of a delegate went through or failed), waiter (a wait ended: found, ran out or stopped), limit (the Bot stopped at its step limit), budget (the Bot did as much as it may on its own), error (the Bot’s turn failed), provider (the model provider refused or filtered a reply), not_sent (a message could not be queued), reset (a reset dropped a message or an answer).
wake_repliestruetrue, falsechat appat onceSend the Bot’s replies to its own updates (replies nobody in a chat asked for) to the home chat.

How answers look in the chat app.

SettingDefaultValuesSet onAppliesWhat it does
format"rich""rich", "plain"chat app, chatat onceSend answers with the platform’s markup (rich) or as plain text.
lang"en""en", "de", "fr", "es", "pt", "it", "ja", "zh"Bot, chat app, personat onceLanguage of the chat app’s fixed lines (en, de, fr, es, pt, it, ja, zh). The Bot’s own answers are not translated. For one person: PATCH …/principals/{pid} with lang; null removes it, so the chat app’s value applies.
max_parts81 to 20chat appat onceMost parts one answer is sent in (1 to 20); a longer answer is cut.
overflow_notetruetrue, falsechat appat onceEnd a cut answer with a line saying it continues in the session.
parse_mode"html""html", "plain"chat appat onceTelegram only: the markup used for rich answers, html or plain.
part_charsDiscord 2000, Slack 3900, Telegram 4096200 to the platform’s limit (Discord 2000, Slack 3900, Telegram 4096)chat appat onceLongest message part, in characters (an emoji or other character outside the basic range counts as two): 200 up to the platform’s limit (Telegram 4096, Slack 3900, Discord 2000), which is the default.
reply_style"thread""thread", "reply", "plain"chat app, chatat onceHow an answer is attached to the message it answers: thread, reply or plain.
show_sender_nametruetrue, falsechat appat onceTell the Bot the sender’s display name with each group message (an unverified hint, never authority); direct messages never carry it.
split_at"paragraph""paragraph", "line", "word"chat appat onceWhere a long answer is split into parts: paragraph, line or word.
typingtruetrue, falsechat appat onceTelegram and Discord only: show a typing indicator while the Bot works on an answer. Slack has no bot typing indicator.

Rates and sizes that keep a chat app from flooding the Bot or the platform.

SettingDefaultValuesSet onAppliesWhat it does
connection_opens_per_hour301 to 120chat appat onceSlack only: connections the chat app may open per hour, failed ones included (1 to 120).
identify_per_day1001 to 500chat appat onceDiscord only: gateway logins the chat app may attempt per day (1 to 500).
identify_per_hour201 to 60chat appat onceDiscord only: gateway logins the chat app may attempt per hour (1 to 60).
max_text_bytes65536256 to 65536chat appat onceLongest message accepted, in bytes (256 to 65536; a character outside basic Latin takes 2 to 4).
outbound_rateDiscord 1, Slack 1, Telegram 10.001 to 1chat appat onceMessages per second the chat app sends to one chat; at least 0.001 and at most 1, which is the default on every platform.
rate_bot_per_day20000 to 3000Botat onceMessages all chat apps of the Bot together may deliver per day (0 = no limit, up to 3000).
rate_chat_per_min200 to 600chat app, chatat onceMessages one chat may send per minute, all senders together (0 = no limit, up to 600).
rate_user_per_day1000 to 20000chat app, chatat onceMessages one person may send per day (0 = no limit, up to 20000).
rate_user_per_hour200 to 3600chat app, chatat onceMessages one person may send per hour (0 = no limit, up to 3600).
rate_user_per_min100 to 600chat app, chatat onceMessages one person may send per minute (0 = no limit, up to 600).
reconnect_backoff_max_seconds605 to 600chat appat onceLongest wait, in seconds, of the normal backoff between reconnect attempts (5 to 600). A connection-open limit or a retry delay from the chat app can make a wait longer.

The chat commands people can type.

SettingDefaultValuesSet onAppliesWhat it does
chat_commands["status", "stop", "bind", "unbind", "help"]list of "status", "stop", "bind", "unbind", "help"chat appat onceChat commands that work: any subset of status, stop, bind, unbind, help. A command not listed is ordinary text.
command_prefixDiscord "!", Slack "!", Telegram "/""!", ".", ";", "~", "/"chat appat onceCharacter that starts a chat command: one of ! . ; ~, or / on Telegram (the default there; ! elsewhere).

Connection details you rarely need to change.

SettingDefaultValuesSet onAppliesWhat it does
channel_leasetruetrue, falsechat apprestarts the chat appKeep the agent running while the chat app is enabled. false: the chat app alone does not keep it running; an open Bot session still does.
channels_pausedfalsetrue, falseBotat onceStop every chat app of the Bot at once; each keeps its own enabled value.
enabledtruetrue, falsechat apprestarts the chat appRun the chat app. false stops it and sends nothing. On an update, set it as enabled beside settings, not inside it. On create it goes in settings: false creates the chat app turned off (its token is still checked), and an update turns it on later.
hide_secretstruetrue, falseBot, chat appat onceHide the chat app’s stored credentials from the agent’s tools and, where the sandbox supports masks, from shells it starts afterwards. A shell without that support can still read them. Not a boundary: it does not stop root or sudo.
max_channels81 to 8Botat onceMost chat apps the Bot may have (1 to 8).
shared_identity"off""off"Botrestarts the chat appWhether several Bots may share one chat app. Only off is available.