Channels

Channels are the messaging platforms the agent can be reached on. With a channel connected, you can send Headmaster a message from your phone, and the agent's reply lands in the same conversation history.

Platforms you can connect

| Channel | Type | Setup difficulty | | ---------------- | --------------------- | ---------------- | | Telegram | Bot API | Easy | | WeChat Work | Enterprise API | Intermediate | | DingTalk | Bot Webhook | Intermediate | | Lark | Bot API | Intermediate | | WeCom | Enterprise API | Intermediate | | iMessage | Apple Messages bridge | Advanced | | WhatsApp Business| Cloud API | Intermediate |

Channels settings — connect a platform

Screenshot placeholder: The Channels settings tab showing available platforms to connect.

Connecting a channel

Open Settings → Headmaster's Library → Channels.
Pick the channel and click Connect.
Follow the platform-specific flow (details for each platform below).
Test the connection by sending a message from your phone to the channel.

The detailed configuration form for each channel lives in the same area. Each form walks you through the steps for that specific platform.

Telegram setup

Create a bot: message @BotFather on Telegram.
Send /newbot, follow the prompts to name it.
Copy the bot token BotFather gives you.
In Headmaster: Channels → Telegram → Connect.
Paste the bot token.
Save. Send a message to your bot on Telegram to test.

What works:

Text messages (send and receive).
File attachments (send and receive).
Inline buttons for approvals and clarifications.
Proactive notifications from scheduled tasks.
Group chats (the bot responds to mentions).

DingTalk setup

Log in to the DingTalk developer console.
Create a custom robot:
- Go to your group → Group Settings → Group Assistant → Add Robot → Custom.
- Or create an enterprise application in the developer console.
Configure the robot:
- Set the security settings (custom keyword, IP whitelist, or sign).
- Note the Webhook URL and Secret (if using sign mode).
In Headmaster: Channels → DingTalk → Connect.
Enter the Webhook URL and Secret.
Save. Send a message from DingTalk to test.

What works:

Text messages (send and receive).
File attachments (limited — depends on DingTalk's API).
Text-based approvals (DingTalk doesn't support inline buttons).
Proactive notifications from scheduled tasks.

WeChat Work setup

Log in to the WeChat Work admin console.
Create a custom application:
- Go to Application Management → Self-built → Create.
Note the Corp ID, Agent ID, and Secret.
Configure the receive message URL:
- Set the callback URL to Headmaster's webhook endpoint.
- Set the callback token and encoding key.
In Headmaster: Channels → WeChat Work → Connect.
Enter the Corp ID, Agent ID, and Secret.
Save. Send a message from WeChat Work to test.

What works:

Text messages (send and receive).
File attachments (send and receive).
Text-based approvals (no inline buttons).
Proactive notifications from scheduled tasks.

Lark setup

Log in to the Lark developer console.
Create a custom bot application:
- Create a new app.
- Enable the Bot capability.
- Set permissions (send messages, receive messages, upload files).
Note the App ID and App Secret.
Configure the event subscription:
- Set the request URL to Headmaster's webhook endpoint.
- Subscribe to the im.message.receive_v1 event.
In Headmaster: Channels → Lark → Connect.
Enter the App ID and App Secret.
Save. Send a message from Lark to test.

What works:

Text messages (send and receive).
File attachments (send and receive).
Inline buttons for approvals and clarifications (Lark supports interactive cards).
Proactive notifications from scheduled tasks.

WeCom setup

Log in to the WeCom admin console.
Create a custom application:
- Go to Application Management → Self-built → Create.
Note the Corp ID, Agent ID, and Secret.
In Headmaster: Channels → WeCom → Connect.
Enter the Corp ID, Agent ID, and Secret.
Save. Send a message from WeCom to test.

What works:

Text messages (send and receive).
File attachments (limited).
Text-based approvals (no inline buttons).
Proactive notifications from scheduled tasks.

iMessage setup

iMessage requires a Mac running as a bridge (Apple Messages doesn't have a public API).

On your Mac, install the bridge software (follow the platform-specific guide for the latest compatible bridge).
Configure the bridge to forward messages to Headmaster's webhook endpoint.
In Headmaster: Channels → iMessage → Connect.
Enter the bridge endpoint URL and authentication token.
Save. Send an iMessage to the bridge's phone number to test.

What works:

Text messages only (send and receive).
No file transfer via iMessage.
Text-based approvals.
Proactive notifications.

iMessage is an advanced setup. The bridge runs on your Mac and must stay online for the channel to work.

WhatsApp Business setup

Sign up for the WhatsApp Business Cloud API at Meta for Developers.
Create a business account:
- Add the WhatsApp product to your Meta app.
- Get the Phone Number ID and Access Token.
- Configure the webhook: set the callback URL to Headmaster's webhook endpoint, and subscribe to message events.
In Headmaster: Channels → WhatsApp Business → Connect.
Enter the Phone Number ID and Access Token.
Save. Send a WhatsApp message to the business number to test.

What works:

Text messages (send and receive).
Media messages (images, documents — limited by WhatsApp's API).
Inline buttons for approvals (WhatsApp supports interactive message buttons).
Proactive notifications from scheduled tasks.

Disconnecting

Click Disconnect on a channel card. The agent stops reading from and replying to that platform immediately. Past conversation transcripts are kept.

What flows over channels

Inbound — messages from the platform become new turns in your active conversation. The agent reads them and responds.
Outbound — the agent's responses are sent back to the platform as messages.
File attachments — supported on channels that allow them. The agent can send and receive files.
Approvals and clarifications — work the same as in the desktop chat window. The agent sends an approval request as a message with buttons (on platforms that support them) or as a text prompt.
Notifications — the agent can proactively send you a message on a channel when a background task finishes or a scheduled task triggers.

Channel-specific limitations

| Channel | File send | File receive | Inline buttons | Notes | | ---------------- | --------- | ------------ | -------------- | ---------------------------------- | | Telegram | Yes | Yes | Yes | Full support. | | WeChat Work | Yes | Yes | No | Text-based approvals only. | | DingTalk | Yes | Limited | No | Text-based approvals only. | | Lark | Yes | Yes | Yes | Full support. Interactive cards. | | WeCom | Yes | Limited | No | Text-based approvals only. | | iMessage | No | No | No | Text only. No file transfer. | | WhatsApp Business| Yes | Limited | Yes | Media messages supported. |

Proactive behaviors

The agent can proactively send messages on channels:

Scheduled task results — when a cron job fires, the result is delivered to the channel you configured.
Background task completion — when a long-running task finishes, the agent notifies you on your preferred channel.
Approval requests — if the agent needs approval and you're not at the desktop, it sends the request to your channel.
Reminders — the agent can send scheduled reminders ("your meeting starts in 10 minutes").

This is what makes Headmaster feel like a 24/7 assistant — it reaches out to you on the platform you're already on, instead of waiting for you to check the desktop app.