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

# Channel Messaging

> Multi-channel communication with Telegram, WhatsApp, Discord, Slack, and email

# Channel Messaging

OrcBot provides unified messaging across Telegram, WhatsApp, Discord, Slack, email, and a web gateway. All skills auto-detect the source channel and handle delivery seamlessly.

## Core Messaging Skills

### send\_telegram

Send a message to a Telegram user or group.

**Parameters:**

<ParamField path="chatId" type="string | number" required>
  Numeric Telegram chat ID (e.g., `123456789`). NOT the username.
</ParamField>

<ParamField path="message" type="string" required>
  Message text. Supports markdown formatting.
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "send_telegram",
  "args": {
    "chatId": "123456789",
    "message": "Hello from OrcBot!"
  }
}
```

**Auto-Resolution:**

If you pass a placeholder ID like `12345` or a name, the skill auto-fills from action metadata:

```json theme={null}
{
  "skill": "send_telegram",
  "args": {
    "chatId": "12345",
    "message": "Reply"
  }
}
// Auto-resolved to real chatId from incoming message metadata
```

### send\_whatsapp

Send a message to a WhatsApp contact or group.

**Parameters:**

<ParamField path="jid" type="string" required>
  WhatsApp JID (e.g., `1234567890@s.whatsapp.net` for contacts, `123456@g.us` for groups)
</ParamField>

<ParamField path="message" type="string" required>
  Message text
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "send_whatsapp",
  "args": {
    "jid": "1234567890@s.whatsapp.net",
    "message": "Hi from OrcBot!"
  }
}
```

### send\_discord

Send a message to a Discord channel.

**Parameters:**

<ParamField path="channel_id" type="string" required>
  Discord channel ID (17-20 digit snowflake)
</ParamField>

<ParamField path="message" type="string" required>
  Message text. Supports Discord markdown.
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "send_discord",
  "args": {
    "channel_id": "1234567890123456789",
    "message": "**Hello** from OrcBot!"
  }
}
```

### send\_slack

Send a message to a Slack channel or DM.

**Parameters:**

<ParamField path="channel_id" type="string" required>
  Slack channel ID (e.g., `C01234567`)
</ParamField>

<ParamField path="message" type="string" required>
  Message text. Supports Slack mrkdwn.
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "send_slack",
  "args": {
    "channel_id": "C01234567",
    "message": "*Hello* from OrcBot!"
  }
}
```

### send\_email

Send an email via configured SMTP.

**Parameters:**

<ParamField path="to" type="string" required>
  Recipient email address
</ParamField>

<ParamField path="subject" type="string">
  Email subject. Defaults to "OrcBot response".
</ParamField>

<ParamField path="message" type="string" required>
  Email body (plain text or HTML)
</ParamField>

<ParamField path="inReplyTo" type="string">
  Message-ID of email being replied to (for threading)
</ParamField>

<ParamField path="references" type="string">
  Space-separated Message-IDs for threading
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "send_email",
  "args": {
    "to": "user@example.com",
    "subject": "Weekly Report",
    "message": "Here is your weekly summary..."
  }
}
```

**Email Threading:**

Use `inReplyTo` and `references` for proper email threading:

```json theme={null}
{
  "skill": "send_email",
  "args": {
    "to": "user@example.com",
    "subject": "Re: Project Update",
    "message": "Thanks for the update...",
    "inReplyTo": "<msg-123@example.com>",
    "references": "<msg-123@example.com>"
  }
}
```

## Rich Interactions

### send\_file

Send a file with auto-detection of channel.

**Parameters:**

<ParamField path="jid" type="string" required>
  Recipient ID (WhatsApp JID, Telegram chatId, Discord channelId)
</ParamField>

<ParamField path="path" type="string" required>
  Absolute file path
</ParamField>

<ParamField path="caption" type="string">
  Optional caption
</ParamField>

<ParamField path="channel" type="string">
  Override channel: `telegram`, `whatsapp`, `discord`, `gateway-chat`
</ParamField>

**Channel Detection:**

1. Explicit `channel` parameter
2. Action source metadata
3. JID pattern detection:
   * `@s.whatsapp.net` or `@g.us` → WhatsApp
   * 17-20 digit number → Discord
   * Otherwise → Telegram

**Example:**

```json theme={null}
{
  "skill": "send_file",
  "args": {
    "jid": "1234567890@s.whatsapp.net",
    "path": "/home/user/.orcbot/downloads/report.pdf",
    "caption": "Here's the report you requested"
  }
}
```

### send\_voice\_note

Convert text to speech and send as voice message.

**Parameters:**

<ParamField path="jid" type="string" required>
  Recipient ID
</ParamField>

<ParamField path="text" type="string" required>
  Text to convert to speech (max 4096 chars)
</ParamField>

<ParamField path="voice" type="string">
  Voice name. OpenAI: alloy, echo, fable, onyx, nova, shimmer. Google: achernar, alnilam, kore, etc.
</ParamField>

**Platform Differences:**

* **WhatsApp/Telegram**: Sent as native voice note (playable inline bubble)
* **Discord**: Sent as audio file attachment (no native voice notes)

**Example:**

```json theme={null}
{
  "skill": "send_voice_note",
  "args": {
    "jid": "1234567890@s.whatsapp.net",
    "text": "Hello, this is a voice message from OrcBot!",
    "voice": "nova"
  }
}
```

### send\_image

Generate AI image and send in one step.

**Parameters:**

<ParamField path="jid" type="string" required>
  Recipient ID
</ParamField>

<ParamField path="prompt" type="string" required>
  Image generation prompt
</ParamField>

<ParamField path="channel" type="string">
  Target channel override
</ParamField>

<ParamField path="size" type="string" default="1024x1024">
  Image size (1024x1024, 1024x1792, 1792x1024)
</ParamField>

<ParamField path="quality" type="string" default="medium">
  Quality: standard, medium, hd
</ParamField>

<ParamField path="caption" type="string">
  Optional caption
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "send_image",
  "args": {
    "jid": "123456789",
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "channel": "telegram",
    "size": "1024x1024",
    "caption": "Here's your generated image"
  }
}
```

