Slack Setup

Ryvos connects to Slack using Socket Mode, which does not require a public URL or webhook endpoint. This makes it easy to run from behind a firewall.

1. Create a Slack App

1. Go to api.slack.com/apps
2. Click "Create New App" > "From scratch"
3. Name it (e.g., "Ryvos Agent") and select your workspace

2. Enable Socket Mode

1. Go to Settings > Socket Mode
2. Enable Socket Mode
3. Create an App-Level Token with the scope connections:write
4. Copy the token (starts with xapp-)

3. Configure Bot Token Scopes

Go to Features > OAuth & Permissions and add these Bot Token Scopes:

4. Subscribe to Events

Go to Features > Event Subscriptions and subscribe to:

5. Install the App

1. Go to Settings > Install App
2. Click "Install to Workspace"
3. Authorize the permissions
4. Copy the Bot User OAuth Token (starts with xoxb-)

6. Get Your Slack User ID

1. Open Slack
2. Click your profile picture > "Profile"
3. Click the three dots (...) > "Copy member ID"

7. Configure Ryvos

[channels.slack]
enabled = true
bot_token = "${SLACK_BOT_TOKEN}"    # xoxb-... token
app_token = "${SLACK_APP_TOKEN}"    # xapp-... token (Socket Mode)
dm_policy = "allowlist"
allowed_users = ["U0123456789"]

Set the environment variables:

export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_APP_TOKEN="xapp-..."

8. Start and Test

ryvos daemon --gateway

DM your bot on Slack:

You: Hello, what can you do?
Ryvos: I'm your AI agent. I can help with file operations, git, code analysis...

Slack Features

Block Kit UI — Rich formatted messages with interactive elements:

┌──────────────────────────────────┐
│ 🔒 *Approval Required*           │
│                                   │
│ Tool: `bash`                      │
│ Command: `git push origin main`   │
│ Tier: T3 (High)                   │
│ Timeout: 60 seconds               │
│                                   │
│ [Approve ✅]  [Deny ❌]           │
└──────────────────────────────────┘

Slash commands — Register slash commands in the Slack app settings for quick actions.

Socket Mode — No public URL needed. Works behind firewalls and NAT.

Dual token auth — Bot token for API calls, App token for Socket Mode connection.

Troubleshooting

WhatsApp Setup

Ryvos connects to WhatsApp via Meta's Cloud API. This requires a Meta Business account and a verified WhatsApp Business phone number.

1. Set Up Meta Business

1. Go to developers.facebook.com
2. Create a Meta Developer account (or log in)
3. Create a new App > Business type
4. Add the WhatsApp product

2. Get Credentials

From the WhatsApp section of your app:

1. Temporary Access Token — Click "Get Temporary Access Token" (valid 24h, for testing)
2. Phone Number ID — Listed under your test phone number
3. Verify Token — You define this yourself (any random string)

For production, generate a permanent System User token:

1. Go to Business Settings > System Users
2. Create a System User with admin role
3. Generate a token with whatsapp_business_messaging permission

3. Configure the Webhook

Meta needs to verify your webhook endpoint. Ryvos exposes this at /api/hooks/whatsapp:

1. In the Meta Developer Portal, go to WhatsApp > Configuration
2. Set the Callback URL to https://your-domain.com/api/hooks/whatsapp
3. Set the Verify Token to the same value in your config
4. Subscribe to the messages webhook field

:::note WhatsApp requires a publicly accessible HTTPS URL for the webhook. If running locally, use a tunnel like ngrok:

ngrok http 8443

Then use the ngrok URL as the callback URL. :::

4. Configure Ryvos

[channels.whatsapp]
enabled = true
access_token = "${WHATSAPP_ACCESS_TOKEN}"
phone_number_id = "${WHATSAPP_PHONE_ID}"
verify_token = "${WHATSAPP_VERIFY_TOKEN}"
webhook_port = 8443
allowed_numbers = ["+1234567890"]     # E.164 format

Set the environment variables:

export WHATSAPP_ACCESS_TOKEN="EAAx..."
export WHATSAPP_PHONE_ID="123456789"
export WHATSAPP_VERIFY_TOKEN="my-random-verify-string"

5. Start and Test

ryvos daemon --gateway

Send a WhatsApp message to your business phone number:

You: Hello
Ryvos: I'm your AI agent. How can I help?

WhatsApp Features

E.164 phone numbers — The allowlist uses international phone number format:

allowed_numbers = ["+14155551234", "+447911123456"]

Message splitting — Responses over 4,096 characters are split at paragraph boundaries.

Text-based approvals — WhatsApp does not support interactive buttons in the same way, so approvals use text replies:

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

Reply "yes" to approve or "no" to deny (60s timeout)

Webhook verification — On initial setup, Meta sends a verification challenge. Ryvos handles this automatically using the verify_token.

WhatsApp Limitations

Troubleshooting

Running Both

Slack and WhatsApp can run simultaneously with all other channels:

[channels.slack]
enabled = true
bot_token = "${SLACK_BOT_TOKEN}"
app_token = "${SLACK_APP_TOKEN}"
dm_policy = "allowlist"
allowed_users = ["U0123456789"]
 
[channels.whatsapp]
enabled = true
access_token = "${WHATSAPP_ACCESS_TOKEN}"
phone_number_id = "${WHATSAPP_PHONE_ID}"
verify_token = "${WHATSAPP_VERIFY_TOKEN}"
webhook_port = 8443
allowed_numbers = ["+1234567890"]

All channels share the same agent runtime and memory system. The agent's learned knowledge is available across every channel.

Next Steps

• Telegram & Discord — Setup guides for Telegram and Discord
• Channels Overview — All channels comparison
• Webhooks & Gateway — HTTP API for programmatic access