Messaging

What it does: Gives agents one unified API to send, reply to, react to, edit, delete, fetch, and attach messages at the current authoritative channel endpoint. Who it’s for: Agents handling native message operations in their current conversation. For proactive delivery that must choose among previously observed endpoints, use notify_user.

Endpoint authority (security). Every message call must match the complete endpoint already attached to the current turn: channel type, configured channel instance, conversation ID, optional thread, and direct/shared kind. The tool’s channel_type and channel_id fields select within that authority; they do not discover or mint a different endpoint. Missing or conflicting authority fails closed before the adapter runs. This prevents a prompt-injected agent from crossing account, thread, or conversation boundaries.

message — Endpoint-Scoped Messaging

The message tool supports 7 actions — send, reply, react, edit, delete, fetch, and attach. Comis verifies the requested coordinates against the turn’s authoritative endpoint, then dispatches to its exact channel adapter instance. Not every action is supported on every platform (see the capability matrix below); the tool returns a structured error if you ask for something the channel cannot do. All actions require the channel_type parameter to specify which platform adapter handles the request. This is a required string identifying the channel type (e.g., telegram, discord, slack, whatsapp, signal, imessage, line, irc, email).

Quick Reference

Action	What It Does
`send`	Send a new message to a channel
`reply`	Reply to a specific message
`react`	Add an emoji reaction
`edit`	Edit a previously sent message
`delete`	Delete a message
`fetch`	Retrieve recent messages from a channel
`attach`	Send a message with a file attachment

Actions

send -- Send a new message

Sends a new message to the endpoint authorized for the current turn. An inbound turn uses its source endpoint; a scheduled or heartbeat turn can send only after the run is bound to an exact endpoint.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `send`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The target channel identifier
`text`	string	Yes	The message content
`buttons`	array	No	Button rows for interactive messages. Each inner array is one row of buttons with `text`, optional `callback_data`, `url`, and `style` (`primary`, `secondary`, `danger`, `link`).
`cards`	array	No	Rich card embeds. Renders as embeds on Discord, blocks on Slack, HTML on Telegram. Each card has optional `title`, `description`, `image_url`, `color`, and `fields`.
`effects`	array	No	Message delivery effects: `spoiler` (wraps text in spoiler) or `silent` (suppresses notification)
`thread_reply`	boolean	No	Create or continue a thread from this message. Discord creates thread, Slack uses thread_ts.

Example — Send a notification:

action: send
channel_type: discord
channel_id: "general"
text: "The daily report is ready. Check the #reports channel for details."

Use send when the current turn already owns the destination endpoint. Use notify_user when proactive delivery should resolve a configured or recent tracked endpoint before enqueueing.

reply -- Reply to a specific message

Replies to an existing message, creating a threaded response on platforms that support threading (like Discord and Slack). On platforms without threading, this sends a regular message.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `reply`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The channel containing the message
`message_id`	string	Yes	The ID of the message to reply to
`text`	string	Yes	The reply content
`buttons`	array	No	Button rows for interactive messages (same format as `send`)
`cards`	array	No	Rich card embeds (same format as `send`)
`effects`	array	No	Message delivery effects: `spoiler` or `silent`
`thread_reply`	boolean	No	Create or continue a thread from this message

Example — Reply to a user’s question:

action: reply
channel_type: slack
channel_id: "support"
message_id: "msg_abc123"
text: "Great question! Here's what I found..."

react -- Add an emoji reaction

Adds an emoji reaction to an existing message. This is a lightweight way for agents to acknowledge messages without sending a full reply.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `react`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The channel containing the message
`message_id`	string	Yes	The ID of the message to react to
`emoji`	string	Yes	The emoji to add. Provide the literal Unicode emoji character (e.g., the thumbs-up character) or a platform-recognized shortcode; per-platform translation is handled by the channel adapter.

Example — Acknowledge a request:

action: react
channel_type: telegram
channel_id: "requests"
message_id: "msg_def456"
emoji: "thumbsup"

Emoji names vary by platform. Discord uses custom emoji names, Telegram uses Unicode emoji, and Slack uses shortcodes like :thumbsup:. The agent handles the translation automatically.

edit -- Edit a sent message

Edits a message that the agent previously sent. Useful for updating status messages or correcting errors.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `edit`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The channel containing the message
`message_id`	string	Yes	The ID of the message to edit
`text`	string	Yes	The new message content

