Channels

Channels let your end-users talk to askTheodor through their everyday messenger. An inbound message matches a routing rule, gets dispatched to the right worker (or a Company’s CEO, or Kafenio), and a reply ships back out the same wire. Email and Signal are live, WhatsApp ships via an unofficial bridge, Telegram arrives in the next update, and several more channels are on the roadmap.

The same screen holds the 📱 Phone console (from the next update), which lets you command your team from your phone over these channels. See Phone console below.

Crucially, inbound handling is draft-only by default: a worker prepares a reply for you to review — nothing is sent on the channel until you approve it.

Add a channel

The top grid shows a card for every known channel. Live ones are highlighted; planned ones are dimmed and labeled Coming soon.

Live now: 📧 Email (SMTP send + IMAP receive) and 💬 Signal (via signal-cli).
Bridge: 🟢 WhatsApp — works through an unofficial WhatsApp Web bridge (see the caution below).
Next update: Telegram, through the official Bot API (see Telegram below).
On the roadmap: Discord, Slack, Microsoft Teams, and Viber. The architecture is already in place — when an adapter ships, your existing routing rules and workforce pick up the new wire with no reconfiguration.

Click a live card to add a channel of that kind; click a planned one to read a short “what’s coming” note.

Configure a channel

Each configured channel is a row with its label, an Enabled toggle, 🔍 Test (a health check), ▾ Configure (the per-kind editor), and 🗑 Delete. The row also shows when it was last polled and any last error.

Email (SMTP / IMAP)

SMTP host / port — your outgoing mail server (e.g. mail.smtp2go.com, port 587). A 📮 Use SMTP2Go preset button fills the host and port for that relay.
Username / Password — your SMTP login (an app password if your provider requires one).
From address — the address replies are sent from, header included (e.g. askTheodor <ai@your-domain.com>).
IMAP host / port / folder — your incoming mail server, so askTheodor can read inbound mail (e.g. imap.gmail.com, port 993, folder INBOX).
💾 Save, then 📨 Test send to a known address to confirm delivery.

Signal

signal-cli path — path to the signal-cli program. Leave blank to find it on your PATH.
Phone number — the number, with country code, already registered with signal-cli.
💾 Save and 📨 Test send as with Email.

⚠️ Unofficial bridge — this drives WhatsApp Web via whatsapp-web.js and is not endorsed by WhatsApp; it can get a number banned. Use a number you control, for personal/testing use only.
Bridge port — the local port the Node bridge listens on (one per number; default 8788).
Session name — identifies the saved login; change it to link a second number.
🔗 Pair (scan QR) — starts the bridge and shows a QR code; scan it from WhatsApp → Linked devices → Link a device. Status updates automatically once linked. 🔓 Log out / new QR unlinks the number to generate a fresh code.
Advanced — optional Node path, bridge directory, and Chrome path.

From 0.9.283, WhatsApp setup works like this:

Make sure Node.js 18+ is installed on this computer. The first 🔗 Pair (scan QR) sets the bridge up by itself.
Click 🔗 Pair (scan QR). The first QR can take up to 2 minutes while WhatsApp Web starts in the background. The status line says so while you wait.
On your phone, open WhatsApp → Settings → Linked devices → Link a device, and scan the code. The status changes to ● Linked with your number.
Choose what happens with messages other people send, then 💾 Save.

Other buttons: ↻ Status re-checks the bridge, ⏹ Stop bridge stops it, and 🔄 Re-pair appears once the number is linked.

Session name is not a display name. It only names the saved login on this computer. Leave it blank for the default (asktheodor), and change it only to link a second number.
▸ Advanced → Node path: if the app can’t find Node.js, enter the full path here (for example /usr/local/bin/node or /opt/homebrew/bin/node). Blank means “find node myself”.
▸ Advanced → Chrome path: optional. Reuse an installed Google Chrome instead of the browser the bridge downloads.
📨 Send test message sends one test message to the phone number in the box next to it. Enter it in full international format, digits only, e.g. 4915123456789. It’s for checking delivery, not for talking to your agents.

To talk to your agents, write in WhatsApp’s “Message yourself” chat on your phone (the chat with your own number), e.g. help. Replies arrive in the same chat within a minute. For this, the phone console must be on, with your number added.

Messages other people send to this number

Only the numbers under 📱 Phone console can command your team. For everyone else, pick one mode:

Mode	What happens
🔒 Private	askTheodor ignores them: not stored, not answered. Your chats stay yours.
🗂 Secretary	Each message is noted as a request and passed to you with a code. You answer with `reply <code> <answer>` or file it with `done <code>`. It’s never acted on.
🤖 Handled by workers	The routing rules decide which worker answers. Use this for a dedicated askTheodor number that customers write to.

In 🗂 Secretary mode, Send a short acknowledgement (once per person per 12 h) is on by default. It sends the sender a polite reply that says plainly it’s an automated assistant:

Hi! This is an automated assistant 🎩 — I’ve noted your message and passed it on. You’ll get a personal reply as soon as possible.

You can replace it with your own text in the box below the checkbox. A sender gets at most one acknowledgement every 12 hours. Requests show in Theodor’s Inbox, under tasks in the phone console, and on your phone if pushes are on. Press 💾 Save after changing the mode.

Answers from leads you contacted through lead-gen are still picked up in every mode.

Telegram uses the official Bot API. There’s no bridge and no phone pairing, which makes it the easiest and safest way to reach askTheodor from your phone.

In Telegram, open @BotFather, send /newbot, follow the steps, and copy the token.
In Add a channel, click the Telegram card. Paste the Bot token (it looks like 123456:ABC-DEF…), click Save, and enable the channel.
Message your bot once. Your chat id then shows in the Inbox as the sender.
Add that chat id under 📱 Phone console to command your team.

