Chat app settings reference
Section titled “Chat app settings reference”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
GETandPATCH /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 asettingsobject.enabledandhome_chatgo besidesettings, 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 asettingsobject.
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.
Access
Section titled “Access”Who can talk to the Bot, in which chats.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
allowed_chats | empty | list, at most 200 | chat app | at once | When 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_chats | empty | list, at most 200 | chat app | at once | Platform chat ids whose messages are dropped (at most 200). |
blocked_users | empty | list, at most 200 | chat app | at once | Platform 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 app | at once | What 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 app | at once | Rights 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 app | at once | Who 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 app | at once | How 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_principals | 8 | 1 to 32 | chat app | at once | Most people a chat app keeps (1 to 32); pairing, an allowlist add and owner enrolment beyond it are refused. |
mention_only | true | true, false | chat app, chat | at once | In 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_tries | 20 | 5 to 200 | chat app | at once | Wrong codes in total before the active code stops working (5 to 200). |
pairing_rights | same as default_rights | list of "chat", "control", "gates" | chat app | at once | Rights a pairing code grants when the request names none: a subset of chat, control, gates. Unset, it follows default_rights. |
pairing_ttl_minutes | 15 | 1 to 1440 | chat app | at once | How long a pairing or owner enrolment code stays valid, in minutes (1 to 1440). |
pairing_user_burn_minutes | 60 | 1 to 1440 | chat app | at once | How 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_tries | 5 | 1 to 20 | chat app | at once | Wrong codes from one person before that person is refused for pairing_user_burn_minutes (1 to 20). |
unpaired_reply | "hint" | "hint", "silent" | chat app | at once | What 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.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
decide_in_groups | false | true, false | chat app | at once | Whether 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 app | at once | How 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 app | at once | Who 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 app | at once | What an approval card shows: summary (the tool, the target and shortened details) or minimal (the tool name only). |
gate_ttl_minutes | 0 | 0 or 1 to 10080 | chat app | at once | Minutes after which an approval card is shown as expired and its buttons refuse (0 = never, else 1 to 10080). |
Updates
Section titled “Updates”What the Bot sends on its own, and where.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
delivery_expiry_hours | 24 | 1 to 168 | chat app | at once | Hours after which an answer that could not be delivered is given up (1 to 168). |
home_chat | none | text | chat app | at once | The 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_doors | false | true, false | chat app | at once | Also send the Bot’s replies to messages from other places (the app, the API) to the home chat. |
no_reply_notice | true | true, false | chat app | at once | Send one line to the chat that asked when the Bot’s turn ends without an answer. |
push_detail | "brief" | "brief", "full" | chat app | at once | How 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_events | empty | list of "report", "gate", "gone", "stop", "waiter", "limit", "budget", "error", "provider", "not_sent", "reset" | chat app | at once | Bot 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_replies | true | true, false | chat app | at once | Send the Bot’s replies to its own updates (replies nobody in a chat asked for) to the home chat. |
Format
Section titled “Format”How answers look in the chat app.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
format | "rich" | "rich", "plain" | chat app, chat | at once | Send answers with the platform’s markup (rich) or as plain text. |
lang | "en" | "en", "de", "fr", "es", "pt", "it", "ja", "zh" | Bot, chat app, person | at once | Language 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_parts | 8 | 1 to 20 | chat app | at once | Most parts one answer is sent in (1 to 20); a longer answer is cut. |
overflow_note | true | true, false | chat app | at once | End a cut answer with a line saying it continues in the session. |
parse_mode | "html" | "html", "plain" | chat app | at once | Telegram only: the markup used for rich answers, html or plain. |
part_chars | Discord 2000, Slack 3900, Telegram 4096 | 200 to the platform’s limit (Discord 2000, Slack 3900, Telegram 4096) | chat app | at once | Longest 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, chat | at once | How an answer is attached to the message it answers: thread, reply or plain. |
show_sender_name | true | true, false | chat app | at once | Tell 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 app | at once | Where a long answer is split into parts: paragraph, line or word. |
typing | true | true, false | chat app | at once | Telegram and Discord only: show a typing indicator while the Bot works on an answer. Slack has no bot typing indicator. |
Limits
Section titled “Limits”Rates and sizes that keep a chat app from flooding the Bot or the platform.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
connection_opens_per_hour | 30 | 1 to 120 | chat app | at once | Slack only: connections the chat app may open per hour, failed ones included (1 to 120). |
identify_per_day | 100 | 1 to 500 | chat app | at once | Discord only: gateway logins the chat app may attempt per day (1 to 500). |
identify_per_hour | 20 | 1 to 60 | chat app | at once | Discord only: gateway logins the chat app may attempt per hour (1 to 60). |
max_text_bytes | 65536 | 256 to 65536 | chat app | at once | Longest message accepted, in bytes (256 to 65536; a character outside basic Latin takes 2 to 4). |
outbound_rate | Discord 1, Slack 1, Telegram 1 | 0.001 to 1 | chat app | at once | Messages 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_day | 2000 | 0 to 3000 | Bot | at once | Messages all chat apps of the Bot together may deliver per day (0 = no limit, up to 3000). |
rate_chat_per_min | 20 | 0 to 600 | chat app, chat | at once | Messages one chat may send per minute, all senders together (0 = no limit, up to 600). |
rate_user_per_day | 100 | 0 to 20000 | chat app, chat | at once | Messages one person may send per day (0 = no limit, up to 20000). |
rate_user_per_hour | 20 | 0 to 3600 | chat app, chat | at once | Messages one person may send per hour (0 = no limit, up to 3600). |
rate_user_per_min | 10 | 0 to 600 | chat app, chat | at once | Messages one person may send per minute (0 = no limit, up to 600). |
reconnect_backoff_max_seconds | 60 | 5 to 600 | chat app | at once | Longest 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. |
Commands
Section titled “Commands”The chat commands people can type.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
chat_commands | ["status", "stop", "bind", "unbind", "help"] | list of "status", "stop", "bind", "unbind", "help" | chat app | at once | Chat commands that work: any subset of status, stop, bind, unbind, help. A command not listed is ordinary text. |
command_prefix | Discord "!", Slack "!", Telegram "/" | "!", ".", ";", "~", "/" | chat app | at once | Character that starts a chat command: one of ! . ; ~, or / on Telegram (the default there; ! elsewhere). |
Advanced
Section titled “Advanced”Connection details you rarely need to change.
| Setting | Default | Values | Set on | Applies | What it does |
|---|---|---|---|---|---|
channel_lease | true | true, false | chat app | restarts the chat app | Keep 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_paused | false | true, false | Bot | at once | Stop every chat app of the Bot at once; each keeps its own enabled value. |
enabled | true | true, false | chat app | restarts the chat app | Run 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_secrets | true | true, false | Bot, chat app | at once | Hide 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_channels | 8 | 1 to 8 | Bot | at once | Most chat apps the Bot may have (1 to 8). |
shared_identity | "off" | "off" | Bot | restarts the chat app | Whether several Bots may share one chat app. Only off is available. |