Skip to content
Ankole

Adapter configuration guide

For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/adapter-configuration/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.

This page lists the enterprise identity, chat, and Connector adapters included with Ankole. First, check whether your platform acts as an Identity Provider (IdP), a Channel Provider, a Connector Toolkit, or all of them, and then open the matching guide below.

During first-run setup, /setup displays the exact login callback URL and setup guide link for your chosen IdP. Pod administrators (pod_admin) manage tenant application connections in Pod → Connections (/connectors, /api/v2/pod/connectors) and enterprise identity providers in Pod Settings (/api/v2/pod/admin/identity-providers), while site administrators manage identity providers in Console → Identity Providers alongside site-level SMTP settings for passwordless Email OTP (authn.email.*). External chat applications connect to Agents under Console → Signal Routing.

Ankole.Connectors stores shared application roots (authConfigId) so identity providers, IM Signal routing rules, MCP Toolkits, and external event triggers can reference a single encrypted credential record instead of duplicating secrets. For example, one Feishu / Lark enterprise application connection in Pod → Connections (or imported during IdP / Signal Routing setup in the Console) can power SSO and directory sync, IM Signal routing, MCP Toolkits (lark-im, lark-approvals, lark-tasks, lark-calendar), and Connector event triggers together. Slack and Microsoft 365 (Entra ID and Teams) connections can likewise share one authConfigId root, or you can create separate connections whenever you want independent bot identities, release scopes, or credential rotation schedules.

Identity Providers

An IdP authenticates members of your organization and can synchronize employees, departments, and groups. Pod administrators (pod_admin) configure enterprise identity providers in Pod Settings, and site administrators can also manage them in Console → Identity Providers. Both forms share the Ankole.Connectors connection selector (authConfigId), letting you pick an existing connection from Pod → Connections or create one inline. When site SMTP delivery (authn.email.*) is configured in the Site Console, Ankole also offers passwordless Email OTP sign-in. Because Ankole never stores user passwords, you create the first administrator during setup either by verifying a live email code or by completing enterprise SSO.

In the table below, the credential names match the fields in the Ankole configuration form. Follow the linked guides for required provider permissions, callback URLs, and verification steps.

Platform External application Main configuration Detailed guide
Slack Slack app created from scratch Client ID and Client Secret; directory sync also needs a Bot Token and App Token Slack IdP guide
Microsoft Entra ID Single-tenant app registration Tenant ID, Client ID, Client Secret, and Microsoft Graph permissions Entra ID guide
Google Workspace OAuth web client and a service account with domain-wide delegation OAuth client, allowed domains, service-account JSON, and delegated administrator email Google Workspace guide
Feishu / Lark Enterprise self-built app or Custom App (reusable via authConfigId across SSO, IM, MCP Toolkits, and triggers) App ID, App Secret, service region, and application availability Feishu / Lark IdP guide
DingTalk Internal enterprise application Client ID, Client Secret, Corp ID, and directory permissions DingTalk IdP guide
WeCom Self-built app with optional contacts synchronization CorpID, AgentId, application Secret, contacts-sync Secret, and trusted IP addresses WeCom IdP guide

After you configure the provider, copy and register the callback URL exactly as shown on /setup—do not type it by hand or replace the browser-facing HTTPS origin with an internal container address. Once sign-in succeeds, run a full directory sync and verify the imported users, departments, and groups under Principals and permission groups.

Channel Providers

A chat adapter receives incoming messages and delivers Agent replies. On platforms supported by Ankole.Connectors—such as Feishu / Lark, Slack, and Microsoft Teams—a Signal Routing rule can either reuse an existing shared application connection (authConfigId) from Pod → Connections / Console or use a dedicated bot connection when different Agents need separate bot personas, release scopes, or rotation schedules. Reusing a Feishu / Lark connection lets one custom enterprise app serve SSO, IM messages, lark-im / lark-approvals / lark-tasks / lark-calendar MCP Toolkits, and Connector event subscriptions without re-entering App ID and App Secret.

Platform External application Connection and main configuration Detailed guide
Slack Slack app with a Bot User Socket Mode; shared connection (authConfigId) or Bot Token, App Token, events, and Bot scopes Slack channel guide
Microsoft Teams Azure Bot with its Entra application Bot Framework; shared connection (authConfigId) or App ID, Client Secret, tenant, and messaging endpoint Teams channel guide
Feishu / Lark Shared or dedicated enterprise self-built app / Custom App Long connection; shared connection (authConfigId) or App ID, App Secret, events, and bot permissions Feishu / Lark channel guide
DingTalk Internal enterprise application with a bot Stream mode; Client ID and Client Secret, with optional AI cards DingTalk channel guide
WeCom API-mode AI bot created by a super administrator Long connection; Bot ID and bot Secret WeCom channel guide
Telegram Bot created with @BotFather Long polling; Bot token, with group privacy mode off Telegram channel guide
Discord Application with a bot in the Developer Portal Gateway WebSocket; Bot token, message content intent, and bot permissions Discord channel guide
LINE Messaging API channel of an Official Account Webhook; Channel ID, Channel secret, channel access token, and webhook URL LINE channel guide
WhatsApp Meta App with the WhatsApp product and a Business phone number Cloud API webhook; App ID, App secret, verify token, Phone number ID, and System User token WhatsApp channel guide
Email A dedicated mailbox with IMAP and SMTP IMAP and SMTP hosts and ports, login, password, and sender authentication Email channel guide

Because Telegram, Discord, LINE, and WhatsApp are consumer messaging platforms without an employee directory, an administrator maps each new sender to an account under Identity → Pending mappings before the Agent serves them. On WhatsApp, however, Ankole resolves the sender automatically when an existing account already owns that phone number. Email senders are recognized only through an explicit email identity binding, which directory sync creates automatically for employees and an administrator creates for everyone else. See Signal routing rules.

Once the external application is ready, open Console → Signal Routing → New routing rule, select the target Agent and adapter, and either pick an existing connection (authConfigId) or enter new credentials. Use the Identity provider field to link the rule to an IdP on the same platform: if only one matching IdP exists, Ankole selects it by default; if multiple exist, choose the appropriate one; or choose the standalone option to keep sender identities in a dedicated namespace for this binding. Linking an IdP unifies chat senders and synced directory users under a single account, so only select an IdP that belongs to the same enterprise organization as the chat application.

Update a stored credential

Whether you edit a shared connection in Pod → Connections or open an Identity Provider or Signal Routing rule in the Console, Ankole displays only whether encrypted credentials are stored—never returning raw tokens or secrets to the browser. Leave a credential field blank to keep the stored value, or enter and save a new value when rotating it; updating a shared connection (authConfigId) increments its secret version and refreshes every Identity Provider, IM channel, and Connector Toolkit bound to it. Because stored secrets cannot be retrieved from Ankole, rotate or revoke old credentials directly in the external provider.

Verification order

  1. Verify sign-in via enterprise IdP SSO or passwordless Email OTP over SMTP, and confirm that the first administrator opens the Pod workspace with siteadmin and pod_admin access and can access the Site Admin Console at /site-admin-console.
  2. If you configured an enterprise IdP, run a full directory sync and inspect the resulting Principals and permission groups.
  3. Create the chat routing rule (reusing your shared connection authConfigId where applicable) and test it first with a direct message or an explicit mention.
  4. Once you confirm that the Agent receives the message and replies, enable optional features such as group observation, real-time directory sync, interactive cards, or Connector Toolkits and personal OAuth in Pod → Connections.

Whenever you change provider scopes, application permissions, or release scope, reinstall or republish the application if the platform requires it, and update Ankole with each rotated credential.