Administration & GovernanceIntegrations

Feishu Bot

View as Markdown

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

ScenarioRecommendation
Team knowledge Q&AAdd the bot only to approved groups and bind it to Agents or document sets the team can access.
Internal support or ticket assistanceUse a dedicated Feishu app and bot name so operations, logs, and permission reviews stay clear.
Project group assistantLimit the knowledge and tool scope to the project group, then remove group access or disable the bot when the project ends.
Sensitive knowledge Q&AVerify user, group, and document-set permissions first; do not use the bot as a shared proxy that bypasses authorization.

Management Boundary

AreaGuidance
EntryUse an approved Feishu custom app, event subscription, and callback URL.
IdentityBind the bot to a clear AIvis workspace and owner instead of treating it as an admin proxy.
ResponsesReturn only knowledge and tool results available to the current user, group, or bound Agent.
PermissionsEnable only the message permissions the bot needs; add group-message permissions only when group use is required.
OperationsTrack 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, 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

1

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.

2

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.

3

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

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

AIvis bot configuration page saving Feishu App ID and App Secret

Feishu Open PlatformAIvis fieldDescription
App IDApp IDIdentifies the Feishu custom app.
App SecretApp SecretUsed 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

Feishu Open PlatformAIvis fieldDescription
Verification TokenVerification TokenValidates Feishu event and callback requests.
Encrypt KeyEncrypt KeyDecrypts 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

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

  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

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

Feishu Open Platform callback configuration saved with the concrete request URL hidden

Add Message Event and Permissions

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

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

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

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

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

SymptomFirst checks
Feishu cannot save the callback URLConfirm 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 logsCheck 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 failsConfirm Verification Token or Encrypt Key matches the current Feishu app and does not include extra spaces.
The bot cannot obtain an access tokenConfirm 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 notConfirm 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 launchCreate and release an app version in Version Management & Release.
403, 91403, or an empty resource list appearsBesides 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.