<Tip>
  **Always use `send_image` instead of `generate_image` + `send_file`.** The compound skill prevents duplicates and provides atomic operations.
</Tip>

## Telegram Rich Features

### telegram\_send\_buttons

Send message with inline keyboard buttons.

**Parameters:**

<ParamField path="chatId" type="string | number" required>
  Telegram chat ID
</ParamField>

<ParamField path="message" type="string" required>
  Message text
</ParamField>

<ParamField path="buttons" type="array" required>
  2D array of button objects. Each button has `text` and `callback_data` or `url`.
</ParamField>

**Button Format:**

```typescript theme={null}
buttons: [
  [
    { text: "Yes", callback_data: "yes" },
    { text: "No", callback_data: "no" }
  ],
  [
    { text: "Learn More", url: "https://example.com" }
  ]
]
```

**Example:**

```json theme={null}
{
  "skill": "telegram_send_buttons",
  "args": {
    "chatId": "123456789",
    "message": "Do you approve this deployment?",
    "buttons": [
      [{"text": "Approve", "callback_data": "approve"}, {"text": "Deny", "callback_data": "deny"}],
      [{"text": "View Changes", "url": "https://github.com/org/repo/pull/123"}]
    ]
  }
}
```

**Auto-coercion:**

If you pass a 1D array of button objects, the system auto-wraps each button in its own row:

```json theme={null}
"buttons": [{"text": "A", "callback_data": "a"}, {"text": "B", "callback_data": "b"}]
// Auto-converted to: [[{"text": "A", ...}], [{"text": "B", ...}]]
```

### telegram\_send\_poll

Create a native Telegram poll.

**Parameters:**

<ParamField path="chatId" type="string | number" required>
  Telegram chat ID
</ParamField>

<ParamField path="question" type="string" required>
  Poll question
</ParamField>

<ParamField path="options" type="array" required>
  Array of 2-10 option strings
</ParamField>

<ParamField path="isAnonymous" type="boolean" default="true">
  Whether votes are anonymous
</ParamField>

<ParamField path="allowsMultipleAnswers" type="boolean" default="false">
  Allow multiple selections
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "telegram_send_poll",
  "args": {
    "chatId": "123456789",
    "question": "Which deployment time works best?",
    "options": ["6 PM EST", "8 PM EST", "10 PM EST"],
    "isAnonymous": false
  }
}
```

### telegram\_edit\_message

Edit a previously sent message.

**Parameters:**

<ParamField path="chatId" type="string | number" required>
  Telegram chat ID
</ParamField>

<ParamField path="messageId" type="number" required>
  Message ID from send\_telegram or telegram\_send\_buttons
</ParamField>

<ParamField path="newText" type="string" required>
  Updated message text
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "telegram_edit_message",
  "args": {
    "chatId": "123456789",
    "messageId": 54321,
    "newText": "Deployment complete! ✅"
  }
}
```

**Use Case:**

Live progress updates without spam:

```typescript theme={null}
// Send initial message
send_telegram(chatId, "Deploying...")
// Returns: message_id 54321

// Update progress
telegram_edit_message(chatId, 54321, "Deploying... 50%")
telegram_edit_message(chatId, 54321, "Deploying... 100%")
telegram_edit_message(chatId, 54321, "Deployment complete! ✅")
```

### telegram\_react

React to a message with an emoji.

**Parameters:**

<ParamField path="chatId" type="string | number" required>
  Telegram chat ID
</ParamField>

<ParamField path="messageId" type="number" required>
  Message ID to react to
</ParamField>