Allowed chat ids — optional, comma-separated. Only these chats may write to the bot at all. Empty means anyone may write to it; people who aren’t phone-console owners then go through the routing rules.
📨 Test send sends “Hello from askTheodor 🎩” to the chat id you enter.

Phone console

The 📱 Phone console panel sits at the top of the Channels tab. It lets you chat with your workers and CEOs, hand out tasks, approve drafts and get reports from WhatsApp, Signal, Telegram or e-mail. What you can write is on the Phone console page.

Connect a messenger channel first (above). Do it on one machine only, ideally the one that’s always on.
Click Set up on the 📱 Phone console panel.
Tick Let my own number/address command the team.
Under My addresses, click + Add my number / address. Pick the channel (or any channel) and enter your WhatsApp or Signal number, your Telegram chat id, or your e-mail address. The first address also receives pushes and the daily report.
Choose Push results, replies, failures and new drafts to my phone, and the hour for Daily report at (or off).
If you’ll send commands by e-mail, set an E-mail passphrase. Every e-mail command must contain it.
Click Save. The pill next to the title switches to on.
Click 📲 Send me a test to check the path to your phone.

Try it here — exactly what your phone would get. Below the settings is a small chat box. Type help, list, tasks, report, @name hi or #company … and press Send. You see the same answers your phone would get, and workers’ answers appear when they’re ready. It works before any phone is connected.

Only the addresses you add here can command your team. Everyone else still goes through the routing rules, or, on WhatsApp, through the number’s mode for other people’s messages.

Routing rules

A routing rule decides where an inbound message goes. When a message lands, the first matching rule wins. Each rule has:

Enabled — whether the rule is active.
⚡ act — let the routed worker act (use its tools to handle the request), not just reply. Tools stay gated by the worker’s autonomy allowlist and the global kill-switch.
📝 draft — draft only: the worker prepares a reply that’s saved for your review and nothing is sent on the channel. Use this for digests and draft-and-review flows.
Channel — which channel this rule watches.
From pattern — a case-insensitive substring matched against the sender (e.g. acme.com). Empty matches everyone on that channel.
Subject pattern (Email) — an optional substring matched against the subject line.
Target — where to send it: → Worker (pick one), → Company CEO (pick a company), → Kafenio (the staff room), or → Report (a report trigger).

Use + Add routing rule to create one and 🗑 to delete it.

In practice

Use a dedicated address, not your main inbox. Point the channel at something like hello@ or a forwarding alias rather than your personal mailbox. It keeps the worker’s scope obvious, makes routing rules simpler, and means a misconfiguration can’t touch mail you care about.

Use an app password where the provider offers one. Gmail and most major providers issue single-purpose credentials for programs. That’s both safer than your account password and easier to revoke if you change your mind.

Set up the Library before you connect the channel. A channel worker with nothing to ground its answers will draft plausible generic replies you’ll rewrite entirely. Your top questions, prices, delivery times and policies first — then the drafts are worth reviewing.

Start with one narrow routing rule. Route a single sender or subject pattern to one worker and watch the drafts for a week before widening. A broad rule on day one produces a lot of drafts you didn’t ask for and can’t easily evaluate.

Everything inbound is untrusted. A message can contain text crafted to read as an instruction to the worker processing it. Replies stay drafts, and the channel worker’s allowlist should be narrow — capability it doesn’t hold can’t be turned against you.

🎓 Learn it hands-on: OAuth sign-in · Run your team from WhatsApp · Your own Telegram bot in 5 minutes

Terms in this page

Channel — an external messenger (Email, Signal, WhatsApp, Telegram, …) connected to askTheodor so people can reach your workers through it.
SMTP — the protocol for sending email. You give askTheodor your outgoing mail server’s host, port, and login.
IMAP — the protocol for reading received email. You give askTheodor your incoming mail server so it can see inbound messages.
App password — a single-purpose password some email providers issue for programs, used instead of your main account password.
signal-cli — a command-line program for the Signal messenger that askTheodor drives to send and receive Signal messages.
Bridge — a helper program that connects askTheodor to a service that has no official API. The WhatsApp bridge automates WhatsApp Web.
QR pairing — linking a device by scanning a one-time QR code, the way WhatsApp Web links to your phone.
Session name — the name of the saved WhatsApp login on this computer; not shown to anyone.
Bot token — the secret @BotFather gives you for a Telegram bot; it lets askTheodor act as that bot.
Chat id — the number Telegram uses for a chat; you register yours as a phone-console owner.
Phone console — commanding your team from your phone; see Phone console.
Owner — an address registered in the phone console; only owners can command the team.
Private / Secretary / Handled by workers — the three modes for messages other people send to a WhatsApp number.
Acknowledgement — the short automatic reply a sender gets in secretary mode, at most once per 12 h.
Routing rule — a condition (which channel, which sender, optional subject) that decides which worker or destination an inbound message is dispatched to.
From / subject pattern — case-insensitive substring matches against the sender address and the email subject; the first matching rule wins.
Draft-only — the worker writes a reply that’s saved for your review and nothing is sent on the channel until you approve it. The default for inbound messages.
Act (⚡) — permission for the routed worker to use its tools to handle a request, still bounded by its autonomy allowlist and the global kill-switch.
Company CEO — the lead worker of a Company; routing to it hands the message to that team.
Kafenio — askTheodor’s shared staff room where workers talk to each other; a message can be routed there.
Kill-switch — the one-click global stop that pauses all worker tool use; it overrides channel auto-replies too.