# Documentation Page **Page:** kit/agent/chat-apps/approvals [Download Raw Markdown](./kit/agent/chat-apps/approvals.md) --- # Approvals from chat **The agents your Bot starts stop and ask before risky steps. Now the question reaches your phone, with buttons.** Your Bot hands work to agents on your computers. When one of them wants to do something that needs a yes from you, it waits. That pause is a **gate**. Until now you answered it in the Hub, in the agent's TUI or over the API. With a chat app, each pending gate becomes a **card**. You press a button. The agent goes on. ## What a card looks like An approval card shows: - **Approval needed**, which agent asks, and the tool it wants to run. - A short summary of what it will do (`gate_detail: summary`). Long details are cut; the card says how much more there is, to read in the session. - Buttons: **Approve**, **Deny**, and **Allow for this session** when the agent offers it. A question card shows the question and one button per choice. That works for one question with up to 8 choices. A question that needs typed text, or several questions at once, gets a card without buttons: answer it in the session. After a decision, the card is edited to say who decided: | Card line | Meaning | |---|---| | Decision sent, checking… | Your press arrived. The agent is applying it. | | Approved by Ana / Denied by Ana / Answered by Ana | Ana decided with this card. | | Allowed for this session by Ana | Ana allowed this tool for the rest of the agent's session. | | Approved elsewhere. / Denied elsewhere. / Answered elsewhere. / Allowed for this session elsewhere. | Someone decided in another place: the TUI, the API, another chat. | | Approved automatically: auto-approve is on. | The Bot's auto-approve setting decided it. | | Declined: a new message replaced it. | A new message to that agent replaced the request. | | Declined: the request was cancelled. | The agent's work was stopped. | | No decision in time: the request timed out. | The agent stopped waiting. | | Resolved elsewhere: check the session. / Unknown outcome: check the session. | The request ended, but the chat app cannot tell how. Open the session to see. | | Expired | The card is older than `gate_ttl_minutes`. Its buttons no longer work. | | No longer pending | The request changed or ended. A new card may follow. | | This question needs a typed answer: answer it in the session. | The question has no buttons. Answer it in the session. | ### When a press changes nothing A card that does not change after a press does not prove that nothing was decided. The agent applies the decision first and edits the card after. That edit can fail, and the card then keeps buttons that no longer do anything. So before you press again, check the gate: open the agent's chat on the **AI** page of the Hub or in the TUI, or query `GET /api/v1/agent/gates`. The API lists gates only for sessions attached through HTTP. Read every page using `page` and `limit`; each page holds at most 100 gates. A gate absent from this list can still be pending in the TUI. If `meta.omitted` is above 0, read the list again. Press again only if the gate is still pending. On Discord, the person who pressed also gets a note that only they can read, for example: - **You may not decide this.** They lack the right to decide (see below). - **Could not be sent. Try again.** The press did not reach the agent. If Discord says the interaction failed, the press was not applied either. Press again. Telegram and Slack show no such note. ## Where cards go Cards go to the **direct message** of every person who may decide. Nobody else gets one. A card needs a direct message to land in. Someone who paired with a code already has one. Someone you added by user id gets cards after their first ordinary direct message or control command that the Bot accepts. The `help` command alone does not establish card delivery. They do not need a pairing code. Groups get no cards by default (`decide_in_groups: false`). They also see nothing else about the gate. Turn `decide_in_groups` on to show cards with buttons in an approved group whose message started the work. The group must be approved even with `group_mode: open`. The rules for who may press still apply there. ## Who may decide `gate_deciders` on the chat app decides who may press a button: | `gate_deciders` | Who may decide | |---|---| | `owner` (default) | Owners only. | | `named` | People with the `gates` right. | | `principals` | Every paired person with the `chat` right. | | `none` | Nobody, from this chat app. First set `gate_cards` to `links` or `off`, or send both settings in the same update. With `gate_cards: on`, this change is refused with `setting_conflict`, reason `no_decider`. | A guest never decides, whatever the settings. When someone who may not decide presses a button anyway, nothing happens (on Discord they also see "You may not decide this."). The check runs again at the moment of the press. If you remove someone's right after the card was sent, their press is refused. You can also answer in words, for an agent's approval. A message like "approve the deploy" from a person who may decide asks the Bot to approve it. From anyone else, it decides nothing. An approval the Bot itself waits on works differently: use the card, or answer in the session. A new message to the Bot declines that approval. ## How cards look These settings change only the card, never who may decide: | Setting | Values | |---|---| | `gate_cards` | `on` (card with buttons, default), `links` (card with the text only, no buttons), `off` (no card). | | `gate_detail` | `summary` (tool, target and shortened details, default) or `minimal` (tool name only). | | `gate_ttl_minutes` | Minutes until a card shows as expired. `0` (default) means never. | 1. In the Hub, open **Bots**, select the Bot and open the **Chat apps** tab. 2. Choose **Manage** on the chat app, then open **Settings**. 3. Change **Who may approve** under **Main settings**. **How approvals are shown**, **Approve in group chats**, **Detail on approval cards** and **Approval cards expire after (minutes)** are under **All settings**, in **Approvals**. 4. Choose **Save settings**. Select the chat app, choose **Settings**, and change **Who can decide**, **Gate cards**, **Gate detail**, **Gate expiry min** or **Decide in groups**. Switches and choices apply at once. For **Gate expiry min**, type the minutes and choose **✓ Save**. ```bash hoody agent bots channels update -c $COMPUTER_ID --id chief --channel-id ch_1a2b3c4d --settings-gate-deciders named --settings-gate-detail minimal ``` `box` is the computer-scoped client from [Connect it](/kit/agent/chat-apps/discord/#2-connect-it): `const box = await hoody.withComputer(process.env.COMPUTER_ID!);` ```ts await box.agent.bots.channels.update('chief', 'ch_1a2b3c4d', { settings: { gate_deciders: 'named', gate_detail: 'minimal' }, }); ``` ```bash curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels/ch_1a2b3c4d" \ -H "Content-Type: application/json" \ -d '{"settings": {"gate_deciders": "named", "gate_detail": "minimal"}}' ``` To let a non-owner decide in direct messages, use a `dm_policy` that admits them, such as `allowlist` or `pairing`; set `gate_deciders` to `named`; and grant them the `gates` right while preserving their `chat` right (`PATCH …/principals/{pid}` with `rights`). If you added them by user id, they must first send an ordinary direct message or control command that the Bot accepts so cards have somewhere to arrive. The `help` command alone does not establish card delivery. In the Hub, open the chat app's **People** section, choose **Edit** on the person, turn on **Decide approvals** under **Rights**, and choose **Save changes**. A card's summary can contain file paths, commands or other details of your work. Anyone who gets the card can read it. Use `gate_detail: minimal` if that is too much for a chat app. **Fewer steps between "may I?" and "yes": the decision goes wherever you are.**