Channel Setup

Chvor supports multiple messaging channels out of the box. Each channel connects your self-hosted instance to an external platform, so users can interact with your agents from Telegram, Discord, Slack, or the built-in web chat.

You can run multiple channels simultaneously. Each channel operates independently — a message from Telegram does not appear in Discord, and conversations are scoped per-channel by default.

---

Web Chat (Built-in)

The web chat is the Brain Canvas itself. It requires no additional configuration — if Chvor is running, the web chat is available.

• URL: http://localhost:5173 (development) or your deployed domain
• Authentication: Protected by CHVOR_TOKEN if set (see Environment Variables)
• Features: Full Brain Canvas visualization, file uploads, conversation history

No setup needed. Move on to the other channels if you want external platform access.

---

Telegram

Step 1: Create a bot with BotFather

1. Open Telegram and search for @BotFather.
2. Send /newbot.
3. Follow the prompts to choose a name and username for your bot.
4. BotFather replies with your bot token — a string like 7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Copy it.

Step 2: Set the environment variable

Add the token to your .env file or environment:

TELEGRAM_BOT_TOKEN=7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 3: Restart Chvor

# If running from source
pnpm dev

# If running with Docker
docker restart chvor

Chvor starts polling the Telegram API for messages. You should see:

[telegram] Bot connected: @your_bot_username

Step 4: Configure the webhook (production)

Polling works for development, but for production you should use a webhook. This requires your Chvor instance to be publicly accessible over HTTPS.

Set the webhook URL by sending a request to the Telegram API:

curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook?url=https://your-domain.com/api/channels/telegram/webhook"

You should get:

{ "ok": true, "result": true, "description": "Webhook was set" }

Chvor handles incoming webhook payloads automatically once the route is hit.

Step 5: Test it

Open Telegram, find your bot, and send a message. You should get a response from your Chvor agent.

Telegram-specific features

• Group chats: Add your bot to a group. It responds when mentioned (@your_bot_username) or when a message matches a skill trigger.
• Inline mode: Not currently supported.
• Media: Users can send images and files. Chvor passes these to the LLM if the model supports multimodal input.

---

Discord

Step 1: Create a Discord application

1. Go to the Discord Developer Portal.
2. Click New Application and give it a name.
3. Go to the Bot tab on the left sidebar.
4. Click Add Bot, then confirm.
5. Under the bot’s token section, click Reset Token and copy the token.
6. Under Privileged Gateway Intents, enable:
   • Message Content Intent (required for reading messages)
   • Server Members Intent (optional, for user info)

Step 2: Generate an invite link

1. Go to the OAuth2 tab, then URL Generator.
2. Under Scopes, check bot.
3. Under Bot Permissions, check:
   • Send Messages
   • Read Message History
   • Embed Links
   • Attach Files
   • Use Slash Commands (optional)
4. Copy the generated URL and open it in your browser to invite the bot to your server.

Step 3: Set the environment variable

DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.Xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 4: Restart Chvor

pnpm dev
# or
docker restart chvor

You should see:

[discord] Bot connected: YourBot#1234
[discord] Serving 1 guild(s)

Step 5: Test it

Go to a channel where the bot has access and send a message. The bot responds in the same channel.

Discord-specific features

• Mention-based activation: By default, the bot only responds when mentioned (@YourBot) or when a message matches a skill trigger pattern.
• Thread support: The bot can participate in threads. Conversations within a thread share context.
• Slash commands: Chvor registers a /ask slash command automatically. Users can type /ask What is quantum computing? for explicit interaction.
• Embeds: Long responses are formatted as Discord embeds for better readability.

---

Slack

Step 1: Create a Slack app

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

Step 2: Configure Socket Mode

Socket Mode lets Chvor receive events without a public URL — ideal for development and firewalled environments.

1. Go to Socket Mode in the left sidebar.
2. Toggle Enable Socket Mode on.
3. Create an App-Level Token with the connections:write scope. Name it anything (e.g., “chvor-socket”). Copy the token — this is your SLACK_APP_TOKEN (starts with xapp-).

Step 3: Configure event subscriptions

1. Go to Event Subscriptions and toggle it on.
2. Under Subscribe to bot events, add:
   • message.channels — messages in public channels
   • message.groups — messages in private channels
   • message.im — direct messages
   • app_mention — when someone mentions your bot
3. Click Save Changes.

Step 4: Set OAuth scopes

1. Go to OAuth & Permissions.
2. Under Bot Token Scopes, add:
   • chat:write — send messages
   • channels:history — read public channel messages
   • groups:history — read private channel messages
   • im:history — read DMs
   • app_mentions:read — read mentions
   • files:read — read uploaded files
   • users:read — resolve user names
3. Click Install to Workspace (or reinstall if already installed).
4. Copy the Bot User OAuth Token (starts with xoxb-).

Step 5: Set environment variables

SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx
SLACK_APP_TOKEN=xapp-x-xxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 6: Restart Chvor

pnpm dev
# or
docker restart chvor

You should see:

[slack] Bot connected via Socket Mode
[slack] Bot user: @chvor

Step 7: Test it

Invite the bot to a channel (/invite @chvor), then send a message or mention it. The bot responds in a thread.

Slack-specific features

• Thread-based conversations: Responses are posted as thread replies, keeping channels clean.
• DM support: Users can message the bot directly for private conversations.
• Rich formatting: Chvor converts Markdown to Slack’s Block Kit format automatically.
• File handling: Users can share files with the bot. Supported files are passed to the LLM.

---

Running Multiple Channels

You can run all channels simultaneously. Set all the required environment variables and Chvor starts each enabled channel:

ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=7123456789:AAH...
DISCORD_BOT_TOKEN=MTIz...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

On startup, Chvor logs which channels are active:

[channels] Active: web, telegram, discord, slack

If a channel token is missing or invalid, that channel is skipped without affecting the others:

[channels] Active: web, telegram
[channels] Skipped: discord (no token), slack (no token)

---

Troubleshooting

Problem	Channel	Solution
Bot does not respond	Telegram	Check TELEGRAM_BOT_TOKEN is correct. Look for errors in server logs.
403 Missing Access	Discord	Ensure the bot has Message Content Intent enabled and proper permissions in the channel.
not_authed	Slack	Regenerate the bot token. Make sure both SLACK_BOT_TOKEN and SLACK_APP_TOKEN are set.
Duplicate responses	All	Make sure you are not running multiple Chvor instances with the same bot token.
Webhook not receiving	Telegram	Verify your domain has valid SSL. Telegram only sends webhooks over HTTPS.

---

Next Steps

• Deployment & Self-Hosting — make your instance publicly accessible for webhooks.
• Environment Variables — full reference of all channel-related variables.
• Creating Custom Skills — build skills that work across all channels.