AgentVis IM Bot Configuration Guide

1. Guide Overview

AgentVis supports communicating with Agents through Feishu or Slack messages: users message a bot in IM, the AgentVis desktop app receives it, sends the task to the bound Agent, and shows progress, stop controls, completion results, and errors in message cards.

The most confusing parts for ordinary users are usually not in AgentVis settings, but in the Feishu Open Platform or Slack App backend:

• Where to create the bot app.
• Which permissions are required.
• Which events must be subscribed.
• Whether a public callback URL is needed.
• Which IDs, secrets, and tokens need to be copied back to AgentVis.
• Why the bot still does not receive messages after setup.

AgentVis IM channels currently use long-lived connections:

• Feishu: uses Feishu Open Platform WebSocket long connections to receive events, with no public Webhook server required.
• Slack: uses Slack Socket Mode to receive events and interactivity callbacks, with no public Request URL required.

In other words, create the app in the platform backend, enable bot capabilities, grant permissions, subscribe to events, and enter the credentials back into AgentVis.

2. AgentVis Settings Field Reference

Open AgentVis, go to Settings, click IM Channel on the left, then choose Add Feishu Bot or Add Slack Bot.

2.1 Feishu Fields

If you manually fill Default Outbound Target, group or one-to-one chats usually use chat_id, such as oc_xxx. Direct users can also use open_id, user_id, union_id, or email. If users only send tasks from Feishu, this field is not required at first.

2.2 Slack Fields

If you manually fill Default Outbound Channel, use the Slack Channel ID, not the channel name. Bot messages usually start with B, public channels with C, private channels or multi-person DMs with G, and one-to-one DMs with D.

3. Feishu Bot Configuration

3.1 Create a Custom Enterprise App

1. Open Feishu Open Platform App Management.
2. Sign in with your enterprise account.
3. Click Create App.
4. Choose Custom Enterprise App.
5. Enter an app name, such as AgentVis bot. Add an app description and icon as needed, then create it.
6. After creation, open the app details page.

3.2 Copy App ID and App Secret

1. In the app details page, open "Basic Information -> Credentials and Basic Information".
2. Find App ID and copy it into AgentVis App ID.
3. Find App Secret and copy it into AgentVis App Secret.

App Secret is sensitive. Store it only in AgentVis local credential storage. Do not screenshot it or paste it into chat groups.

3.3 Configure Permissions

Open "Development Configuration -> Permission Management -> Enable Permissions". You can copy the Scope values below. Different tenants may show localized names or scope names; if you cannot find one, search by scope.

3.4 Configure Events and Callbacks

1. Open "Development Configuration -> Events and Callbacks".
2. Under Event Configuration, find Subscription Method, choose Use Long Connection to Receive Events, and save.
3. Click Add Event and add im.message.receive_v1 and im.message.recalled_v1.
4. Under Callback Configuration, find Subscription Method, choose Use Long Connection to Receive Events, and save.
5. Click Add Callback and add card.action.trigger.

AgentVis receives events through long connections and does not need a public callback URL. As long as the AgentVis desktop app is online and connected to the bot, events arrive through WebSocket.

3.5 Publish an App Version

After changing permissions, event subscriptions, or bot capabilities, a Feishu app usually needs a new version published before changes take effect.

1. Open Version Management and Release.
2. Create a new version.
3. Fill in release notes.
4. Submit for release.
5. If your enterprise requires admin approval, wait for approval.

If the bot still does not respond after configuration, first check whether you forgot to publish a new version.

3.6 Connect the Feishu Bot in AgentVis

1. Open AgentVis "Settings -> IM Channel".
2. Click Add Feishu Bot.
3. Enter Display Name, App ID, and App Secret.
4. Select a Hub.
5. Select the Target Agent.
6. Leave Default Outbound Target empty at first.
7. Click Save Credentials.
8. Click Connect.

After connection succeeds, the status shows Online.

3.7 Test Feishu Messages

One-to-one test: in Feishu, for example on mobile, use the search button at the top to find the bot you created. Send it a text message such as "Please write a hello_world.md file and send it to me." AgentVis should receive the task and return a progress card in Feishu.

Group test: add the bot to a group chat and send @bot hello. AgentVis only handles group messages that @mention the bot; ordinary group messages without @mention are ignored.

File test: send the bot an image or file; it should inspect and reply. You can also send "Please find the XX file on my desktop and send it to me"; the Agent searches the computer and sends the file to Feishu.

4. Slack Bot Configuration

