Ryvos

Telegram Setup

1. Create a Bot

Open Telegram and message @BotFather
Send /newbot
Choose a display name (e.g., "My Ryvos Agent")
Choose a username (must end in bot, e.g., my_ryvos_bot)
BotFather gives you a bot token — save this

2. Get Your User ID

You need your Telegram user ID for the allowlist:

Message @userinfobot on Telegram
It replies with your user ID (a number like 123456789)

3. Configure Ryvos

[channels.telegram]
enabled = true
bot_token = "${TELEGRAM_BOT_TOKEN}"
dm_policy = "allowlist"
allowed_users = [123456789]

Set the environment variable:

export TELEGRAM_BOT_TOKEN="7123456789:AAF..."

4. Start the Daemon

ryvos daemon --gateway

5. Test It

Open Telegram and send a message to your bot:

You: Hello, what can you do?
Bot: I'm your Ryvos AI agent. I can help you with...

Telegram Features

Inline approval buttons — When the agent needs approval for a tool call, it sends a message with interactive buttons:

🔒 Approval needed: bash
Command: git push origin main
Tier: T3 (High)

[✅ Approve] [❌ Deny]

Message splitting — Responses longer than 4,096 characters are automatically split at paragraph boundaries.

Markdown formatting — The agent's responses are formatted with Telegram's MarkdownV2.

Multiple users — Add multiple user IDs to the allowlist:

[channels.telegram]
allowed_users = [123456789, 987654321, 111222333]

DM Policies

Allowlist (recommended)

Only listed users can interact:

[channels.telegram]
dm_policy = "allowlist"
allowed_users = [123456789]

Open

Anyone can interact (use with budget limits):

[channels.telegram]
dm_policy = "open"

:::caution With open DM policy, anyone who finds your bot can use it and consume your LLM API budget. Always configure [budget] limits when using open mode. :::

Disabled

No DM interactions:

[channels.telegram]
dm_policy = "disabled"

Troubleshooting

Issue	Solution
Bot does not respond	Check `ryvos doctor` output. Verify the bot token is correct.
"User not allowed" in logs	Add your user ID to `allowed_users`.
Messages cut off	This is Telegram's 4,096 char limit. Ryvos auto-splits, but some formatting may break at split points.
Bot goes offline	Check if the daemon is still running. Consider setting up a systemd service.

Discord Setup

1. Create a Discord Application

Go to the Discord Developer Portal
Click "New Application"
Name it (e.g., "Ryvos Agent")
Go to the Bot section
Click "Add Bot"
Copy the bot token

2. Configure Bot Permissions

Under the Bot section:

Enable Message Content Intent (required for reading message content)
Enable Server Members Intent (optional, for user info)

3. Generate an Invite Link

Go to OAuth2 > URL Generator:

Scopes: bot, applications.commands
Bot Permissions: Send Messages, Read Message History, Embed Links, Add Reactions, Use Slash Commands

Copy the generated URL and open it in your browser to add the bot to your server.

4. Get Your User ID

Enable Developer Mode in Discord (Settings > App Settings > Advanced > Developer Mode)
Right-click your username and select "Copy User ID"

5. Configure Ryvos

[channels.discord]
enabled = true
bot_token = "${DISCORD_BOT_TOKEN}"
dm_policy = "allowlist"
allowed_users = ["123456789012345678"]
guild_id = ""                          # Optional: restrict to one server

Set the environment variable:

export DISCORD_BOT_TOKEN="MTIz..."

6. Start the Daemon

ryvos daemon --gateway

7. Test It

Send a DM to your bot on Discord:

You: Hello, what's the weather?
Bot: I don't have a weather tool configured, but I can help with...

Discord Features

Rich embeds — Responses use Discord embeds for structured output:

┌──────────────────────────────────┐
│ 📋 Code Review Results            │
│                                   │
│ Found 3 issues in src/auth.rs:    │
│                                   │
│ 1. Line 42: unwrap() on network   │
│    response                        │
│ 2. Line 89: SQL injection risk     │
│ 3. Line 156: Mutex across await    │
│                                   │
│ 🟡 Priority: Medium                │
└──────────────────────────────────┘

Button components — Approval requests use Discord's interactive buttons.

Guild restriction — Optionally restrict the bot to a specific Discord server:

[channels.discord]
guild_id = "1234567890123456789"

DM Policies

Allowlist (recommended)

[channels.discord]
dm_policy = "allowlist"
allowed_users = ["123456789012345678"]

Open

[channels.discord]
dm_policy = "open"

:::caution With open DM policy, any Discord user who can find your bot can interact with it. Use budget limits. :::

Disabled

[channels.discord]
dm_policy = "disabled"

Troubleshooting

Issue	Solution
Bot shows as offline	Check daemon is running. Verify token in `ryvos doctor`.
"Missing Access" error	Re-invite the bot with correct permissions. Enable Message Content Intent.
Bot does not respond in DMs	Check `dm_policy` and `allowed_users`. Discord user IDs are strings (they are too large for integers).
Rich embeds not showing	Make sure the bot has the "Embed Links" permission in the server.
Rate limited	Discord has strict rate limits. Ryvos handles this with backoff, but very frequent messages may be delayed.

Running Both

Telegram and Discord can run simultaneously:

[channels.telegram]
enabled = true
bot_token = "${TELEGRAM_BOT_TOKEN}"
dm_policy = "allowlist"
allowed_users = [123456789]
 
[channels.discord]
enabled = true
bot_token = "${DISCORD_BOT_TOKEN}"
dm_policy = "allowlist"
allowed_users = ["123456789012345678"]

Both channels share the same agent runtime. Sessions from different channels are separate, but they share the same memory system. Something the agent learns via Telegram is available when interacting through Discord.

Next Steps

Slack & WhatsApp — Setup guides for Slack and WhatsApp
Channels Overview — All channels comparison
Configuration — Full channel config reference