Channels

Channels bring Cairn's attention requests to the messaging apps where you already are. Cairn can deliver questions, permission requests, reviews, and followed-work updates through iMessage, Telegram, and Discord. A GitHub App mention can start work from a repository conversation. Channels extend work already organized in Cairn; they are not standalone chatbots.

How channel conversations work

Each destination has an inbound allowlist, independent inbound grants, and a choice of what Cairn may deliver. The allowlist is checked first. Traffic from outside it is ignored; admitted senders can use only the capabilities granted to that conversation:

• Permissions allows approving or denying permission requests.
• Answers allows answering questions and using follow, focus, subscription, and poll controls.
• Free text allows loose messages to reach the focused or bound Cairn target as instructions.

With none of these grants enabled, the conversation is notify-only. Grants are independent, so a conversation can answer questions without accepting loose instructions, or carry permission decisions without becoming a general command surface.

Replies to a delivered ask return to the waiting agent; replies to followed-work updates return to that thread or issue. A loose message goes to the currently focused follow only when Free text is enabled.

• /threads and /issues list active work. Choose an item to follow and focus it.
• /focus <name> focuses an existing follow.
• /unfollow <name> stops its updates. With no name, it unfollows the focus.
• /help shows the command summary.

Cairn uses polls when a provider supports them. Selecting an item follows and focuses it. iMessage can report a poll deselection and unfollow it; on tap-only providers such as Telegram, use /unfollow.

Questions and permission requests are posted to every eligible carrying surface, including the desktop and configured channel conversations. The first accepted answer wins, retires the controls on the other surfaces, and leaves a receipt such as Allowed via Discord · 17:56. The durable receipt retains the provider, canonical conversation address, authenticated actor when known, and absolute decision time. The surface says how the answer appeared; the actor says which principal answered. A surface name never grants or implies authority.

iMessage setup

Prerequisites

• A macOS fleet executor signed in to the intended Messages account.
• A working imsg bridge with the required macOS privacy permissions.
• The phone number or email that will receive messages.

Configure iMessage

1. Open Settings › Channels › iMessage and select the macOS Executor.
2. Enter the destination under Recipient.
3. Add every phone number or email allowed to answer under Allow replies from. For a personal setup, add the recipient itself.
4. Enable the inbound grants this conversation needs. Permissions and Answers make a focused operator conversation useful without allowing loose instructions; add Free text only when intended.
5. Choose what to send under Deliver, then enable iMessage.

Screenshot slot: iMessage executor, recipient, and allowlist settings.

The selected executor owns this connection. Cairn does not silently move it to another machine when that executor is offline.

Telegram setup

Allow about five minutes for a direct-message setup.

1. Message @BotFather, send /newbot, follow its prompts, and copy the token.
2. Message @userinfobot and copy your numeric user ID.
3. Find your new bot, tap Start, and send it a message. A bot cannot initiate a direct-message conversation.

Screenshot slot: BotFather's new-bot flow and returned token.

Screenshot slot: @userinfobot showing the operator's numeric user ID.

The number before the colon in the bot token is the bot's ID, not your user ID. Do not use it as the Chat ID.

4. Open Settings › Channels › Telegram and paste the Bot token.
5. For a direct message, enter your numeric user ID as the Chat ID and add it to Allow replies from. The allowlist is required.
6. Enable the inbound grants this conversation needs. Leave all three off for notify-only delivery.
7. Choose what to send under Deliver, then enable Telegram.

Screenshot slot: Telegram token, Chat ID, allowlist, and delivery settings.

For a group, the Chat ID is negative. Add the bot, send a fresh message, then read message.chat.id from Telegram's getUpdates response while Cairn's Telegram channel is disabled. The Bot API URL contains your token: do not put it in a shared request tool, and clear it from history. Keep your own positive user ID in the allowlist. If ordinary group messages must reach Cairn, use /setprivacy with @BotFather to disable bot privacy mode.

Discord setup

You need permission to create a Discord application and install it in the destination server.

1. Open the Discord Developer Portal, sign in, and choose New Application.

2. Name the application, accept Discord's terms, and create it.

3. Open Bot. Under Token, choose Reset Token, copy the new token, and keep it private. Discord only shows it once.

4. Scroll to Privileged Gateway Intents and enable only Message Content Intent. Presence Intent and Server Members Intent are not required.

5. Open Installation. Under Guild Install, include the bot scope and grant View Channels, Send Messages, Read Message History, Manage Channels, Manage Threads, and Send Messages in Threads.

6. Save, copy the installation link, open it, choose the server, and authorize it.

7. In Discord, open User Settings › Advanced and enable Developer Mode.

8. Right-click the server to copy its ID. Open your profile and copy your user ID; repeat for every person who may reply.

9. Open Settings › Channels › Discord. Paste the bot token and Server ID. Add permitted user IDs under Allow replies from, enable the required inbound grants, choose what to deliver, and enable Discord. Cairn creates and binds its project channels and issue threads inside that server as they are needed.

The allowlist also protects direct messages from people who share a server with the bot.

GitHub mentions

GitHub mentions use the GitHub App connection rather than a messaging-provider token. First connect and install your GitHub App for the repository. In a GitHub issue or pull-request comment, mention the installed Cairn App. Cairn receives the comment webhook and creates an issue in the Cairn project whose Git remote matches that repository. Bot comments and repositories without a matching project are ignored.

Screenshot slot: Mentioning the installed Cairn App in a GitHub issue comment.

For the relay and key-custody model, see GitHub.

Troubleshooting

Cairn surfaces the latest outbound send failure separately from connection status, so a healthy inbound feed cannot hide a broken delivery path.