​

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

---

​

Connecting a channel

1. Open Settings → Headmaster’s Library → Channels.
2. Pick the channel and click Connect.
3. Follow the platform-specific flow (details for each platform below).
4. 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

1. Create a bot: message @BotFather on Telegram.
2. Send /newbot, follow the prompts to name it.
3. Copy the bot token BotFather gives you.
4. In Headmaster: Channels → Telegram → Connect.
5. Paste the bot token.
6. 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

1. Log in to the DingTalk developer console.
2. Create a custom robot:
   • Go to your group → Group Settings → Group Assistant → Add Robot → Custom.
   • Or create an enterprise application in the developer console.
3. Configure the robot:
   • Set the security settings (custom keyword, IP whitelist, or sign).
   • Note the Webhook URL and Secret (if using sign mode).
4. In Headmaster: Channels → DingTalk → Connect.
5. Enter the Webhook URL and Secret.
6. 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

1. Log in to the WeChat Work admin console.
2. Create a custom application:
   • Go to Application Management → Self-built → Create.
3. Note the Corp ID, Agent ID, and Secret.
4. Configure the receive message URL:
   • Set the callback URL to Headmaster’s webhook endpoint.
   • Set the callback token and encoding key.
5. In Headmaster: Channels → WeChat Work → Connect.
6. Enter the Corp ID, Agent ID, and Secret.
7. 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

1. Log in to the Lark developer console.
2. Create a custom bot application:
   • Create a new app.
   • Enable the Bot capability.
   • Set permissions (send messages, receive messages, upload files).
3. Note the App ID and App Secret.
4. Configure the event subscription:
   • Set the request URL to Headmaster’s webhook endpoint.
   • Subscribe to the im.message.receive_v1 event.
5. In Headmaster: Channels → Lark → Connect.
6. Enter the App ID and App Secret.
7. 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

1. Log in to the WeCom admin console.
2. Create a custom application:
   • Go to Application Management → Self-built → Create.
3. Note the Corp ID, Agent ID, and Secret.
4. In Headmaster: Channels → WeCom → Connect.
5. Enter the Corp ID, Agent ID, and Secret.
6. 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).

1. On your Mac, install the bridge software (follow the platform-specific guide for the latest compatible bridge).
2. Configure the bridge to forward messages to Headmaster’s webhook endpoint.
3. In Headmaster: Channels → iMessage → Connect.
4. Enter the bridge endpoint URL and authentication token.
5. 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

1. Sign up for the WhatsApp Business Cloud API at Meta for Developers.
2. 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.
3. In Headmaster: Channels → WhatsApp Business → Connect.
4. Enter the Phone Number ID and Access Token.
5. 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

---

​

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.