<ParamField path="emoji" type="string" default="👍">
  Emoji to react with
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "telegram_react",
  "args": {
    "chatId": "123456789",
    "messageId": 54321,
    "emoji": "🔥"
  }
}
```

**Graceful Degradation:**

Telegram restricts bots from setting native reactions in most chat types. The skill automatically falls back to **replying** with the emoji:

```
Reacted with 🔥 via reply (native reaction unavailable for bots in this chat type)
```

Native reactions only work in **channels where the bot is admin**.

### telegram\_pin\_message

Pin a message to the top of a chat.

**Parameters:**

<ParamField path="chatId" type="string | number" required>
  Telegram chat ID
</ParamField>

<ParamField path="messageId" type="number" required>
  Message ID to pin
</ParamField>

<ParamField path="silent" type="boolean" default="true">
  Don't notify members about the pin
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "telegram_pin_message",
  "args": {
    "chatId": "123456789",
    "messageId": 54321,
    "silent": true
  }
}
```

<Note>
  Bot must be an admin in groups/channels to pin messages.
</Note>

## Email Management

### search\_emails

Search inbox with filters.

**Parameters:**

<ParamField path="query" type="string">
  Search email body
</ParamField>

<ParamField path="sender" type="string">
  Filter by sender address
</ParamField>

<ParamField path="subject" type="string">
  Filter by subject line
</ParamField>

<ParamField path="daysAgo" type="number">
  Only emails from last N days
</ParamField>

<ParamField path="unreadOnly" type="boolean" default="false">
  Only unread emails
</ParamField>

<ParamField path="limit" type="number" default="10">
  Max results
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "search_emails",
  "args": {
    "sender": "github-notifications@github.com",
    "daysAgo": 7,
    "unreadOnly": true,
    "limit": 5
  }
}
```

**Response:**

```
Found 5 matching emails:

--- EMAIL (UID: 12345) ---
From: github-notifications@github.com
Subject: [org/repo] New pull request #123
Preview: User opened a new pull request...

[4 more results]
```

### fetch\_email

Get full email by UID.

**Parameters:**

<ParamField path="uid" type="string" required>
  Email UID from search\_emails
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "fetch_email",
  "args": {
    "uid": "12345"
  }
}
```

### index\_emails\_to\_knowledge\_base

Ingest emails into RAG knowledge store.

**Parameters:**

Same as `search_emails`, plus `collection`.

**Example:**

```json theme={null}
{
  "skill": "index_emails_to_knowledge_base",
  "args": {
    "sender": "team@example.com",
    "daysAgo": 30,
    "collection": "team-emails",
    "limit": 50
  }
}
```

### generate\_email\_report

Synthesize multi-email report.

**Parameters:**

<ParamField path="topic" type="string" required>
  Report focus
</ParamField>

<ParamField path="emails" type="array">
  Specific UIDs to analyze
</ParamField>

<ParamField path="sender" type="string">
  Filter by sender
</ParamField>

<ParamField path="subject" type="string">
  Filter by subject
</ParamField>

<ParamField path="daysAgo" type="number" default="7">
  Lookback window
</ParamField>

**Example:**

```json theme={null}
{
  "skill": "generate_email_report",
  "args": {
    "topic": "Action items and blockers from team standup emails",
    "sender": "standup-bot@example.com",
    "daysAgo": 7
  }
}
```

**Response:**

```
## Email Synthesis Report

Topic: Action items and blockers from team standup emails
Based on 7 emails.

### Key Action Items
1. Alice: Complete API integration by Friday
2. Bob: Review security audit findings
3. Team: Schedule post-mortem for last week's outage

### Blockers
- Waiting on design mockups for feature X
- Database migration needs approval

### Decisions
- Deployment moved to Saturday for safety
```

## Cross-Channel Reactions

### react

Universal reaction skill with auto-detection.

**Parameters:**

<ParamField path="message_id" type="string" required>
  Message ID to react to
</ParamField>

<ParamField path="emoji" type="string" required>
  Emoji (raw or semantic: thumbs\_up, love, fire, laugh, check, eyes, thinking)
</ParamField>

<ParamField path="channel" type="string">
  Override channel detection
</ParamField>

<ParamField path="chat_id" type="string">
  Override chat ID detection
</ParamField>

**Emoji Resolution:**

* `thumbs_up` → 👍
* `love` → ❤️
* `fire` → 🔥
* `laugh` → 😂
* `check` → ✅
* `eyes` → 👀
* `thinking` → 🤔

**Example:**

```json theme={null}
{
  "skill": "react",
  "args": {
    "message_id": "54321",
    "emoji": "fire"
  }
}
```

## Best Practices

<Tip>
  **Channel selection priority:**

  1. Use auto-detection when replying to messages
  2. Set explicit `channel` parameter for proactive sends
  3. Let the system fall back to configured channels
</Tip>

<Warning>
  **Avoid cross-channel sends without permission.** Autonomy mode blocks cross-channel messaging unless the tool is exempt (like `send_email`) or the user is an admin.
</Warning>

## Related Skills

<CardGroup cols={2}>
  <Card title="Memory" icon="brain" href="/api/skills/memory">
    Store and recall conversation context
  </Card>

  <Card title="Files" icon="folder" href="/api/skills/files">
    Send files and media
  </Card>
</CardGroup>