Channels
Every chat app Habakkuk can talk on, how each one connects, how much setup it takes, and which one to start with.
A channel is one account on one chat platform: a Telegram bot, a Slack app, a WhatsApp agent. Channels live under channels: in config.yaml, keyed by an account name you choose, with a type. habakkuk serve runs them, and habakkuk channels (or /status in a chat) shows their health.
yaml
channels:
telegram: # the account name: yours to choose
type: telegram # the platform
token_env: TELEGRAM_BOT_TOKENTip
Start with a WhatsApp agent or Telegram. Both connect by polling, so they need no public URL, and habakkuk setup checks the key or token for you. A WhatsApp agent takes about a minute; a Telegram bot takes two.
All channels#
"Public URL" means the platform calls Habakkuk over the internet, so habakkuk serve needs an HTTPS address it can reach (see Webhook channels).
| Channel | type |
Connects by | Public URL | Setup |
|---|---|---|---|---|
| WhatsApp agent | whatsappagent |
long polling | no | easy, in habakkuk setup |
| WhatsApp linked device | whatsapp |
a linked device, like WhatsApp Web | no | easy, in habakkuk setup |
| WhatsApp Business Cloud API | whatsappcloud |
webhook + Graph API | yes | involved: a Meta app and business account |
| Telegram | telegram |
long polling | no | easy, in habakkuk setup |
| Slack | slack |
Socket Mode | no | moderate: a Slack app, in habakkuk setup |
| Discord | discord |
Gateway websocket | no | moderate: a bot application, in habakkuk setup |
| Signal | signal |
a signal-cli daemon | no | moderate: run signal-cli |
| Matrix | matrix |
/sync long polling |
no | moderate: a bot account and token |
email |
IMAP (IDLE or polling) + SMTP | no | easy: a mailbox and an app password | |
| SMS | sms |
Twilio webhook + REST | yes | moderate: a Twilio number |
| Microsoft Teams | msteams |
Bot Framework webhook | yes | involved: an Azure bot registration |
| Google Chat | googlechat |
Chat app HTTP endpoint | yes | involved: a Google Cloud project |
| iMessage | bluebubbles |
a BlueBubbles server on a Mac | yes | moderate: a Mac that stays on |
| Web chat | web |
Habakkuk's own HTTP server | no | easy, in habakkuk setup |
| LINE | line |
webhook | yes | moderate |
| Mattermost | mattermost |
WebSocket + REST | no | easy |
| IRC | irc |
TLS, SASL PLAIN | no | easy |
| ntfy | ntfy |
JSON stream + publish | no | easy |
| Messenger | messenger |
webhook + Graph API | yes | involved: a Meta app |
instagram |
webhook + Graph API | yes | involved: a Meta app | |
| Feishu / Lark | feishu |
event subscription + IM API | yes | moderate |
| DingTalk | dingtalk |
robot HTTP callback | yes | moderate |
| WeCom | wecom |
app callback + message API | yes | moderate |
| Zulip | zulip |
event queue long-poll + REST | no | easy |
| Rocket.Chat | rocketchat |
realtime API + REST | no | easy |
| Nextcloud Talk | nextcloudtalk |
Talk bot webhook | yes | moderate |
| Twitch chat | twitch |
IRC over TLS | no | easy |
What has been tested live#
Three channels have run against the real service so far:
- WhatsApp linked device (
whatsapp), linked to a real account. - WhatsApp agents (
whatsappagent). - Slack over Socket Mode (
slack), including two Slack apps side by side.
The web chat is Habakkuk's own HTTP server, so its tests exercise the real thing.
Every other channel in the table is built against the platform's documented API and tested here with a fake platform server. None of them has run against the real service yet. Expect rough edges there, and please report what you find with the output of habakkuk logs -level warn -since 1h.
How channels work#
- Who may talk. Direct messages from someone not in
allow_fromget a pairing code that you approve withhabakkuk pair CODE. See Access, groups and delivery. - Groups. In groups the bot answers only when addressed (a mention, a reply, or the platform's equivalent).
groups: allanswers everything;offignores groups. - One conversation, one session. Each chat (and each thread, where the platform has them) is a conversation with its own session. A fresh session starts after 24 hours of silence or when you send
/new. - Exactly once. A redelivered message never runs twice, a reply is delivered once, and a long reply resumes at the first unsent chunk after a crash.
- Replies keep their context. When you reply to (quote) a message, the agent sees what you quoted. Messages that reached the chat from elsewhere, such as a scheduled task's result or another agent's question, are shown to the agent on your next message. See Access, groups and delivery and Sessions.
- Supervised. Every adapter runs under a supervisor that restarts it with backoff and tears down a connection that stays silent too long.
- Several at once. Run as many channels as you like, of the same or different types, and route each one (or each conversation) to a different agent.
Next steps#
In this section
- Access, groups and deliveryWho may talk to the bot, pairing codes, group rules, webhook channels, the settings every channel takes, how delivery works, and what each platform supports.
- WhatsAppThe three ways to reach Habakkuk on WhatsApp, compared: a WhatsApp agent from Settings > Agents, a linked device on your number, and the Business Cloud API.
- TelegramConnect a Telegram bot in two minutes: long polling with no public URL, groups and forum topics, approval buttons, reactions, polls and voice notes.
- SlackConnect a Slack app over Socket Mode: one connection for every workspace, mentions and threads, files, reactions and approval buttons, with no public URL.
- DiscordConnect a Discord bot over the Gateway: the Message Content intent, invite permissions, servers and threads, buttons, reactions and polls.
- SignalConnect a Signal number through a signal-cli daemon: register or link the number, keep the daemon on loopback, and approve people by phone number.
- MatrixConnect a Matrix account with an access token: invites from allowed users, direct chats, rooms and threads; end-to-end encryption is not supported yet.
- EmailGive Habakkuk a mailbox: IMAP with IDLE or polling, SMTP replies that keep the thread, sender checks, and why email sessions start tainted.
- SMSText Habakkuk over SMS and MMS through a Twilio number: the webhook, signature checks, messaging services and media limits.
- Microsoft TeamsConnect a Teams bot through the Bot Framework: the bot registration, the messaging endpoint, single-tenant bots, and how files are sent.
- Google ChatConnect a Google Chat app with an HTTP endpoint: the Chat API configuration, the authentication audience, and the service account used for replies.
- iMessageReach Habakkuk over iMessage through a BlueBubbles server on a Mac: the webhook secret, the Private API for typing and replies, and group chats.
- Web chatThe chat page Habakkuk serves itself, and the same chat over a JSON API with Server-Sent Events, for your own clients.
- More platformsSet up LINE, Mattermost, IRC, ntfy, Messenger, Instagram, Feishu and Lark, DingTalk, WeCom, Zulip, Rocket.Chat, Nextcloud Talk and Twitch chat.