Multi-Channel Messaging¶

Multi-Channel Messaging lets your agents respond to messages from external chat platforms — Telegram, Slack, Discord, and WhatsApp. Once configured, messages sent to your bot are routed to the appropriate Squad group for processing, and the agent's reply is sent back through the same channel.

Architecture¶

flowchart LR
    subgraph Channels
        TG[Telegram]
        SL[Slack]
        DC[Discord]
        WA[WhatsApp]
    end

    subgraph Backend.AI GO
        CR[Channel Registry]
        AL[Sender Allowlist]
        MR[Message Router]
        SQ[Squad Groups]
    end

    TG & SL & DC & WA --> CR
    CR --> AL
    AL -- allowed --> MR
    AL -- blocked --> X[Rejected]
    MR --> SQ
    SQ --> MR
    MR --> TG & SL & DC & WA

General Setup Process¶

For each channel:

1. Create a bot or app in the platform's developer portal
2. Copy the required tokens/credentials
3. Connect the channel in Backend.AI GO
4. Map the channel's chats to Squad groups
5. (Optional) Configure the sender allowlist

Telegram¶

Create a Telegram Bot¶

1. Open Telegram and start a chat with @BotFather.

2. Send /newbot and follow the prompts:

   • Choose a display name (e.g., "My AI Assistant")
   • Choose a username ending in bot (e.g., myai_assistant_bot)

3. BotFather replies with your Bot Token (format: 1234567890:ABCdef...). Copy it.

Connect Telegram in Backend.AI GO¶

1. In Settings > Squad, click the Telegram Bot card under Channels.

2. Paste your token into Bot Token. The form checks the token's format as you type: a malformed token shows "Invalid token format" under the field and keeps Connect disabled. It does not test the token against Telegram.

3. Optionally enter a Trigger Keyword (optional), a prefix the bot also responds to in group chats.

4. Click Connect.

5. The channel's badge changes to Connected when the bot is connected.

Telegram Trigger Behavior¶

JID Format¶

Telegram chat identifiers use the format tg:{chat_id} (e.g., tg:123456789).

Slack¶

Create a Slack App¶

1. Go to api.slack.com/apps and click Create New App.

2. Choose From scratch, enter an app name and select your workspace.

3. In the left sidebar, click OAuth & Permissions.

4. Under Bot Token Scopes, add these scopes:

   • app_mentions:read
   • channels:history
   • chat:write
   • groups:history
   • im:history
   • im:read
   • im:write

5. Click Install to Workspace and authorize. Copy the Bot User OAuth Token (xoxb-...).

6. In the left sidebar, click Socket Mode and enable it. Create an App-Level Token with connections:write scope. Copy the App Token (xapp-...).

7. Under Event Subscriptions, enable events and subscribe to:

   • app_mention
   • message.im

Connect Slack in Backend.AI GO¶

1. In Settings > Squad, click the Slack Bot card under Channels.

2. Paste your tokens into Bot Token (xoxb-) and App Token (xapp-). The form checks the format of both tokens as you type and keeps Connect disabled while either is malformed. It does not test the tokens against Slack.

3. Click Connect.

Slack Trigger Behavior¶

JID Format¶

Slack chat identifiers use the format slack:{channel_id} (e.g., slack:C01234567).

Discord¶

Create a Discord Bot¶

1. Go to the Discord Developer Portal and click New Application.

2. Give it a name and click Create.

3. Click Bot in the left sidebar.

4. Click Add Bot and confirm.

5. Under Token, click Reset Token and copy the token.

6. Under Privileged Gateway Intents, enable:

   • Message Content Intent (required to read message text)

7. Click OAuth2 > URL Generator. Under Scopes, select bot. Under Bot Permissions, select:

   • Read Messages/View Channels
   • Send Messages
   • Read Message History

8. Copy the generated OAuth2 URL and open it in a browser to invite the bot to your server.

Connect Discord in Backend.AI GO¶