4.1 Create a Slack App

1. Open Slack Apps.
2. Click Create New App.
3. Choose From scratch.
4. Enter an app name, such as AgentVis bot.
5. Choose the Slack workspace to install into.
6. Click Create.

4.2 Configure Bot Token Scopes

In the Slack App backend, open OAuth & Permissions on the left, find "Scopes -> Bot Token Scopes", and add:

Optional permission: chat:write.public is only needed when the bot must proactively send messages to public channels it has not joined. Usually do not add it at first; invite the bot to the channel instead.

After adding or changing scopes, reinstall the app to the workspace; otherwise the new permissions will not be included in the xoxb- token.

4.3 Install the App and Copy Bot User OAuth Token

1. Still on OAuth & Permissions, click Install to Workspace or Reinstall to Workspace.
2. Authorize the app.
3. Return to OAuth & Permissions.
4. Copy Bot User OAuth Token.
5. Paste it into AgentVis Bot User OAuth Token.

This token usually starts with xoxb-.

4.4 Enable Socket Mode and Copy App-Level Token

AgentVis uses Slack Socket Mode, so no public Request URL is needed.

1. Open "Settings -> Socket Mode" on the left and enable Socket Mode.
2. Open "Settings -> Basic Information" on the left and follow the prompts to create an App-Level Token.
3. Use any Token Name, choose connections:write as the scope, then copy the generated token. This token usually starts with xapp-.
4. Paste it into AgentVis App-Level Token.

4.5 Configure Event Subscriptions

1. Open Event Subscriptions on the left.
2. Turn on Enable Events.
3. Request URL is not needed when using Socket Mode.
4. Open Subscribe to bot events and add the required events.

If users only need to use the bot through DMs, subscribe only to message.im. If users need to @mention the bot in channels, app_mention is required at minimum.

4.6 Enable Interactivity

1. Open Interactivity & Shortcuts on the left.
2. Turn on Interactivity.
3. After Socket Mode is enabled, interactive components are sent to AgentVis through WebSocket, so no Request URL is needed.
4. Save.

This lets AgentVis receive button clicks on cards, such as Stop Task or Delete Message. If it is disabled, users can see cards but button clicks will not trigger AgentVis.

4.7 Allow Users to DM the App

If users see a message such as "Sending messages to this app has been turned off" when opening the Slack App Messages tab, the message entry is usually disabled in App Home.

1. Open App Home on the left.
2. Find Messages Tab or Show Tabs.
3. Enable the option that allows users to send messages from the Messages tab.
4. Save.

4.8 Connect the Slack Bot in AgentVis

1. Open AgentVis "Settings -> IM Channel".
2. Click Add Slack Bot.
3. Enter a display name.
4. Enter Bot User OAuth Token, which is xoxb-....
5. Enter App-Level Token, which is xapp-....
6. Select a Hub.
7. Select the Target Agent.
8. Leave Default Outbound Channel empty at first.
9. Click Save Credentials.
10. Click Connect.

After connection succeeds, the status shows Online.

4.9 Test Slack Messages

DM test: find your app under Apps in Slack, open the Messages tab, and send a message such as "Please write a helloworld text and send it to me." AgentVis should receive the task and return a progress card.

Channel test: open the target channel, type /invite @your-bot-name to invite the bot, then send @your-bot-name hello. AgentVis should receive the message and reply.

File test: send a file to the bot; it should inspect and reply. With files:read, AgentVis can download Slack files sent by users. With files:write, Agents can proactively send files through im_send.

5. Troubleshooting

5.1 AgentVis Shows Offline

• Feishu: check whether App ID and App Secret are swapped or incomplete.
• Slack: check whether Bot User OAuth Token starts with xoxb-... and App-Level Token starts with xapp-....
• Check that the Slack App-Level Token includes connections:write.
• Check whether the current network can reach open.feishu.cn or the Slack API.
• After permission changes, confirm that the Feishu app was republished or the Slack App was reinstalled.

5.2 Feishu Bot Does Not Receive Messages

1. Confirm the bot is online in AgentVis.
2. Confirm the Feishu app has the bot capability enabled.
3. Confirm im.message.receive_v1 is subscribed.
4. Confirm the event subscription method is Use Long Connection to Receive Events.
5. Confirm app permissions include one-to-one chat, group @mention, message sending, and resource permissions.
6. Confirm a new version was published and approved by the enterprise if required.
7. Check whether the bot was @mentioned in the group. AgentVis ignores group messages that do not @mention the bot by default.
8. Old messages sent before successful connection may be ignored. Send a new message after the bot is online.

