> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Feishu Bot

> Connect AIvis to Feishu groups or apps while controlling messages, permissions, and knowledge access.

The Feishu bot lets users call AIvis from Feishu one-on-one conversations, groups, or app entry points. Treat it as a governed entry point before launch: accept messages only from approved sources, use only the knowledge and tools available to the current user or group, and keep every response traceable.

## Use Cases

| Scenario                              | Recommendation                                                                                                              |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Team knowledge Q\&A                   | Add the bot only to approved groups and bind it to Agents or document sets the team can access.                             |
| Internal support or ticket assistance | Use a dedicated Feishu app and bot name so operations, logs, and permission reviews stay clear.                             |
| Project group assistant               | Limit the knowledge and tool scope to the project group, then remove group access or disable the bot when the project ends. |
| Sensitive knowledge Q\&A              | Verify user, group, and document-set permissions first; do not use the bot as a shared proxy that bypasses authorization.   |

## Management Boundary

| Area        | Guidance                                                                                                          |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| Entry       | Use an approved Feishu custom app, event subscription, and callback URL.                                          |
| Identity    | Bind the bot to a clear AIvis workspace and owner instead of treating it as an admin proxy.                       |
| Responses   | Return only knowledge and tool results available to the current user, group, or bound Agent.                      |
| Permissions | Enable only the message permissions the bot needs; add group-message permissions only when group use is required. |
| Operations  | Track App ID, callback URL, release time, secret rotation, and owner.                                             |

## Before Configuration

Before configuring the bot, confirm that:

