Messaging Apps
Connect your agents to Telegram and WhatsApp.
A Telegram or WhatsApp connection lets people talk to your agents from those apps. You connect a Telegram bot or a WhatsApp account in Desktop. Then you set routing rules that select the agent for each message.
How it works
- A person sends a text message to your bot or your WhatsApp account.
- The HQ gets the message. The HQ always opens the connection to the platform, so you do not open a port on your router.
- The HQ examines the routing rules and the block lists of the connection.
- The first rule that matches selects the agent. That agent does the work.
- The HQ sends the full reply back as one message when the agent completes its turn.
Each chat has its own conversation with the agent. A person who sends more messages in the same chat continues the same conversation.
Supported platforms
| Platform | How you connect | Sender IDs |
|---|---|---|
| Telegram | A bot that you make with BotFather. | The numeric Telegram user ID. A group has its own chat ID. |
| Your own WhatsApp account, linked as a device with a QR code. | The WhatsApp ID of the person, for example 6591234567@s.whatsapp.net. |
Both platforms send and receive text only. The HQ ignores photos, voice messages and other media.
Connect Telegram
In Desktop, open Settings → Messaging Apps. Click Connect app, then click Telegram. The wizard asks how much help you need. It gives three options:
| Option | What the wizard shows |
|---|---|
| First option | What Telegram and bots are, then all the steps below. |
| I know Telegram — help me create a bot | The BotFather steps and the steps after them. |
| I already have a bot token | Only the steps that start at Paste your bot token. |
Create a bot with BotFather
Open Telegram and find BotFather. Click Open BotFather in browser to open it from Desktop. Send /newbot. Give a name and a username that ends in bot.
Copy the bot token
BotFather shows a token, for example 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. Copy it.
Paste the token
Paste the token into Bot Token. Click Verify and continue. Desktop asks Telegram to confirm the token and shows the bot username.
Name the connection
Type a name in Connection Name. Desktop suggests a name from the bot name.
Choose the agent
Select the agent that answers messages to this bot. If no agent shows, deploy an agent first.
Restrict who can message the bot
Type the Telegram user IDs of the people who can use the bot in Allowed user IDs (comma-separated). To find your ID, send a message to @userinfobot in Telegram. Click Connect bot.
Do not skip the user ID list unless you want a public bot. If you skip the list, anyone who finds the bot can talk to your agent.
The HQ keeps the bot token in its encrypted credential store, not in the channel settings. While the agent works, the bot adds a 👀 reaction to the message. Telegram also shows that the bot is active.
Telegram accepts a maximum of 4096 characters in one message. If a reply is longer, the bot sends it as more than one message. It cuts the reply at a line break or a space when it can. These messages show as plain text, so some Markdown can show as you typed it.
Connect WhatsApp
WhatsApp uses the Linked Devices feature of your own WhatsApp account. You do not need a WhatsApp Business API account.
Start the wizard
In Desktop, open Settings → Messaging Apps. Click Connect app, then click WhatsApp. Read the first screen and click Continue.
Scan the QR code
On your phone, open WhatsApp. Go to Settings → Linked Devices → Link a Device. Scan the QR code that Desktop shows. When the link is complete, click Continue.
Name the connection
Type a name in Connection Name. The default name is "My WhatsApp".
Choose the agent
Select the agent that answers WhatsApp messages. Click Connect WhatsApp.
The wizard makes one Everyone rule. Thus, any person who sends a message to your WhatsApp account reaches the agent. To limit this, add routing rules and block lists after the setup.
Routing rules
Routing rules select the agent that gets each message. Open a connection in Settings → Messaging Apps to see its rules under Connected Agents.
Rule types
When you click Add routing rule, Who triggers this rule? gives three types:
| Option | What it matches |
|---|---|
| Specific people | Messages from the sender IDs in the list. |
| Specific groups | Messages in the group chats in the list. |
| Everyone | All messages. Desktop asks you to confirm this choice. |
Then select the agent in Route to agent and click Add rule.
How rules work together
The HQ examines the rules from top to bottom. The first rule that matches selects the agent. Use the arrow buttons to change the order. Put an Everyone rule at the bottom as a catch-all.
Rule 1: Specific people (alice's ID) → research agent
Rule 2: Specific groups (sales group ID) → sales agent
Rule 3: Everyone → general assistantIn this example, Alice always talks to the research agent. Messages in the sales group go to the sales agent. All other messages go to the general assistant.
If no rule matches, the HQ ignores the message. If a rule names an agent that does not exist, Desktop shows Agent not found and the HQ drops the messages for that rule.
Access control
Each connection has one global block list. Each rule also has two optional lists. To set them, open the advanced section at the bottom of the rule form.
| List | Where | What it does |
|---|---|---|
| Global Block List | The connection page | The HQ ignores all messages from these senders, for all rules. |
| Senders to let in | The advanced lists of a rule | Only these senders can reach the agent through this rule. Empty means all senders. |
| Senders to block | The advanced lists of a rule | The HQ ignores these senders for this rule. |
The HQ applies the two lists of a rule after it selects the rule. Thus, a blocked sender does not move on to the next rule.
Changes to rules and lists apply to the next message. You do not restart the HQ.
Chat commands
People in Telegram or WhatsApp can send these commands. The HQ answers the first two itself, without the agent.
| Command | What it does |
|---|---|
/help | Shows the list of commands. |
/skills | Shows the skills that the agent can use. |
/skill:<name> [input] | Tells the agent to use the skill. See Skills. |
/<plugin>:<command> [input] | Runs a plugin command. See Plugins. |
Telegram and WhatsApp cannot show question cards. When the agent asks a question, the HQ adds the question to the reply as text.
The HQ
The HQ keeps the connections to the platforms. It does these tasks:
- It connects to Telegram and WhatsApp when it starts.
- It gets new messages and applies the routing rules.
- It gives each message to the agent in the HQ.
- It sends the reply of the agent back to the platform.
The HQ must operate for your agents to answer. When the HQ starts, it discards the Telegram messages that people sent while it was stopped.
The HQ saves each connection to channels.json in its data directory. For an HQ that Desktop starts, that is ~/.dashsquad/<hq id>/channels.json. For a standalone HQ, it is ~/.dash/gateway/channels.json. The file has the platform, the routing rules and the block lists. The HQ keeps the Telegram bot token and the WhatsApp login in credentials.enc. See Secrets.
Desktop uses the HQ Management API to make connections. You can use the same API with a standalone HQ. First, store the bot token as the credential channel:<name>:token with POST /credentials. Then send POST /channels with the name, the adapter and the routing rules.
The API also has an allowedUsers list for Telegram. If this list has entries, the bot replies "Sorry, you are not authorized to use this bot." to all other senders. Desktop does not show this list. See Configuration for the HQ flags.