Not all platforms support message editing. Telegram supports editing within 48 hours. Discord supports editing with no time limit. Some platforms (like IRC) do not support editing at all. The tool will return an error if editing is not supported.

delete -- Delete a message

Deletes a message from a channel. The agent can only delete messages it has permission to delete — typically its own messages or, on platforms with moderation rights, other users’ messages.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `delete`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The channel containing the message
`message_id`	string	Yes	The ID of the message to delete

Platform permissions apply. On Discord, the bot needs “Manage Messages” permission to delete other users’ messages. On Telegram, the bot needs admin rights. Check your platform’s documentation for permission requirements. This is a destructive action that requires user confirmation via the _confirmed parameter.

fetch -- Retrieve recent messages

Fetches recent messages from a channel. Useful when the agent needs to review recent conversation history or catch up on messages it may have missed.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `fetch`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The channel to fetch messages from
`limit`	integer	No	Maximum number of messages to return (default: 20)
`before`	string	No	Fetch messages before this message ID (for pagination)

Returns a list of messages including their IDs, authors, timestamps, and content.Example — Get the last 5 messages:

action: fetch
channel_type: discord
channel_id: "general"
limit: 5

attach -- Send a message with a file

Sends a message with a file attachment. The agent can attach images, documents, audio files, or any other file type supported by the target platform.Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Must be `attach`
`channel_type`	string	Yes	Channel type (e.g., `telegram`, `discord`, `slack`, `whatsapp`)
`channel_id`	string	Yes	The target channel
`attachment_url`	string	Yes	URL or workspace path of file to send: `http://`, `https://`, `file://`, or absolute path
`attachment_type`	string	No	Attachment media type: `image`, `file`, `audio`, or `video` (default: `file`)
`mime_type`	string	No	MIME type of attachment
`file_name`	string	No	Display filename for the attachment
`caption`	string	No	Caption text for the attachment

Example — Send a generated report:

action: attach
channel_type: telegram
channel_id: "reports"
attachment_url: "https://example.com/weekly-report.pdf"
attachment_type: file
file_name: "weekly-report.pdf"
caption: "Here's the weekly summary report."

File size limits vary by platform. Discord allows up to 25 MB (or 100 MB with Nitro). Telegram allows up to 50 MB for most files. Check your platform’s limits if sending large files.

Per-channel capability matrix

Channel adapters declare what they can do via a ChannelCapability schema, and the message tool checks support before dispatching. Asking for an unsupported action returns a structured error with errorKind: "platform" — it does not silently no-op.

Channel	Send	Reply	React	Edit	Delete	Fetch History	Attachments	Streaming method	Max chars
Discord	Yes	Yes	Yes	Yes	Yes	Yes	Yes	edit (500ms)	2000
Telegram	Yes	Yes	Yes (limited emoji)	Yes	Yes	No	Yes	edit (300ms)	4096
Slack	Yes	Yes (thread_ts)	Yes (shortnames)	Yes	Yes	Yes	Yes	edit (400ms)	4000
WhatsApp	Yes	Yes (quoted)	Yes (Unicode)	Yes (overwrite)	Own only	No	Yes	block (600ms)	65536
Signal	Yes	Yes (quoted)	Yes (Unicode)	No	Yes	No	Yes	block (500ms)	65536
iMessage	Yes	No	No	No	No	Yes	Yes	none	20000
LINE	Yes	Yes (push)	No	No	No	No	Yes	none	5000
IRC	Yes	Mention prefix	No	No	No	No	No	none	512
Email	Yes	Yes (RFC 5322 headers)	No	No	No	No	Yes	none	100000

Streaming methods:

edit — the agent posts a placeholder, then edits it in place as content streams in. Supported on Discord, Telegram, Slack.
block — the agent buffers chunks and emits complete blocks (no edit). Used by WhatsApp and Signal where edits are unreliable or unsupported.
none — no streaming; the agent waits for the full reply before sending.

The throttle column is the minimum delay between consecutive edits/blocks during streaming, configured per adapter to respect each platform’s rate limits.

The React column above is the outbound capability — whether the agent can add an emoji via message action: react. It is independent of inbound-reaction capture (below): a channel can support sending reactions while not exposing inbound ones, and vice versa.

Inbound reactions: corroborating learning signal

