Communication & escalation tools

This page documents the agent tools your Revka agent uses to talk to people and to other sessions: react to messages, ask a question and wait for the answer, escalate to a human, run a poll, fire a Pushover push notification, and read or write across conversation sessions. Use it when you need the exact parameters each tool accepts.

The tools fall into three groups:

• Channel interactions — reaction, ask_user, escalate_to_human, and poll send something to a live messaging channel. They depend on at least one channel being configured and initialized at startup. See Channels overview and Connect a messaging channel.
• Push notifications — pushover (and the escalation path of escalate_to_human) sends a mobile push via Pushover.
• Inter-session messaging — sessions_list, sessions_history, and sessions_send inspect and write to other conversation sessions, enabling cross-session and inter-agent communication. See Sessions & conversation state.

Note

The channel tools (reaction, ask_user, escalate_to_human, poll) resolve the live channel map that Revka populates after channels boot. Until channels are initialized they return No channels available yet (channels not initialized). All of these tools are gated by the security policy and are blocked under read-only autonomy. See Autonomy levels & approvals.

Channel interaction tools

reaction

Adds or removes an emoji reaction on a message in any active channel (Discord, Slack, Telegram, etc.). You identify the message with the platform channel ID and message ID — not Revka’s internal channel name.

{
  "channel": "discord",
  "channel_id": "123456789",
  "message_id": "msg_123",
  "emoji": "👍",
  "action": "add"
}

Field	Type	Meaning
channel	string (required)	The configured channel name to react in (e.g. discord, slack, telegram).
channel_id	string (required)	Platform-specific channel/conversation identifier (e.g. a Discord channel snowflake, a Slack channel ID).
message_id	string (required)	Platform-scoped identifier of the message to react to.
emoji	string (required)	The emoji — a Unicode character (e.g. 👍) or a platform shortcode.
action	string	add (default) or remove. Any other value is rejected.

If the named channel is not in the channel map, the tool lists the available channel names in its error. Emoji format differs per platform — some platforms expect a Unicode character, others a shortcode — so use what the target platform accepts.

ask_user

Asks the user a question on a messaging channel and blocks the agent loop until they reply or the timeout expires. Pass choices to offer structured options; on the CLI they render as a numbered list, and on platforms that support it (e.g. Telegram) as buttons.

{
  "question": "Which deployment environment should I use?",
  "choices": ["production", "staging", "dev"],
  "timeout_secs": 120
}

Field	Type	Meaning
question	string (required)	The question to ask. Must be non-empty.
choices	array of strings	Optional structured options. Rendered as a numbered list (and buttons on capable channels). Empty entries are dropped.
timeout_secs	integer	Seconds to wait for a reply. Default 300.
channel	string	Target channel name. Defaults to the first available channel if omitted.

The tool returns the user’s reply text on success. On timeout it returns success: false with the output TIMEOUT and an error such as No response received within 120 seconds. If you name a channel that does not exist, the error lists the available channels.

Caution

ask_user holds the agent loop open for the full timeout_secs while it waits. Keep the timeout short for interactive flows, and prefer choices when you want an answer you can parse deterministically.

escalate_to_human

Escalates a situation to a human operator with urgency routing. It sends a structured, urgency-prefixed message to the active channel, and for high or critical urgency it also fires a Pushover notification when credentials are configured. Optionally it blocks to wait for a human reply.

{
  "summary": "Database replication lag exceeded 30s",
  "context": "Lag has been growing for 10 minutes",
  "urgency": "high",
  "wait_for_response": true,
  "timeout_secs": 600
}

Field	Type	Meaning
summary	string (required)	One-line escalation summary. Must be non-empty.
context	string	Detailed context for the human.
urgency	string	low, medium (default), high, or critical. Any other value is rejected.
wait_for_response	boolean	false by default. When true, the tool blocks and returns the human’s reply.
timeout_secs	integer	Wait timeout when wait_for_response is true. Default 600.

The escalation is sent to the first available channel. The message is prefixed by urgency — ℹ️ [LOW], ⚠️ [MEDIUM], 🔴 [HIGH], or 🚨 [CRITICAL] — followed by the summary, the optional context, and a Reply to this message to respond. line.

When wait_for_response is false, the tool returns immediately with a JSON status, e.g. {"status":"escalated","urgency":"high","channel":"slack"}. When true, it returns the human’s reply text, or TIMEOUT if none arrives in time.

The Pushover step is best-effort: high/critical escalations still succeed (channel-only) even when Pushover credentials are missing or the push fails. The push uses the title Agent Escalation, with Pushover priority 1 for critical and 0 for high; low and medium never push.

Tip

Choose ask_user for a question that expects an answer, and escalate_to_human for an urgent alert that needs a human’s attention (and optionally an acknowledgment). Only escalate_to_human carries urgency routing and the automatic Pushover hop.

poll