1. In Settings > Squad, click the Discord Bot card under Channels.

2. Paste your token into Bot Token. The form checks the token's format as you type (a Discord bot token is at least 50 characters) and keeps Connect disabled while it is malformed. It does not test the token against Discord.

3. Optionally enter a Trigger Keyword (optional), a prefix the bot also responds to in guild channels.

4. Click Connect.

Discord Trigger Behavior¶

JID Format¶

Discord chat identifiers use the format discord:{channel_id} (e.g., discord:123456789012345678).

WhatsApp Business¶

WhatsApp uses the WhatsApp Business Cloud API and requires a verified Meta business account.

Prerequisites¶

• A Meta Developer Account
• A WhatsApp Business Account
• A phone number dedicated to the WhatsApp Business API

Configure WhatsApp Business API¶

1. Go to developers.facebook.com and create a new app of type Business.

2. Add the WhatsApp product to your app.

3. In the WhatsApp setup, note your:

   • Phone Number ID (numeric ID of your WhatsApp phone number)
   • WhatsApp Business Account ID

4. Generate a Permanent Access Token (or a temporary token for testing):

   • Go to Meta Business Suite > System Users
   • Create a system user with whatsapp_business_messaging permission
   • Generate a token for the system user

5. Configure the Webhook:

   • Webhook URL: https://{your-domain}/api/v1/channels/whatsapp/webhook
   • Verify Token: any string you choose (used during webhook verification)
   • Subscribe to messages events

Connect WhatsApp in Backend.AI GO¶

1. In Settings > Squad, click the WhatsApp Business card under Channels.

2. Fill in all four fields:

   • Phone Number ID: Your WhatsApp phone number ID
   • Business Account ID: Your WhatsApp Business Account ID
   • Access Token: Your permanent access token
   • Webhook Verify Token: The verify token you set in Meta's developer portal

   The form checks the formats of the Phone Number ID and Access Token as you type, and keeps Connect disabled while either is malformed. It does not contact Meta.

3. Click Connect.

4. Trigger the webhook verification from Meta's developer portal by clicking Verify and Save.

WhatsApp Trigger Behavior¶

All incoming direct messages trigger the bot. Group messages are supported when the phone number is added to the group.

JID Format¶

WhatsApp chat identifiers use the format wa:{phone_number} (e.g., wa:15551234567).

Managing Connected Channels¶

View Channel Status¶

curl http://localhost:8001/api/v1/channels

Response:

{
  "channels": [
    {"name": "telegram", "connected": true, "statusMessage": "Connected"},
    {"name": "slack", "connected": true, "statusMessage": "Connected"},
    {"name": "discord", "connected": false, "statusMessage": "Not configured"},
    {"name": "whatsapp", "connected": false, "statusMessage": "Not configured"}
  ]
}

Disconnect a Channel¶

1. In Settings > Squad, click the channel's card under Channels.

2. Click Disconnect.

Send a Message¶

curl -X POST http://localhost:8001/api/v1/channels/messages \
  -H "Content-Type: application/json" \
  -d '{"chatJid": "tg:123456789", "content": "Hello from Backend.AI GO!"}'

View Message History¶

# List all chats
curl http://localhost:8001/api/v1/channels/chats

# Get messages from a specific chat
curl "http://localhost:8001/api/v1/channels/chats/tg:123456789/messages?limit=50"

Sender Allowlist¶

The sender allowlist restricts which external users can interact with your agents. When configured, messages from senders not on the list are silently dropped.

Configure via Management API¶

curl -X PUT http://localhost:8001/api/v1/channels/sender-allowlist \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entries": [
      {"chatJid": "tg:123456789", "label": "Alice"},
      {"chatJid": "slack:U01ABCDEF", "label": "Bob"}
    ]
  }'

Behavior¶

Next Steps¶

• Channel-Squad Mapping — Route messages to specific squad groups
• Security Model — Understand the security layers