Beyond sending reactions (the react action above, plus the removeReaction lifecycle), Comis also captures reactions that other people add to the agent’s own outbound messages — turning a 👍 / 👎 into a lightweight, corroborating outcome signal for Verified Learning. This is off by default and only does anything when learningOutcome.enabled is set for the agent (and the master memory.enabled switch is on). When enabled, a reaction is matched against the agent’s reactionMap (👍/✅ → success, 👎/❌ → failure by default) and recorded through the reaction source. It is strictly a corroborating signal: it can only weight an outcome the deterministic tool/pipeline signal already resolved, never override it. The captured event carries ids / emoji / counts only — never a message body or a sender display name. See the learningOutcome config for the trust-weighting and rate-limit behavior.

Which channels capture inbound reactions

Channel	Inbound reaction capture	Notes
Discord	Yes	Binds `MessageReactionAdd`; the required gateway intents are already held.
Slack	Yes	Binds the `reaction_added` event; requires operator setup (below).
Telegram	Yes	Binds `message_reaction`; polling opts into this update type automatically.
WhatsApp / Signal / iMessage / LINE / IRC / Email	No	These platforms’ inbound APIs expose no per-reaction event carrying the reactor’s identity. This is an honest no-op, not a gap — the agent can still send reactions where the capability matrix above allows it.

Operator setup

The reaction-capable platforms need a one-time setup so the platform actually delivers reaction events:

Slack — add the reactions:read OAuth scope to the app and subscribe to the reaction_added event in the app’s Event Subscriptions. Without both, Slack silently delivers no reaction events and the signal stays dark with no error.
Telegram — the bot opts into message_reaction updates automatically. Telegram webhook ingestion is not available; setting a webhook URL fails adapter startup.
Discord — no developer-portal change. Comis already holds the GuildMessageReactions / DirectMessageReactions intents.

Endpoint-Scoped Routing

channel_type and channel_id are necessary coordinates, but they are not sufficient authority. The current turn must also carry the same complete endpoint. This keeps separate accounts, threads, and direct/shared conversations distinct even when a platform reuses the same visible ID. To contact a different known endpoint, bind the scheduled run to that endpoint or use notify_user. Notification resolution accepts only complete endpoints recorded from authoritative session activity and fails closed when none exists.

notify_user — Proactive Notifications

The notify_user tool delivers proactive notifications outside the normal request-response flow. The daemon resolves a complete tracked endpoint, then applies rate limiting, dedup, quiet-hours suppression, and channel-resolution guards before enqueueing the notification.

Parameter	Type	Required	Description
`message`	string	Yes	Notification text to send to the user
`priority`	string	No	One of `low`, `normal` (default), `high`, `critical`. `critical` bypasses quiet hours.
`channel_type`	string	No	Target channel type (e.g., `telegram`, `discord`). Omit for auto-resolution from tracked endpoint activity.
`channel_id`	string	No	Target conversation ID. Required with `channel_type`; the pair must resolve to a tracked complete endpoint.

Example — Critical alert that bypasses quiet hours:

message: "Production deploy failed -- rolling back."
priority: critical

Use notify_user for agent-initiated communication (alerts, reminders, task-completion notices) when the daemon should resolve a tracked endpoint and apply platform-level guards. Use message (action: send) for direct messaging to the endpoint already authorized for the current turn.

Channels Overview

Connect Discord, Telegram, Slack, and 5 more platforms

Sessions

Sub-agents, pipelines, and session management

Agent Tools Overview

Master reference table of all tools

Platform Actions

Moderation actions for Discord, Telegram, Slack, and WhatsApp

Agents

Channels

Skills and integrations

Agent tools

Media

Web dashboard

message — Endpoint-Scoped Messaging

Quick Reference

Actions

Per-channel capability matrix

Inbound reactions: corroborating learning signal

Which channels capture inbound reactions

Operator setup

Endpoint-Scoped Routing

notify_user — Proactive Notifications

Channels Overview

Sessions

Agent Tools Overview

Platform Actions

​message — Endpoint-Scoped Messaging

​Quick Reference

​Actions

​Per-channel capability matrix

​Inbound reactions: corroborating learning signal

​Which channels capture inbound reactions

​Operator setup

​Endpoint-Scoped Routing

​notify_user — Proactive Notifications

​Related

Channels Overview

Sessions

Agent Tools Overview

Platform Actions

message — Endpoint-Scoped Messaging

Quick Reference

Actions

Per-channel capability matrix

Inbound reactions: corroborating learning signal

Which channels capture inbound reactions

Operator setup

Endpoint-Scoped Routing

notify_user — Proactive Notifications

Related