Creates a poll in a messaging channel. The poll is rendered as a numbered text message with number-emoji voting (1️⃣–🔟) so it works on every channel.

{
  "question": "Which tech talk topic should we host next?",
  "options": ["Rust", "WebAssembly", "AI agents"],
  "channel": "discord",
  "duration_minutes": 60,
  "multi_select": false
}

Field	Type	Meaning
question	string (required)	The poll question. Must be non-empty.
options	array of strings (required)	The answer options. 2–10 non-empty entries; outside that range the call is rejected.
channel	string	Target channel name. Defaults to the first available channel if omitted.
recipient	string	Recipient/chat identifier within the channel (e.g. a Telegram chat ID or a Slack channel ID).
duration_minutes	integer	Poll duration shown in the message. Default 60.
multi_select	boolean	false by default. Controls the “single choice” vs. “multiple choices allowed” label.

Note

Telegram and Discord are detected as native-poll-capable, but the current channel interface delivers a text-formatted poll to every channel — native poll APIs are not yet wired up, so the tool notes the intent in its output rather than creating a platform-native poll. Voting happens via the number-emoji reactions; the tool does not tally or return results — they remain visible in the channel.

Push notifications

pushover

Sends a Pushover push notification to your configured device. Credentials are read from a .env file in the agent’s workspace directory.

{
  "message": "Deployment succeeded",
  "title": "CI/CD",
  "priority": 1
}

Field	Type	Meaning
message	string (required)	The notification body. Must be non-empty.
title	string	Optional notification title.
priority	integer	-2 (lowest/silent), -1 (low/no sound), 0 (normal), 1 (high), 2 (emergency/repeating). Values outside -2..=2 are rejected.
sound	string	Notification sound override (e.g. pushover, bike, bugle, cashregister).

Setup: create a Pushover account and application to get an API token, then add both values to the .env file in the workspace:

# .env (in the agent's workspace directory)
PUSHOVER_TOKEN=your-application-api-token
PUSHOVER_USER_KEY=your-user-key

Both keys are required; the tool errors if either is missing. export prefixes, quoted values, and trailing # comments are tolerated. Priority 2 (emergency) repeats until acknowledged in the Pushover app.

Note

escalate_to_human calls Pushover automatically for high/critical urgency, so you do not need a separate pushover call when escalating. Use pushover directly for standalone notifications that are not escalations.

Inter-session messaging

These three tools let the agent see and act across other conversation sessions. A session is keyed by <channel>__<identifier> (for example telegram__alice or discord__bob); the part before __ is the channel. Sessions are persisted by the session backend in the workspace.

sessions_list is read-only and ungated. sessions_history requires the Read tool operation and sessions_send requires the Act operation, so both are subject to the security policy. A session_id must be non-empty and contain at least one alphanumeric character.

sessions_list

Lists active sessions with their channel, last activity time, and message count.

{"limit": 20}

Field	Type	Meaning
limit	integer	Max sessions to return. Default 50.

Returns No active sessions found. when there are none; otherwise one line per session in the form - telegram__alice: channel=telegram, messages=2, last_activity=....

sessions_history

Reads the message history of a specific session, returning the last N messages with their roles.

{"session_id": "telegram__alice", "limit": 50}

Field	Type	Meaning
session_id	string (required)	The session ID, e.g. telegram__alice. From sessions_list.
limit	integer	Max messages to return, counting from the most recent. Default 20.

Each message is rendered as [<role>] <content> (roles such as user and assistant), prefixed by a header like Session 'telegram__alice': showing 2/2 messages. An unknown or empty session returns No messages found for session '...'.

sessions_send

Sends a message to a specific session by its ID. The message is appended to that session’s conversation history as a user message — this is the push model that enables inter-agent communication: the next time the target session runs, the message is in its history and drives the agent’s response.

{
  "session_id": "discord__bob",
  "message": "The background task has completed. Results: ..."
}

Field	Type	Meaning
session_id	string (required)	The target session ID, e.g. discord__bob.
message	string (required)	The message content. Must be non-empty.

On success it returns Message sent to session '<id>'. Sending to a session ID that does not exist creates/appends to that key in the backend; the validation only rejects blank or non-alphanumeric IDs and empty messages.

Caution

sessions_send writes directly into another session’s history without going through that channel’s normal ingress. Treat it as an internal coordination primitive between your own agents, not as a way to message arbitrary users on a platform — for that, send through the channel (or schedule delivery with cron_add).

Related pages

• Tools overview — how tools are registered and gated.
• Channels overview and Connect a messaging channel — set up the channels these tools talk to.
• Sessions & conversation state — the session model behind the sessions_* tools.
• Autonomy levels & approvals — why these tools are blocked under read-only autonomy.
• Scheduling & SOP tools — cron_add delivery for scheduled channel messages.
• Spawning & coordinating agents — multi-agent patterns that build on inter-session messaging.