1. You have an HTTPS callback URL that Feishu can reach from the public internet.
2. You can sign in to the [Feishu Open Platform](https://open.feishu.cn/app), and the current account can create or manage custom apps.
3. The Feishu client and Open Platform are using the same tenant or account type. If the Feishu client uses a personal account, switch the Open Platform to the matching account.
4. The AIvis bot configuration page is open so you can copy the callback URL and fill in the Feishu credentials.
5. The approved groups, departments, workspace, and default Agent or knowledge scope are clear.

`App Secret`, `Verification Token`, and `Encrypt Key` are sensitive. Store them only in protected configuration; do not place real values in public docs, Agent instructions, screenshots, tickets, or chat messages.

## Create the App in Feishu

After opening the Feishu Open Platform, confirm that the account in the upper-right corner belongs to the target company or personal tenant. If it is not the right account, switch accounts first, then open the **Developer Console** and **Custom Apps** page.

![Feishu Open Platform account switch and custom app entry page](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/74390154d42ccbb00126dda86e5eae00dfc8faad95517b43ac7b3d059cf3ef24/assets/aivis/feishu-bot/open-custom-apps.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=5208f7ba3884a4a17b504542c73da60da6086bef22fb7e2368b1ff5aa572c6d6&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

#### Open custom apps

Open the Feishu Open Platform, go to the **Developer Console**, and create a new app from **Custom Apps**. If you already have an AIvis-specific bot app, open that app and continue configuration there.

#### Fill in app details

Enter the app name, description, and icon. Keep the app name aligned with the AIvis bot display name, such as `AIvis Assistant` or `Product Knowledge Assistant`, so administrators and group members can identify it.

#### Confirm app status

After creation, verify that the app appears in the custom-app list. If its status is still **Pending launch**, continue with event, permission, and release configuration.

![Feishu Open Platform custom app creation dialog with app name, description, and icon fields](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2c56ebf6a86ebaecb1ec11f4613e27edc903ac072e78a9c5714e2f09c77cb23c/assets/aivis/feishu-bot/create-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=be57888f334ce8c2cf73350bd5c5d6f56bdd36de2053503adf8195986f214b16&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Configure App Credentials

In the Feishu app management page, open **Credentials & Basic Info** and copy the `App ID` and `App Secret` from **App Credentials**. Return to the AIvis bot configuration page and map them as follows:

![Feishu Open Platform Credentials and Basic Info page showing App ID and the hidden App Secret area](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/79e2a2be8cac98583946e2222ecac864cfa36d5ba86d2c19e37dd25a464964bd/assets/aivis/feishu-bot/app-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=7b31f34863081e406b94a887a1cd85a1ef240f158bb63f57939c626dac96f14f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![AIvis bot configuration page saving Feishu App ID and App Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/a1d8fbbcfc5565642bbb80d00d3d8e7c6f97a9347dccd7a75be44828ade45ebe/assets/aivis/feishu-bot/aivis-app-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=7950b9e39f43ad5911c697bce3a6fd952997e5042e883666ae3ab9c838b1dcfb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| Feishu Open Platform | AIvis field | Description                          |
| -------------------- | ----------- | ------------------------------------ |
| `App ID`             | App ID      | Identifies the Feishu custom app.    |
| `App Secret`         | App Secret  | Used to obtain Feishu access tokens. |

Keep these rules in mind:

* `App ID` and `App Secret` must come from the same Feishu app.
* Do not paste a personal user ID, tenant ID, bot name, or tenant token into **App ID**.
* If you regenerate the `App Secret`, update the AIvis configuration; otherwise the bot may fail to obtain access tokens.
* If the AIvis field says that the value is already saved and can be left blank, leave the secret field empty when you are not rotating it.

## Configure Verification Token and Encrypt Key

In the Feishu Open Platform sidebar, open **Events & Callbacks**, then open **Encryption Strategy**. Copy `Verification Token` and `Encrypt Key`, and fill them in on the AIvis bot configuration page:

![Feishu Open Platform encryption strategy page showing hidden Verification Token and Encrypt Key fields](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2c25ce2a22ac4caa8b4a6776523d90b8950f3cc3cc06cbb5bdc46322c42b8043/assets/aivis/feishu-bot/encryption-strategy.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=620a8e2f4a2b71e807f27fa6f2a962bffc13881c26f554cb2438e7630c40456b&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| Feishu Open Platform | AIvis field        | Description                                      |
| -------------------- | ------------------ | ------------------------------------------------ |
| `Verification Token` | Verification Token | Validates Feishu event and callback requests.    |
| `Encrypt Key`        | Encrypt Key        | Decrypts encrypted message payloads from Feishu. |

After saving, confirm that the bot is **Enabled** and that the display name is clear. Saved `Verification Token` and `Encrypt Key` values are usually not shown in plaintext; refill them only when you regenerate or change the values in Feishu.

![AIvis bot configuration page showing the bot enabled with saved verification token and encryption key fields](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/01e8b5eb1786b0620205992abb8c7fa6c6ea89a9660d509a44565b56180a2de1/assets/aivis/feishu-bot/aivis-bot-security-fields.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=63cc973290a30e42e5b3b9cc667a56948f4c4c66cb30260b49f3e1d6b1b47015&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Configure Events and Callback URL

Copy the **Callback URL** generated by AIvis. Then return to **Events & Callbacks** in the Feishu Open Platform and configure both places:

![AIvis bot configuration page showing the callback URL field with the concrete address hidden](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/cc022c74a4eb8e4a8ae9de0bb141780c2b333c17916597b7a54470edcace8868/assets/aivis/feishu-bot/aivis-callback-url.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=3dfb1c0ae9af33eae2129fd3512fb76fc0a03920d7b27a111faeb70b0c414991&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

1. In **Event Configuration**, set the subscription method to **Send events to developer server**, paste the callback URL, and save.
2. In **Callback Configuration**, set the subscription method to **Send callbacks to developer server**, paste the same callback URL, and save.

![Feishu Open Platform callback configuration page set to send callbacks to the developer server](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/5f0554136dfcbc94b938e36eab684f24e982da83b1b10bbfeff5eabc80fcac48/assets/aivis/feishu-bot/callback-configuration.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=b8621076c229e4ea28eff1915dbb865ffe83dbd09feedc0ed91c1dcf2e3bbe8c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Event Configuration** and **Callback Configuration** are separate tabs. Message events usually arrive through event configuration; some interaction or capability callbacks arrive through callback configuration. Configure the same AIvis callback URL in both places.

After saving, both tabs should show the configured request URL. If Feishu cannot save the URL, first confirm that it uses HTTPS, is reachable from the public internet, and that AIvis can respond to Feishu's URL verification request.

![Feishu Open Platform event configuration saved with the receive-message event added and the concrete request URL hidden](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/7f9b6626febc30c96b9ada97c51327ad52031357490258e69b05e1d9f1617933/assets/aivis/feishu-bot/event-configuration-saved.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=c8890970fcd3b0aa43cadb8e040528fa99c07bf58ac2f33a9e6f797ed0d9bec0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![Feishu Open Platform callback configuration saved with the concrete request URL hidden](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/112fe7f4d88037cf5ed199f1ea599b8c8fd18192c21478a2daf73777c21e5438/assets/aivis/feishu-bot/callback-configuration-saved.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=eb7e396212bba50aed581d90b814847ef26754982199d05840816bf5d874a793&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Add Message Event and Permissions

In **Event Configuration**, click **Add event** and add the receive-message event:

```text
im.message.receive_v1
```

In **Permission Management**, enable only the message permissions the bot actually needs. For one-on-one use, avoid group-message permissions. For group use, add the relevant group-message permissions, such as reading messages that mention the bot.

![Feishu Open Platform event configuration showing the receive-message event and required message permissions](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/fa690ed3039fe9f011ac47edca42e2be0b09d60e5a205c454ba673af71c8ca4d/assets/aivis/feishu-bot/message-event.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=076168705dc09e2df0bf75dfb6451b5881d05655c47912611b824cb942175ce6&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Permission approval and event subscription are separate checks. The bot may fail to receive messages when the event is added but permissions are not approved, or when permissions are approved but the app version has not been released.

## Create and Release a Version

Open **Version Management & Release**, click **Create version**, fill in the release information, and submit the release. After release, confirm that:

* The version status is **Released**.
* The page indicates that all current changes have been released.
* The version details include the **Bot** capability, and it is enabled.
* The availability scope is expected, such as selected members, departments, or the target company.

If the page says that current changes take effect only after version release, there are still unreleased changes. Even when the AIvis-side configuration is saved, Feishu may not deliver messages or callbacks until the app version is released.

![Feishu Open Platform version details showing the bot capability enabled and the version released](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/c6d85ef2602d13493bcdbc8c83d4c682fa4dc4311269ed19c03ff507289ca4db/assets/aivis/feishu-bot/release-details.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=47bfd2d6030c3bea0beb8edb5db2bd6e3ff9a1529be9cf2d75b7f61a96533efc&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Test the Bot

Before testing, confirm on the AIvis bot configuration page that:

1. The bot is **Enabled**.
2. The display name is correct.
3. App ID, App Secret, Verification Token, and Encrypt Key are saved.
4. The callback URL matches both Feishu event and callback settings.
5. The bound Agent, knowledge scope, and tool scope match the test scenario.

Open a Feishu one-on-one conversation or test group and send a normal question. When the configuration is correct, the bot should receive the message and return a response. Actual response time depends on networking, model calls, and backend processing.

For group testing, add the bot to the target group first and use the trigger method that matches the granted permissions. For example, if the bot can read only group messages that mention it, mention the bot in the group message.

![Feishu bot message test succeeds](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/a24c5652da370938a698cbddee79487b436d8980bf5433728416fc23764a5699/assets/aivis/feishu-bot/feishu-bot-test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T105542Z&X-Amz-Expires=604800&X-Amz-Signature=a03ecd85220822de314d976d8572e1c1d1ad3958cf71e88e0be6540738fea981&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Verify Access Boundaries

After the basic reply test passes, verify governance boundaries:

1. Ask an allowed question as an authorized member and confirm that the bot returns the expected answer.
2. Ask for unauthorized content as an unauthorized member, group, or document-set audience and confirm that sensitive data is not returned.
3. Confirm that tracing or request logs include the source platform, user context, bound Agent, response result, and errors.
4. After changing `App Secret`, `Verification Token`, `Encrypt Key`, event permissions, or availability scope, release the Feishu version again and repeat the tests.

## Troubleshooting

| Symptom                                             | First checks                                                                                                                                                             |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Feishu cannot save the callback URL                 | Confirm the callback URL uses HTTPS, is publicly reachable, and that AIvis responds to Feishu's URL verification request.                                                |
| Feishu sends messages, but AIvis shows no logs      | Check that **Event Configuration** has the correct URL, `im.message.receive_v1` is added, and the latest version is released.                                            |
| AIvis receives the callback, but verification fails | Confirm `Verification Token` or `Encrypt Key` matches the current Feishu app and does not include extra spaces.                                                          |
| The bot cannot obtain an access token               | Confirm `App ID` and `App Secret` belong to the same app and that regenerated secrets were updated in AIvis.                                                             |
| One-on-one chat works, but group chat does not      | Confirm the bot is in the group, group-message permissions are enabled, and group messages mention the bot when required.                                                |
| The app list still shows **Pending launch**         | Create and release an app version in **Version Management & Release**.                                                                                                   |
| `403`, `91403`, or an empty resource list appears   | Besides API permissions, confirm that the app version is released and that the target document, knowledge space, group, or other resource has granted access to the app. |

## Security and Maintenance

* Store real secrets only in the AIvis configuration page; do not place them in docs, screenshots, tickets, chat messages, or source control.
* If a secret may have leaked, regenerate it in Feishu and update AIvis immediately.
* Apply least-privilege permissions. If the bot only needs message auto-replies, do not add document, contact, or administrative permissions.
* When the bot is no longer needed, disable it in AIvis first, then remove unneeded permissions or release changes that take the app offline in Feishu.
* For production, record each Feishu app release time, publisher, change summary, and verification result.

## Related Pages

* [Agents](/aivis/agents/agents) explains how to configure Agents the bot can call.
* [Users, Groups & Roles](/aivis/governance/users-and-groups) explains how access boundaries apply to members and groups.
* [Tracing](/aivis/governance/tracing) explains how to audit bot requests.
* [Feishu Knowledge Connector](/aivis/knowledge/connectors/feishu) explains how to index Feishu knowledge spaces.