Approvals from chat
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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. |
- In the Hub, open Bots, select the Bot and open the Chat apps tab.
- Choose Manage on the chat app, then open Settings.
- 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.
- 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.
hoody agent bots channels update -c $COMPUTER_ID --id chief --channel-id ch_1a2b3c4d --settings-gate-deciders named --settings-gate-detail minimalbox is the computer-scoped client from Connect it: const box = await hoody.withComputer(process.env.COMPUTER_ID!);
await box.agent.bots.channels.update('chief', 'ch_1a2b3c4d', { settings: { gate_deciders: 'named', gate_detail: 'minimal' },});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.
Fewer steps between “may I?” and “yes”: the decision goes wherever you are.