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:

string | number

required

Numeric Telegram chat ID (e.g., 123456789). NOT the username.

string

required

Message text. Supports markdown formatting.

Example:

{
  "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:

{
  "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:

string

required

WhatsApp JID (e.g., 1234567890@s.whatsapp.net for contacts, 123456@g.us for groups)

string

required

Message text

Example:

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

send_discord

Send a message to a Discord channel. Parameters:

string

required

Discord channel ID (17-20 digit snowflake)

string

required

Message text. Supports Discord markdown.

Example:

{
  "skill": "send_discord",
  "args": {
    "channel_id": "1234567890123456789",
    "message": "**Hello** from OrcBot!"
  }
}

send_slack

Send a message to a Slack channel or DM. Parameters:

string

required

Slack channel ID (e.g., C01234567)

string

required

Message text. Supports Slack mrkdwn.

Example:

{
  "skill": "send_slack",
  "args": {
    "channel_id": "C01234567",
    "message": "*Hello* from OrcBot!"
  }
}

send_email

Send an email via configured SMTP. Parameters:

string

required

Recipient email address

string

Email subject. Defaults to “OrcBot response”.

string

required

Email body (plain text or HTML)

string

Message-ID of email being replied to (for threading)

string

Space-separated Message-IDs for threading

Example:

{
  "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:

{
  "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:

string

required

Recipient ID (WhatsApp JID, Telegram chatId, Discord channelId)

string

required

Absolute file path

string

Optional caption

string

Override channel: telegram, whatsapp, discord, gateway-chat

Channel Detection:

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

Example:

{
  "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:

string

required

Recipient ID

string

required

Text to convert to speech (max 4096 chars)

string

Voice name. OpenAI: alloy, echo, fable, onyx, nova, shimmer. Google: achernar, alnilam, kore, etc.

Platform Differences:

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

Example:

{
  "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:

string

required

Recipient ID

string

required

Image generation prompt

string

Target channel override

string

default:"1024x1024"

Image size (1024x1024, 1024x1792, 1792x1024)

string

default:"medium"

Quality: standard, medium, hd

string

Optional caption

Example:

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

Always use send_image instead of generate_image + send_file. The compound skill prevents duplicates and provides atomic operations.

Telegram Rich Features

telegram_send_buttons

Send message with inline keyboard buttons. Parameters:

string | number

required

Telegram chat ID

string

required

Message text

array

required

2D array of button objects. Each button has text and callback_data or url.

Button Format:

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

Example:

{
  "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:

"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:

string | number

required

Telegram chat ID

string

required

Poll question

array

required

Array of 2-10 option strings

boolean

default:"true"

Whether votes are anonymous

boolean

default:"false"

Allow multiple selections

Example:

{
  "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:

string | number

required

Telegram chat ID

number

required

Message ID from send_telegram or telegram_send_buttons

string

required

Updated message text

Example:

{
  "skill": "telegram_edit_message",
  "args": {
    "chatId": "123456789",
    "messageId": 54321,
    "newText": "Deployment complete! ✅"
  }
}

Use Case: Live progress updates without spam:

// 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:

string | number

required

Telegram chat ID

number

required

Message ID to react to

string

default:"👍"

Emoji to react with

Example:

{
  "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:

string | number

required

Telegram chat ID

number

required

Message ID to pin

boolean

default:"true"

Don’t notify members about the pin

Example:

{
  "skill": "telegram_pin_message",
  "args": {
    "chatId": "123456789",
    "messageId": 54321,
    "silent": true
  }
}

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

Email Management

search_emails

Search inbox with filters. Parameters:

string

Search email body

string

Filter by sender address

string

Filter by subject line

number

Only emails from last N days

boolean

default:"false"

Only unread emails

number

default:"10"

Max results

Example:

{
  "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:

string

required

Email UID from search_emails

Example:

{
  "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:

{
  "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:

string

required

Report focus

array

Specific UIDs to analyze

string

Filter by sender

string

Filter by subject

number

default:"7"

Lookback window

Example:

{
  "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:

string

required

Message ID to react to

string

required

Emoji (raw or semantic: thumbs_up, love, fire, laugh, check, eyes, thinking)

string

Override channel detection

string

Override chat ID detection

Emoji Resolution:

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

Example:

{
  "skill": "react",
  "args": {
    "message_id": "54321",
    "emoji": "fire"
  }
}

Best Practices

Channel selection priority:

Use auto-detection when replying to messages
Set explicit channel parameter for proactive sends
Let the system fall back to configured channels

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.

Memory

Store and recall conversation context

Files

Send files and media

CLI Commands

Core Skills

Configuration

Channel Messaging

Channel Messaging

Core Messaging Skills

send_telegram

send_whatsapp

send_discord

send_slack

send_email

Rich Interactions

send_file

send_voice_note

send_image

Telegram Rich Features

telegram_send_buttons

telegram_send_poll

telegram_edit_message

telegram_react

telegram_pin_message

Email Management

search_emails

fetch_email

index_emails_to_knowledge_base

generate_email_report

Cross-Channel Reactions

react

Best Practices

Memory

Files

Channel Messaging

Core Messaging Skills

send_telegram

send_whatsapp

send_discord

send_slack

send_email

Rich Interactions

send_file

send_voice_note

send_image

Telegram Rich Features

telegram_send_buttons

telegram_send_poll

telegram_edit_message

telegram_react

telegram_pin_message

Email Management

search_emails

fetch_email

index_emails_to_knowledge_base

generate_email_report

Cross-Channel Reactions

react

Best Practices

Related Skills

Memory

Files