5.3 Feishu Card Buttons Do Not Respond

• Check whether card.action.trigger is subscribed.
• Check whether a new version containing that event was published.
• Check whether AgentVis is online.
• If the Feishu client shows a callback timeout toast but the card state updates correctly, you can usually ignore it. If buttons do nothing, check event subscriptions.

5.4 Feishu Image or File Sending Fails

• Check whether bot capability is enabled.
• Check whether im:resource is granted.
• Check file size limits: AgentVis currently limits Feishu images to 10 MB and regular files to 30 MB.
• Check whether the app was republished after permission changes.

5.5 Slack Bot Does Not Receive Channel Messages

1. Check whether the app is installed to the workspace.
2. Check whether the bot has been invited to the target channel.
3. Check whether the channel message @mentions the bot.
4. Check whether app_mention is subscribed.
5. If relying on normal message events, check the related subscriptions: public channels message.channels, private channels message.groups, DMs message.im, and multi-person DMs message.mpim.
6. Check whether scopes include the corresponding history scope.
7. After changing scopes or events, check whether you clicked Reinstall to Workspace.

5.6 Slack DM Says Users Cannot Message the App

Open App Home and enable the option to send messages from the Messages tab. After enabling it, you may need to reinstall the app or ask users to reopen Slack.

5.7 Slack Card Buttons Do Not Respond

• Check whether Interactivity & Shortcuts is enabled.
• Check whether Socket Mode is enabled.
• Check whether the App-Level Token includes connections:write.
• Check whether AgentVis is online.

5.8 Slack Message Sending or Deletion Fails

• Check whether chat:write exists.
• Check whether the bot is in the target channel.
• Check whether Default Outbound Channel uses the channel ID, not the channel name.
• To send messages to public channels the bot has not joined, add chat:write.public; however, inviting the bot into the channel is recommended first.

5.9 Slack File Download or Upload Fails

• Downloading files sent by users requires files:read.
• Agent-initiated file upload requires files:write.
• Check whether the app was reinstalled after changing scopes.
• Check whether the bot can access that channel or DM.

6. Recommended Checklist

6.1 Feishu

• Custom enterprise app is created.
• Bot capability is enabled.
• App ID and App Secret have been copied to AgentVis.
• Permissions include at least im:message.p2p_msg:readonly, im:message.group_at_msg:readonly, im:message:send_as_bot, im:message:update, im:message:recall, and im:resource.
• Event subscription uses long connection.
• Events im.message.receive_v1 and im.message.recalled_v1 are added.
• Callback card.action.trigger is added.
• A new app version has been published.
• Hub and Target Agent are selected in AgentVis.
• Bot status is Online in AgentVis.

6.2 Slack

• Slack App is created.
• Bot Token Scopes include at least app_mentions:read, channels:history, groups:history, im:history, mpim:history, chat:write, files:write, and files:read.
• The app is installed or reinstalled to the workspace.
• xoxb-... has been copied to AgentVis Bot User OAuth Token.
• Socket Mode is enabled.
• App-Level Token is created with the connections:write scope.
• xapp-... has been copied to AgentVis App-Level Token.
• Required bot events are added in Event Subscriptions.
• Interactivity is enabled.
• If DM is needed, the App Home Messages tab allows users to send messages.
• Hub and Target Agent are selected in AgentVis.
• Bot status is Online in AgentVis.

7. Security Recommendations

• App Secret, xoxb-..., and xapp-... are sensitive credentials. Do not commit them to Git or send them to others.
• If credentials may have leaked: reset App Secret in Feishu Open Platform and update AgentVis; for Slack, regenerate the relevant token in OAuth & Permissions or Basic Information, then update AgentVis.
• Grant bots the minimum necessary permissions. Add resource or file permissions only when file capabilities are needed.
• In Slack, invite the bot into channels first instead of granting chat:write.public at the beginning.
• Bind each AgentVis bot to one clear Target Agent so users know who will execute IM tasks.

8. Reference Links

Feishu

• Feishu Open Platform App Management
• Receive Events with Long Connections
• Receive Message Event im.message.receive_v1
• Send Message API
• Card Interaction Callback
• Update Sent Message Cards
• Upload Images
• Upload Files
• Get Resource Files from Messages

Slack

• Slack Apps Management
• Using Socket Mode
• app_mention event
• message event
• chat.postMessage
• files:write scope
• files:read scope
• Working with files