Signal routing rules
For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/signal-bindings/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.
A signal routing rule (Signal Binding) determines how Ankole routes incoming chat messages or external events:
ai_colleaguemode connects a chat application or CloudEvents source to one chosen AI Colleague, and a single AI Colleague can have multiple rules across different platforms.sender_personal_assistantmode (supported on Lark/Feishu and Slack withagent_uidset tonull) exposes a single shared Personal Assistant Bot for your workspace: Ankole routes each direct message (im_dm) to that matched active member’s own Personal Assistant (provisioning it on first use) and holds unmapped senders under Manual review.
When a message arrives, the chat adapter records it in a Conversation and admits Signals for the resolved Agent. You can also expose CloudEvents webhook endpoints to ingest events from external systems and route them as Signals.
If you have not yet created an application in Slack, Microsoft Teams, Lark, Feishu, or DingTalk, complete the Channel Provider setup in Quick start first.
Create a routing rule
- Open Signal Routing in the Console and select New routing rule.
- Choose the Channel Provider adapter and routing mode: pick a target AI Colleague (
ai_colleaguemode), or select Sender’s Personal Assistant (sender_personal_assistantmode on Lark/Feishu or Slack). - Enter a descriptive rule name, such as
support-slackorworkspace-pa-lark. - For
ai_colleaguerules, choose how the Agent should handle group messages (sender_personal_assistantrules handle direct messages only and enforce Manual review for unmapped senders). - Select an existing application connection (
authConfigId) from Pod → Connections (Ankole.Connectors)—allowing chat routing and directory/SSO login to share one platform application credential—or enter credentials directly to save them intoAnkole.Connectors, then save the rule. - Send a test message to the bot in that chat platform and confirm that the Agent replies.
Give every distinct bot persona its own chat application and routing rule: use a dedicated application per AI Colleague so their identities and message streams stay independent, and use one dedicated application for a shared Personal Assistant Bot.
Select a group-message mode
The Console displays only the group-message modes supported by the selected Channel Provider:
| Mode | What happens to a group message that does not address the Agent |
|---|---|
| Addressed messages only | The Agent neither sees the message nor replies to it. |
| Observe unaddressed messages | Ankole records the message in the conversation context without waking the Agent, so the Agent can reference it once someone addresses it later. |
| May intervene | Ankole wakes the Agent to evaluate whether stepping in would be helpful, and the Agent replies only when it chooses to speak. |
Slack, Microsoft Teams, Lark, and Feishu support all three modes. Because DingTalk and WeCom deliver only group messages that explicitly @-mention the bot, the Console offers only Addressed messages only for those platforms. WeCom imposes several additional platform restrictions—no message recall, no group file attachments, and no bot-initiated conversations—so we do not recommend it as your first channel; see the WeCom tab in Quick start.
Selecting May intervene does not cause the Agent to reply to every message; instead, Ankole evaluates each batch of new chatter once so the Agent can decide whether to chime in. To set clear boundaries for a specific room, give the Agent a standing order for that channel directly in chat (for example, “only speak when CI turns red”). If the Agent still chimes in too often, tighten that standing order or refine its AGENTS.md instructions; see Ambient intervention for details.
Choose Addressed messages only whenever a group wants strictly on-demand question-and-answer behavior.
Choose what happens to unknown senders
Ankole first looks for an active Human Principal already linked to the sender’s stable platform user ID. Directory sync, SSO login, or an administrator can establish that link. Under the default Manual review policy, an email address or mobile number observed in a chat profile does not create a link to an existing account; an Email OTP (SiteCredential) login alone does not link that user’s chat account either.
Use When account auto-mapping fails to control how Ankole handles unmapped senders:
| Option | Behavior |
|---|---|
| Manual review (default) | Ankole queues the sender under Identity → Pending mappings in the Console. Until an administrator links the sender there, messages that address the Agent receive a single standard reply asking the sender to contact an administrator, and nothing enters conversation context or Brain learning. |
| Create a standalone account | Ankole resolves or creates an account and lets the sender talk to the Agent—useful for public or community channels. On the first binding to that provider, an attested email can link the sender to one active Human whose profile email, verified personal login email, or directory contact alias matches, provided that Human has no binding to the provider and has not completed offboarding. Otherwise, Ankole creates a standalone account from the platform identifier. Ambiguous email matches or an occupied account identifier prevent admission; an administrator must link the identity explicitly. |
Ankole ignores unaddressed group chatter from senders awaiting manual review.
On Telegram, Discord, LINE, and WhatsApp, a sender with no existing platform binding starts out unmapped. Keep Manual review enabled and bind each person’s account once when you want to admit known users only. A WhatsApp phone number does not by itself link the sender to an existing Human’s mobile number.
The Email channel uses the sender address in its own email namespace: it matches an explicit email identity binding or the active Human’s recorded contact email. Directory sync or upstream sign-in can establish email bindings for employees, and an administrator can add bindings for external contacts on this Console page. An Email OTP login address alone is not an Email channel binding. On Lark and Feishu, external cross-tenant group members have no internal employee ID, so use manual binding or the standalone-account policy. Administrators can pre-link accounts before a user sends their first message—for example, to bind an Email OTP (SiteCredential) user to their chat account ahead of time.
How chat conversations become Brain knowledge
A signal routing rule governs message delivery, whereas Brain derives knowledge visibility from the conversation type and verified participant identities:
- Group chat: Members and Agents belonging to the channel’s synchronized member group can recall knowledge learned from that room; Brain skips learning altogether for groups that have no member group.
- Direct message: Only the human participant and the executing Agent (the bound AI Colleague or the sender’s Personal Assistant) can recall knowledge from the conversation by default.
Broad company facts can still be promoted to tenant-wide knowledge, while explicitly confidential statements can be restricted to the speaker alone; everything else retains the group-chat or direct-message audience above. See Brain for retrieval and disclosure rules.
Edit, disable, or enable a rule
By default, the Signal Routing page lists only active rules; toggle Show disabled to inspect or re-enable a paused rule.
Select Edit to update non-secret fields—such as the target AI Colleague, group-message mode, selected Ankole.Connectors connection (authConfigId), or rotated credentials. Pointing an ai_colleague rule at a different Agent routes subsequent incoming messages to the newly selected Agent.
For security, the control plane never sends stored tokens or secrets back to the browser: leave secret fields blank when editing to preserve their existing encrypted values, and enter a value only when replacing a credential.
Select Disable to pause new message admission while preserving the rule configuration, external app binding, and conversation history. Later, toggle Show disabled and click Enable to resume delivery without recreating the rule.
If the Agent does not reply
- The Channel Provider does not appear: Control Plane Plugins are strictly site-scoped (
/api/v2/site/control-plane-plugins), so they appear only under Global defaults in the Site Admin Console rather than inside the Agent Library view for an individual tenant or Agent. Open the Site Admin Console (/site-admin-console), navigate to Agent Library with scope set to Global defaults, open the Control Plane Plugins tab, enable the channel plugin, and restart the control plane. - No group messages arrive: Verify the external app’s event subscriptions, scopes, and published release status, and remember that DingTalk and WeCom deliver group messages only when users @-mention the bot.
- WeCom behaves unexpectedly: Check the WeCom tab in Quick start—common pitfalls include bots not created by a super administrator, missing trusted-IP allowlist entries, or conversations that the user has not activated yet.
- The rule is saved, but the Agent stays silent: Confirm that the target Agent is enabled, its required model profiles resolve cleanly, and the routing rule itself is enabled.
- Direct messages work, but group messages do not: Check the rule’s group-message mode and confirm that the bot has been added to the group channel.
Refer to Quick start for each platform’s required scopes, webhook events, and credentials. If you use DingTalk with streaming card replies, follow the advanced section of the DingTalk tab in Quick start to create the required AI card template.