# 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_TOKEN
```

> [!TIP]
> **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](https://www.habakkuk.ai/docs/channels/settings.md#webhook-channels)).

| Channel | `type` | Connects by | Public URL | Setup |
|---|---|---|---|---|
| [WhatsApp agent](https://www.habakkuk.ai/docs/channels/whatsapp.md#whatsapp-agents) | `whatsappagent` | long polling | no | easy, in `habakkuk setup` |
| [WhatsApp linked device](https://www.habakkuk.ai/docs/channels/whatsapp.md#linked-device) | `whatsapp` | a linked device, like WhatsApp Web | no | easy, in `habakkuk setup` |
| [WhatsApp Business Cloud API](https://www.habakkuk.ai/docs/channels/whatsapp.md#business-cloud-api) | `whatsappcloud` | webhook + Graph API | yes | involved: a Meta app and business account |
| [Telegram](https://www.habakkuk.ai/docs/channels/telegram.md) | `telegram` | long polling | no | easy, in `habakkuk setup` |
| [Slack](https://www.habakkuk.ai/docs/channels/slack.md) | `slack` | Socket Mode | no | moderate: a Slack app, in `habakkuk setup` |
| [Discord](https://www.habakkuk.ai/docs/channels/discord.md) | `discord` | Gateway websocket | no | moderate: a bot application, in `habakkuk setup` |
| [Signal](https://www.habakkuk.ai/docs/channels/signal.md) | `signal` | a signal-cli daemon | no | moderate: run signal-cli |
| [Matrix](https://www.habakkuk.ai/docs/channels/matrix.md) | `matrix` | `/sync` long polling | no | moderate: a bot account and token |
| [Email](https://www.habakkuk.ai/docs/channels/email.md) | `email` | IMAP (IDLE or polling) + SMTP | no | easy: a mailbox and an app password |
| [SMS](https://www.habakkuk.ai/docs/channels/sms.md) | `sms` | Twilio webhook + REST | yes | moderate: a Twilio number |
| [Microsoft Teams](https://www.habakkuk.ai/docs/channels/microsoft-teams.md) | `msteams` | Bot Framework webhook | yes | involved: an Azure bot registration |
| [Google Chat](https://www.habakkuk.ai/docs/channels/google-chat.md) | `googlechat` | Chat app HTTP endpoint | yes | involved: a Google Cloud project |
| [iMessage](https://www.habakkuk.ai/docs/channels/imessage.md) | `bluebubbles` | a BlueBubbles server on a Mac | yes | moderate: a Mac that stays on |
| [Web chat](https://www.habakkuk.ai/docs/channels/web-chat.md) | `web` | Habakkuk's own HTTP server | no | easy, in `habakkuk setup` |
| [LINE](https://www.habakkuk.ai/docs/channels/more-platforms.md#line) | `line` | webhook | yes | moderate |
| [Mattermost](https://www.habakkuk.ai/docs/channels/more-platforms.md#mattermost) | `mattermost` | WebSocket + REST | no | easy |
| [IRC](https://www.habakkuk.ai/docs/channels/more-platforms.md#irc) | `irc` | TLS, SASL PLAIN | no | easy |
| [ntfy](https://www.habakkuk.ai/docs/channels/more-platforms.md#ntfy) | `ntfy` | JSON stream + publish | no | easy |
| [Messenger](https://www.habakkuk.ai/docs/channels/more-platforms.md#messenger-and-instagram) | `messenger` | webhook + Graph API | yes | involved: a Meta app |
| [Instagram](https://www.habakkuk.ai/docs/channels/more-platforms.md#messenger-and-instagram) | `instagram` | webhook + Graph API | yes | involved: a Meta app |
| [Feishu / Lark](https://www.habakkuk.ai/docs/channels/more-platforms.md#feishu-and-lark) | `feishu` | event subscription + IM API | yes | moderate |
| [DingTalk](https://www.habakkuk.ai/docs/channels/more-platforms.md#dingtalk) | `dingtalk` | robot HTTP callback | yes | moderate |
| [WeCom](https://www.habakkuk.ai/docs/channels/more-platforms.md#wecom) | `wecom` | app callback + message API | yes | moderate |
| [Zulip](https://www.habakkuk.ai/docs/channels/more-platforms.md#zulip) | `zulip` | event queue long-poll + REST | no | easy |
| [Rocket.Chat](https://www.habakkuk.ai/docs/channels/more-platforms.md#rocketchat) | `rocketchat` | realtime API + REST | no | easy |
| [Nextcloud Talk](https://www.habakkuk.ai/docs/channels/more-platforms.md#nextcloud-talk) | `nextcloudtalk` | Talk bot webhook | yes | moderate |
| [Twitch chat](https://www.habakkuk.ai/docs/channels/more-platforms.md#twitch) | `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](https://github.com/habakkuk-ai/habakkuk/issues/new/choose) with the output of `habakkuk logs -level warn -since 1h`.

## How channels work

- **Who may talk.** Direct messages from someone not in `allow_from` get a pairing code that you approve with `habakkuk pair CODE`. See [Access, groups and delivery](https://www.habakkuk.ai/docs/channels/settings.md#who-may-talk-to-the-bot).
- **Groups.** In groups the bot answers only when addressed (a mention, a reply, or the platform's equivalent). `groups: all` answers everything; `off` ignores 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](https://www.habakkuk.ai/docs/channels/settings.md#replies-and-quotes) and [Sessions](https://www.habakkuk.ai/docs/agents/sessions.md#messages-from-elsewhere-in-the-same-chat).
- **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](https://www.habakkuk.ai/docs/agents/multi-agent.md#who-answers-a-conversation).

## Next steps

<!-- cards -->
- [Access, groups and delivery](https://www.habakkuk.ai/docs/channels/settings.md): pairing, group rules, webhooks, the settings every channel takes, and what each platform supports.
- [WhatsApp](https://www.habakkuk.ai/docs/channels/whatsapp.md): the three ways to be on WhatsApp, compared.
- [Telegram](https://www.habakkuk.ai/docs/channels/telegram.md): a bot in two minutes, with buttons, reactions and voice notes.

---

Source: https://www.habakkuk.ai/docs/channels