Channel Setup

Zubo connects to multiple messaging platforms simultaneously. All channels share the same agent personality, memory, tools, and skills. Messages from any channel are routed through the unified agent loop — so your agent behaves consistently whether someone messages it on Telegram, Discord, Slack, WhatsApp, Signal, or the built-in web chat.

Copy-Paste Task Cards

zubo config set auth.enabled true
zubo auth create-key my-app

zubo config set failover '["openai","ollama"]'
zubo config set providers.ollama.model llama3.3

Common Errors

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3000/api/dashboard/status

zubo model openai/gpt-4o-mini
zubo logs --follow

ollama serve
ollama pull llama3.3

Web Chat (Always On)

The web chat channel is enabled by default and requires no configuration. When Zubo starts, it serves a full-featured chat interface and dashboard at http://localhost:<port>.

• No setup required — web chat is active out of the box
• Port — auto-assigned (0) by default, or set a specific port via config
• Features — streaming responses, file upload, voice input, tool status indicators, full conversation history
• Dashboard — the same URL serves the Zubo dashboard with analytics, memory management, skills, and settings

Configuration:

{
  "channels": {
    "webchat": { "enabled": true, "port": 3000 }
  }
}

Or set the port via CLI:

zubo config set channels.webchat.port 3000

Telegram

Connect Zubo to Telegram so you can chat with your agent from the Telegram app on any device.

