Skip to main content
Messaging apps let your agents talk to people on platforms they already use. Connect a Telegram bot or WhatsApp number, set up routing rules, and your agents start responding to messages automatically.

​
How it works

Messages flow through a simple chain:
  1. A user sends a message on Telegram (or WhatsApp)
  2. The HQ receives it through the platform’s bot API
  3. Routing rules determine which agent should handle it
  4. The agent processes the message — thinking, using tools, and building a response
  5. The response flows back through the HQ to the messaging platform
The user sees a normal chat conversation. Behind the scenes, your agent is doing all the work.

​
Supported platforms

Telegram

Connect a Telegram bot to your agents. Supports individual and group chats, user allow lists, and per-sender routing.

WhatsApp

Connect a WhatsApp number to your agents. Same routing and access control features as Telegram.
More platforms are planned. The HQ uses an adapter pattern, so adding a new platform does not change how routing or agent interaction works.

​
Setting up Telegram

1

Create a bot with BotFather

Open Telegram and search for @BotFather. Send /newbot, follow the prompts, and copy the bot token it gives you. The token looks like 123456789:ABCdefGhIjKlmNoPqRsTuVwXyZ.
2

Add the bot in Desktop

In Desktop, open Settings → Messaging Apps and click to add a new Telegram connection. Give it a name (e.g. “Support Bot”) and paste your bot token. The token is stored in the encrypted secret store.
3

Configure routing rules

Set up rules that tell the HQ which agent should receive messages from this bot. You can route all messages to a single agent, or create more specific rules based on sender or group.
4

Enable the connection

Toggle the connection on. The HQ connects to Telegram’s bot API and starts listening for messages. Your agent is now reachable on Telegram.
Channels aren’t configured with a file — they’re created at runtime through the HQ’s Management API. Desktop is just a friendly front-end for that API.To set one up against a standalone HQ, POST /channels with the adapter, token, routing rules, and access lists, then enable it. See the Management API reference.

​
Setting up WhatsApp

1

Get your WhatsApp credentials

Set up a WhatsApp Business API account and obtain your access credentials.
2

Add the connection in Desktop

Open Settings → Messaging Apps, add a new WhatsApp connection, and enter your credentials. They are encrypted and stored securely.
3

Configure routing rules

Just like Telegram — define which agent handles incoming messages.
4

Enable the connection

Turn it on and your agent starts responding to WhatsApp messages.

​
Routing rules

Routing rules control which agent receives messages from each messaging app. Rules are evaluated in order — the first match wins.

​
Rule types

​
How rules work together

Rules are checked top to bottom. The first rule that matches determines which agent gets the message. A default rule at the bottom acts as a catch-all.
In this example, Alice always talks to the research agent. Messages in the Engineering group go to the coder. Everyone else reaches the general assistant.

​
Access control

Each messaging app also has access control lists:
  • Global deny list — Block specific users from reaching any agent through this messaging app. Evaluated before any routing rules.
  • Per-rule allow list — Restrict a routing rule to specific senders. If set, only listed senders can reach the agent through that rule.
  • Per-rule deny list — Block specific senders from a routing rule, even if they would otherwise match.
The global deny list is checked first. If a sender is on the deny list, their messages are ignored regardless of routing rules.

​
The HQ

The HQ is the process that hosts agents and handles all messaging platform connections. It takes care of:
  • Connecting to each platform’s bot API
  • Receiving incoming messages
  • Evaluating routing rules
  • Forwarding messages to the correct agent via the Chat API
  • Sending agent responses back to the platform
The HQ hosts agents in-process and serves the channel server on port 9200. Desktop’s built-in chat connects to the same channel server over WebSocket.
Each channel records its adapter type, bot token, routing rules, and access lists, and which agent to route to. The HQ persists channels to ~/.dash/gateway/channels.json and connects each adapter on startup. Edits made through Desktop (or PUT /channels/:name) take effect on the next message — no restart needed. Because the HQ hosts agents in-process, there are no separate agent server URLs to wire up.
The HQ starts on its data directory (~/.dash/gateway), reconnects any saved channels, and begins routing. Create or edit channels through its Management API, and supply bot tokens the same way (POST /credentials). It runs until stopped. See Configuration for the available flags.
When you manage messaging apps through Desktop, the HQ is handled automatically. Desktop:
  1. Saves your channel settings to the HQ via the Management API
  2. Stores bot tokens in the encrypted credential store
  3. Keeps the HQ process running
  4. Routes Desktop’s built-in chat through the HQ
There’s nothing to configure by hand.

​
What’s next

Squad

Learn how agents are configured and how they process messages.

Chat

Talk to agents via Desktop, Telegram, or WebSocket API.

Desktop

Deploy agents and manage messaging apps from the desktop app.

Architecture

How the HQ and Desktop fit together.