arizuko › how-to › talking to agents
Two layers of "address the bot" live side by side: the chat platform (mention syntax, replies, reactions) and arizuko itself (slash commands, sticky routing, MCP tools). This page is the operator's map of both.
Whether a message fires the agent at all depends on the route. The default shape for a public channel is "respond on mention, observe everything else" (see asymmetric channels). A mention means different things per platform:
| platform | mention syntax | notes |
|---|---|---|
| Slack | @<bot> hello | slakd derives verb=mention from <@bot_user_id> in message text. Reactions and replies-to-bot also count as mentions. |
| Discord | @<bot> hello | Same shape. Replies to bot messages and reactions on them are promoted to mentions. |
| Telegram | @<botname> or reply | Group chats fire on @-mention or on reply to a bot message. DMs always fire. |
@<phone> or reply | WhatsApp groups need @-mention. Reply-to-bot promotes to mention (v0.40.2). | |
web (/chat/<token>/) | any message | The chat page is one-on-one with the agent. Every message is a turn. |
To: <bot>@<domain> | emaid threads by Message-ID. Reply-all keeps the thread. |
Six commands work on every platform — they short-circuit
before the agent runs. The handler list is
gateway/commands.go:36.
Type them as the first non-whitespace token of a message;
Telegram's /cmd@botname suffix is accepted.
| command | who can run | what it does |
|---|---|---|
/new [text] | anyone with interact | Clear the agent's session for this folder. Optional text runs as the first message of the new session. |
/ping | anyone with interact | Replies with current folder, session ID prefix, active container count, registered group count. |
/chatid | anyone with interact | Replies with the chat_jid of the current chat. Useful when writing route rules. |
/stop | anyone with interact | Kills the current agent container for this chat. Next message spawns a fresh one. |
/status | root only | Channel count, group count, active containers, errored chats, active tasks. |
/root <msg> | tier ≤ 1 | Delegate <msg> to the root group of the current folder hierarchy. Replies route back here. |
/invite [N] | root only | Mint an invite link; N = max uses (default 1). |
/gate list|add|rm|enable|disable | root only | Manage rate-limit gates. |
Bare @ at the start of a message is parsed
before commands — see sticky routing below.
@<folder> and #<topic>
On its own line at the start of a message, these change
where subsequent messages in this chat go — until
cleared. Implementation:
gateway/gateway.go:1876.
@<folder> — pin this chat to
folder <folder>. Replies arrive here,
but the agent for <folder> is the one
that runs. Unknown folder names are passed to the agent
(so a Czech sentence starting @everyone
doesn't break).@ alone — clear the pin, route by
rules again.#<topic> — pin a thread label.
Useful for multi-thread workflows in one chat.# alone — clear the topic pin.
With a leading @<child> <text>
(single message, not on its own line), the gateway
delegates that one message to the child folder —
same effect as a single-shot delegate_group
from inside the agent.
The operator's tools for moving conversation between
agents are the same MCP tools the agents use among
themselves. Two ways to invoke them: ask the agent in
chat ("delegate this to research") or call
the tool directly from the chat MCP socket. Tool
reference: MCP reference.
| tool | direction | use it when |
|---|---|---|
delegate_group |
parent → child | This folder owns a problem that belongs to a child agent. The child runs the turn; the reply routes back here. |
escalate_group |
child → parent | The child agent needs a decision from the parent. Parent receives the message; nothing is granted automatically. |
register_group |
parent creates child | Create a new sub-folder on the fly. Common in autoviv setups (autoviv) — tier-1 agent calls this on first message from a new channel. |
inject_message |
any → any | Push a system-style message into another folder's chat. Used by tasks and timed events. |
refresh_groups |
self | Reload the in-memory group list. Run after a folder is added or removed out-of-band. |
These are tier-gated. register_group needs
tier ≤ 1; delegate_group and
escalate_group follow the folder hierarchy
rules (parent can delegate to known children; child can
escalate to its parent). See
grants for the
permission model.
A chat_jid is <platform>:<rest>.
Full table at JID format.
For writing route rules, you almost always want
/chatid in the target chat and to paste the
result.
slack:T012/channel/C345 # one Slack channel
discord:dm/123 # one Discord DM
telegram:group/-100456 # one Telegram group
whatsapp:789@g.us # one WhatsApp group
web:<folder> # browser chat at folder (via /chat/<token>/)
hook:<folder>/<source> # webhook ingest at folder (via /hook/<token>)| I want to… | use |
|---|---|
| Start a fresh agent session in this chat | /new |
| Find this chat's JID for a route rule | /chatid |
| Send one message to the root agent | /root <msg> |
Route all subsequent messages to research | @research on its own line |
Hand this one task to research | @research <task> as one message, or ask the agent to delegate_group |
| Open a new sub-folder | Ask the agent to call register_group |
| Push a system note into another folder | Ask the agent to call inject_message |
| Bring in events from GitHub or Stripe | Wire a webhook → webhooks |
| Make the agent forget and start over | /stop (kills container), then /new |
app_mention; slakd derives mention from the
regular message.* event. Subscribing both
double-fires (see Slack adapter, step 3).@botname suffix (/new@mybot);
the gateway strips it before matching.verb=reaction with the emoji. The agent can
treat 👎 as a dislike signal — no
separate code path.