Setup Steps

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to create a new bot. BotFather will give you a bot token (e.g., 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
3. Add the token to your Zubo config:

   zubo config set channels.telegram.botToken "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

4. (Optional) Restrict access to specific Telegram users by their numeric user ID:

   {
     "channels": {
       "telegram": {
         "botToken": "123456:ABC-DEF...",
         "allowedUsers": [12345678]
       }
     }
   }

5. Restart Zubo: zubo restart

Getting your Telegram user ID: search for @userinfobot on Telegram and send it any message. It will reply with your numeric user ID.

Config Fields

Discord

Add Zubo as a Discord bot so it can respond to messages in your server.

Setup Steps

1. Go to the Discord Developer Portal
2. Click New Application and give it a name
3. Go to the Bot section in the left sidebar, then click Reset Token to generate a bot token. Copy and save it.
4. Still in the Bot section, scroll down to Privileged Gateway Intents and enable Message Content Intent
5. Go to OAuth2 → URL Generator in the left sidebar. Select the bot scope, then check the Send Messages and Read Message History permissions.
6. Copy the generated URL at the bottom and open it in your browser to invite the bot to your server
7. Add the token to your Zubo config:

   zubo config set channels.discord.botToken "MTk4NjIz..."

8. Restart Zubo: zubo restart

Config Fields

Slack

Connect Zubo to your Slack workspace using Socket Mode for real-time communication without exposing a public URL.

Setup Steps

1. Go to api.slack.com/apps and click Create New App. Choose "From scratch" and select your workspace.
2. In the left sidebar, go to Settings → Socket Mode and enable it
3. When prompted, generate an App-Level Token with the connections:write scope. Copy this token (it starts with xapp-).
4. Go to OAuth & Permissions in the left sidebar. Under Bot Token Scopes, add: chat:write, app_mentions:read, im:history, im:read, im:write
5. Click Install to Workspace at the top of the page and authorize. Copy the Bot User OAuth Token (it starts with xoxb-).
6. Add both tokens to your Zubo config:

   {
     "channels": {
       "slack": {
         "botToken": "xoxb-...",
         "appToken": "xapp-...",
         "allowedUsers": []
       }
     }
   }

7. Restart Zubo: zubo restart

Config Fields

WhatsApp

Zubo connects to WhatsApp using the Baileys library, which provides an unofficial WhatsApp Web API. No Meta Business account or phone number API is required — it works by linking as a companion device to your existing WhatsApp account.

Setup Steps

1. Add WhatsApp to your Zubo config:

   {
     "channels": {
       "whatsapp": { "enabled": true }
     }
   }

2. Start (or restart) Zubo. A QR code will appear in your terminal.
3. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device
4. Scan the QR code displayed in the terminal
5. Once linked, Zubo will respond to incoming WhatsApp messages

Config Fields

Signal

Connect Zubo to Signal using signal-cli, a command-line interface for the Signal messenger.

Setup Steps

1. Install signal-cli on your system:

   # macOS
   brew install signal-cli
   
   # Linux (download from GitHub releases)
   # See: https://github.com/AsamK/signal-cli/releases

2. Register your phone number with Signal:

   signal-cli -u +1234567890 register

3. Verify the number with the SMS code you receive:

   signal-cli -u +1234567890 verify 123-456

4. Add Signal to your Zubo config:

   {
     "channels": {
       "signal": {
         "phoneNumber": "+1234567890",
         "signalCliPath": "/usr/local/bin/signal-cli",
         "allowedNumbers": ["+1987654321"]
       }
     }
   }

5. Restart Zubo: zubo restart

Config Fields

Email

Connect Zubo to an email account via IMAP/SMTP so it can receive and reply to emails. Great for workflows like processing incoming emails, auto-replies, or email-based task management.

Prerequisites

• An email account with IMAP and SMTP access (Gmail, Outlook, FastMail, etc.)
• For Gmail, an App Password is required — your regular Google account password will not work

Setup Steps

1. Gather your IMAP and SMTP server details from your email provider (host, port, username, password)
2. Add the email channel to your Zubo config:

   {
     "channels": {
       "email": {
         "enabled": true,
         "imap": {
           "host": "imap.gmail.com",
           "port": 993,
           "user": "you@gmail.com",
           "password": "your-app-password",
           "tls": true
         },
         "smtp": {
           "host": "smtp.gmail.com",
           "port": 587,
           "user": "you@gmail.com",
           "password": "your-app-password",
           "tls": true
         },
         "pollIntervalSeconds": 60,
         "allowedSenders": ["boss@company.com", "team@company.com"],
         "fromName": "Zubo Assistant"
       }
     }
   }

3. Restart Zubo: zubo restart

Config Fields

Security note — allowedSenders: If set, only emails from the listed addresses will be processed. All other incoming emails are marked as read and skipped. If allowedSenders is omitted or empty, Zubo will process every incoming email — use this only for private or low-traffic mailboxes.

Gmail setup: Gmail requires an App Password for third-party IMAP/SMTP access. To create one, go to Google Account → Security → App Passwords (requires 2-Step Verification to be enabled). Generate a new app password, then use that 16-character password in both the imap.password and smtp.password fields above.

Running Multiple Channels

Zubo is designed to run all channels simultaneously. There is no limit to how many channels you can enable at once.

• Shared state — all channels share the same memory, personality, tools, skills, and session. Your agent has one unified brain regardless of which platform a message comes from.
• Automatic routing — when a message arrives from Telegram, Discord, or any other channel, it goes through the same agent loop. The response is automatically sent back to whichever channel the message originated from.
• Proactive messages — scheduled tasks, alerts, and proactive triggers can broadcast to all connected channels simultaneously, or target a specific channel.
• Per-channel formatting — while the agent personality is shared, each channel adapter handles platform-specific formatting (Markdown for Telegram, embeds for Discord, blocks for Slack, etc.).

Channel Security

Controlling who can interact with your agent is critical, especially for public-facing deployments.

• Access control — use allowedUsers or allowedNumbers on each channel to restrict who can send messages. When the list is empty, anyone on that platform can message your agent.
• Rate limiting — the web chat channel enforces rate limits per IP address. Other channels enforce rate limits per user ID. Configure limits via rateLimit.chatPerMinute in your config.
• API authentication — enable bearer token auth for the web chat HTTP endpoints by setting auth.enabled: true in your config. See the Security & Auth guide for details.
• Tool confirmation — destructive tools like shell, file_write, and secret_delete require explicit user confirmation before executing, regardless of channel.

Best Practices

• Always set allowedUsers for public-facing channels — without it, anyone who finds your bot can interact with your agent and its tools
• Start with web chat only, then add channels one at a time as needed. This makes it easier to debug connection issues.
• Disable without removing — use zubo config set channels.telegram.enabled false to temporarily disable a channel without deleting its configuration
• Check logs if a channel is not connecting: zubo logs will show connection errors and status updates for each channel adapter
• Monitor from the dashboard — the Settings → Channels page shows real-time connection status for every enabled channel
• Keep tokens secure — bot tokens grant full control over your bot. Never share them or commit them to version control. Zubo stores them in ~/.zubo/config.json with restricted file permissions.
• Test incrementally — after adding a new channel, send a simple test message before relying on it for important tasks