> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Messaging

> Multi-channel delivery pipeline that enables agents to send messages, attachments, and polls across Telegram, Discord, Slack, WhatsApp, and more.

## Overview

Outbound Messaging is ArgentOS's multi-channel delivery pipeline. It enables agents to proactively send messages, attachments, polls, and rich content to any configured communication channel -- Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, MS Teams, Mattermost, and more.

Unlike inbound message handling (where channels push messages to the agent), outbound messaging is agent-initiated. The agent decides to send a message using the `message` tool, and the outbound pipeline handles channel resolution, target routing, session tracking, media handling, and cross-context policy enforcement.

## Architecture

```mermaid theme={null}
flowchart TD
    A["Agent Tool Call (message tool)"] --> B[Message Action Runner]
    B --> C[Outbound Send Service]
    C --> D[Channel Adapters]
    D --> E[Outbound Session Tracking]
```

## Message Actions

The system supports several action types:

| Action           | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| `send`           | Send a text message with optional media attachments           |
| `sendAttachment` | Send a file attachment with optional caption                  |
| `poll`           | Create a poll with question, options, and multiselect support |
| `broadcast`      | Send the same message to multiple targets across channels     |
| `setGroupIcon`   | Change a group chat's icon/avatar                             |
| `react`          | Add a reaction to a specific message                          |

### Send Action

The primary action. Supports text messages with markdown formatting, media attachments via URL/file path/base64, reply threading, buttons and cards (channel-dependent), and multiple media in a single message.

```typescript theme={null}
{
  action: "send",
  channel: "telegram",
  to: "user:123456",
  message: "Here's the report you requested.",
  media: "/path/to/report.pdf"
}
```

### Broadcast Action

<Warning>
  Broadcast must be explicitly enabled in config (`tools.message.broadcast.enabled: true`).
</Warning>

```typescript theme={null}
{
  action: "broadcast",
  targets: ["user:alice", "user:bob", "channel:general"],
  channel: "all",
  message: "Weekly standup reminder"
}
```

### Poll Action

Creates interactive polls (supported on Discord, Telegram, Slack):

```typescript theme={null}
{
  action: "poll",
  channel: "discord",
  to: "channel:general",
  pollQuestion: "When should we schedule the demo?",
  pollOption: ["Monday 2pm", "Tuesday 10am", "Wednesday 3pm"],
  pollMulti: true,
  pollDurationHours: 24
}
```

## Channel Resolution

When an agent sends a message, the system resolves the target channel:

1. **Explicit channel** -- If the agent specifies `channel: "slack"`, use that
2. **Tool context inference** -- If responding to an inbound message, use the same channel
3. **Configured channels** -- Query the list of configured message channels from `argent.json`

### Target Format Examples

| Channel  | Target Format Examples                         |
| -------- | ---------------------------------------------- |
| Telegram | `user:123456`, `group:-100123`, `@username`    |
| Discord  | `user:123456789`, `channel:987654321`          |
| Slack    | `user:U01ABC`, `channel:C01DEF`, `#general`    |
| WhatsApp | `+15551234567`, `group:120363...@g.us`         |
| iMessage | `+15551234567`, `user@icloud.com`              |
| Signal   | `+15551234567`, `group:abc123`                 |
| Matrix   | `@user:server.org`, `!roomid:server.org`       |
| MS Teams | `user:abc`, `conversation:19:...@thread.tacv2` |

## Media Handling

The outbound pipeline handles media through several mechanisms:

1. **URL resolution** -- HTTP/HTTPS URLs are downloaded and forwarded
2. **File paths** -- Local file paths are read and encoded
3. **Sandbox resolution** -- Paths within the agent sandbox are resolved safely
4. **Base64 encoding** -- Raw binary data is accepted as base64
5. **Size limits** -- Per-channel and per-account media size limits are enforced
6. **Content type inference** -- MIME types are detected from file extensions

<Note>
  Data URLs (`data:...`) are explicitly rejected to prevent agents from embedding large binary payloads in tool call parameters.
</Note>

## Delivery Pipeline

The full delivery flow for a `send` action:

<Steps>
  <Step title="Parse">Parse and validate tool parameters</Step>
  <Step title="Resolve channel">Resolve channel from hint, context, or config</Step>
  <Step title="Resolve target">Contact lookup, group resolution</Step>
  <Step title="Enforce policy">Enforce cross-context policy</Step>
  <Step title="Hydrate media">Download URLs, resolve paths, encode base64</Step>
  <Step title="Apply directives">Apply reply directives from message text</Step>
  <Step title="Resolve session">Resolve outbound session route</Step>
  <Step title="Ensure session">Ensure session entry exists for continuity</Step>
  <Step title="Execute send">Execute send via channel adapter or gateway relay</Step>
  <Step title="Return result">Return structured result to agent</Step>
</Steps>

## Abort Support

All outbound operations support abort signals for cancellation. If an agent run is aborted (user presses stop, timeout), in-flight message sends are cancelled cleanly via `AbortSignal`.

## Configuration

```json theme={null}
{
  "channels": {
    "telegram": {
      "botToken": "...",
      "enabled": true
    },
    "discord": {
      "botToken": "...",
      "enabled": true
    }
  },
  "tools": {
    "message": {
      "broadcast": {
        "enabled": false
      }
    }
  }
}
```