> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Messaging
> Send, reply, react, edit, and delete messages across channels
**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](#per-channel-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
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:**
```yaml theme={}
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.
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:**
```yaml theme={}
action: reply
channel_type: slack
channel_id: "support"
message_id: "msg_abc123"
text: "Great question! Here's what I found..."
```
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:**
```yaml theme={}
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.
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.
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.
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:**
```yaml theme={}
action: fetch
channel_type: discord
channel_id: "general"
limit: 5
```
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:**
```yaml theme={}
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](/reference/config-yaml#learning-outcome-agents-learningoutcome).
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`](/reference/config-yaml#learning-outcome-agents-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:**
```yaml theme={}
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.
## Related
Connect Discord, Telegram, Slack, and 5 more platforms
Sub-agents, pipelines, and session management
Master reference table of all tools
Moderation actions for Discord, Telegram, Slack, and WhatsApp