> 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.

# WeCom Bot

> Connect AIvis with a WeCom Smart Bot in API mode and long-connection mode while controlling Bot ID, Secret, message permissions, and testing boundaries.

The WeCom bot connects AIvis to WeCom conversations. The recommended path is to create a Smart Bot in the WeCom client or admin console, choose API mode, and use long-connection mode.

Use it for internal Q\&A, ticket assistance, and notifications. Do not treat it as unrestricted history export. Before rollout, confirm message permissions, availability scope, default knowledge access policy, and audit paths.

## Use Cases

| Scenario                              | Guidance                                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Team knowledge Q\&A                   | Make the bot available only to approved members or groups, and bind it to the Agent or document set that team can access. |
| Internal support or ticket assistance | Use a dedicated bot name and owner so operations, log filtering, and permission reviews are clear.                        |
| Project-group assistant               | Limit knowledge and tool scope to the project group, then disable the bot or remove access after the project ends.        |
| Sensitive knowledge Q\&A              | Validate member, group, and document-set permissions first. Do not use the bot as a shared permission bypass.             |

## Management Boundary

| Area        | Guidance                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------- |
| Entry       | Use an approved WeCom Smart Bot, API mode, and long-connection channel.                      |
| Identity    | Bind the bot to a clear AIvis workspace and owner. Do not treat 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 types and scopes the bot actually needs.                             |
| Operations  | Track Bot ID, secret rotation, message permissions, owner, and shutdown process.             |

## Before Configuration

Before configuration, confirm:

1. You have WeCom administrator permissions.
2. You can access the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/index), or you have switched to an administrator account in the WeCom client.
3. The AIvis WeCom bot configuration page is open and ready for `Bot ID` and `Secret`.
4. The groups, departments, members, workspace, default Agent, and knowledge scope the bot may serve are defined.
5. You plan to use long-connection mode. Long-connection mode does not require a public callback URL, but Bot ID, Secret, and message permissions must still be configured correctly.

> `Secret` is sensitive. Store it only in protected configuration. Do not put real secrets in public docs, Agent instructions, screenshots, tickets, or chat messages.

## Open the Smart Bot Entry

In the WeCom client or admin console, open Workbench and then Smart Bot.

![WeCom Workbench showing the Smart Bot entry](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/b8849dff59b03723f84081b9992c64feaf4df32c2fb1caaac208a36b2d0b8031/assets/aivis/wecom-bot/wecom-smart-bot-entry.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=2fbb9787bdeba65cfd383d3ef673dcb53acdee6edaac989b2467864bc802d320&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Create the Bot

Click create bot to start the bot creation flow.

![WeCom Smart Bot creation entry](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/62e8ff3a8c74d785ed44388e69d96b3a0cb659aa7c4ca19b1889d609af2ad65a/assets/aivis/wecom-bot/wecom-create-bot.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=cd8f1045b0a6fb2286fecdb395efb239af53969569f1b289348d4534b563e619&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Choose manual creation.

![WeCom Smart Bot manual creation option](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/01a42b956b4c19fc0dba34cd19eafc91b2deeeba21a280427984b7392803f293/assets/aivis/wecom-bot/wecom-manual-create.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=2c141be8710a8cbe513845ef65e5ff1398fa42e980e174cee6d010857999b56e&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

For creation mode, choose API mode. API mode generates the `Bot ID` and `Secret` required by AIvis.

![WeCom Smart Bot API mode creation option](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/297573934ca20626e6e786a5e3a15e244d0d4aee2d554a41cfbba9b9136dd0cc/assets/aivis/wecom-bot/wecom-api-mode-create.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=467158f9c3826face2c61dbf35b4e77932b06c17ed1d32366d2a5863a5b40e5a&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Configure Connection and Message Permissions

Use long-connection mode. After the required base configuration, continue to configure the message scope and message permissions the bot can receive.

![WeCom Smart Bot long-connection setup](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/094566589c675d9bf1d6612e927b51292fcc3963ee99a8bfc717133605a235ac/assets/aivis/wecom-bot/wecom-stream-connection.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=9a3fef51ad2b455cd40a21cf1140d4bd91a6985f9eb423ac7254a07929379ba5&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![WeCom Smart Bot message permission configuration](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/d7b2f72ea9eca15185ce6dfedb9e3a963c1a20c7baa454d5d1ffdcc385610852/assets/aivis/wecom-bot/wecom-message-permissions.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=9888b7fdc1cc5fc10d91c7b38cf43a57aab07b5d8c3c0fc09eeceac952a96a36&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![WeCom Smart Bot message permission confirmation](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/a530317da5e8c9a9ddedff4af21c90e4f112f1802e1caaecea95b4137ec1bf58/assets/aivis/wecom-bot/wecom-message-permission-confirm.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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=7164e03eded95955dc6190bbd871770c0fede97c834c9f194e235717de5f5a26&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

When configuring message permissions:

* Select only the message types the bot actually needs.
* If the bot is only for a limited set of members or groups, do not expand availability to the whole company.
* After changing permissions, save the WeCom configuration and test again from AIvis.

## Fill Bot ID and Secret

Copy the `Bot ID` and `Secret` generated by WeCom. Return to the AIvis bot configuration page, fill the corresponding fields, and save.

![AIvis bot configuration page saving WeCom Bot ID and Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2fe8b7ea9a9a85975a3d34a2b163c6cf66b4074318d2eab8a91f8ccb72a1f5d4/assets/aivis/wecom-bot/aivis-wecom-bot-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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=b9549d0c46e95ff2c58eb6f2ab1b9be15797c0aed0ec2f94748148b201518ea5&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| WeCom           | AIvis configuration field | Notes                                                |
| --------------- | ------------------------- | ---------------------------------------------------- |
| `Bot ID`        | Bot ID                    | Identifies the WeCom Smart Bot.                      |
| `Secret`        | Secret                    | Used for bot authentication and the long connection. |
| Long connection | Connection mode           | Recommended default for WeCom bots.                  |

Configuration notes:

* `Bot ID` and `Secret` must come from the same WeCom Smart Bot.
* Do not put an enterprise ID, group ID, member ID, bot name, or admin account into the Bot ID field.
* If `Secret` is regenerated, update the AIvis configuration as well.
* If the AIvis page says the value is already saved and you are not changing the secret, the secret field can remain empty.

## Test the WeCom Bot

Before testing, confirm in AIvis:

1. The bot is enabled.
2. `Bot ID` and `Secret` are saved.
3. WeCom uses API mode and long-connection mode.
4. Message permissions and availability scope match the test scenario.
5. The bound Agent, knowledge scope, and tool scope match the test scenario.

Then open the bot conversation in WeCom and send a test message. When configuration is correct, the bot should receive the message and reply.

![WeCom bot message test succeeds](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/b4297f36090e7ca65d673024140296cba9ebd8ffd59df85e5cbfd837ed10d617/assets/aivis/wecom-bot/wecom-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=20260805T130119Z&X-Amz-Expires=604800&X-Amz-Signature=5f580f4bc85af648ef8acf4523e4b9ee2735fe71cddde2d8cff9d1b2b323d21c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Validate Access Boundaries

After the basic reply test, validate governance boundaries:

1. Send an allowed question as an authorized member and confirm the bot returns the expected answer.
2. Test an unauthorized member, unauthorized group, or a question requiring an inaccessible document set, and confirm sensitive data is not returned.
3. Confirm tracing or request logs include source platform, user context, bound Agent, response result, and errors.
4. After changing `Secret`, message permissions, availability scope, or default Agent, save configuration again and test again.

## Troubleshooting

| Symptom                                          | Priority checks                                                                                                        |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| WeCom bot cannot connect                         | Confirm `Bot ID` and `Secret` come from the same bot, and the secret has not been regenerated without updating AIvis.  |
| WeCom can send messages but AIvis has no logs    | Confirm API mode, long-connection mode, saved message permissions, and target availability scope.                      |
| No reply in direct or group chats                | Confirm the bot is added or available to the target conversation and the message type is allowed by WeCom permissions. |
| AIvis receives the request but returns no result | Check the bound Agent, knowledge scope, tool scope, and member permissions.                                            |
| Authorization errors or empty resources          | Confirm the target knowledge base, document set, group, or resource is granted to the bot and current user.            |
| Secret changes still fail                        | Confirm the AIvis configuration was saved again, then restart or wait for the long connection to re-establish.         |

## Security and Maintenance

* Store real secrets only in the AIvis configuration page. Do not write them into docs, screenshots, tickets, chat records, or repositories.
* If a secret may have leaked, regenerate it in WeCom and update AIvis immediately.
* Request permissions with the smallest usable scope. Do not enable contacts, message archive, or management permissions for a message-only bot.
* When the bot is no longer needed, disable it in AIvis first, then remove permissions or take the WeCom bot offline.
* In production, record each permission change, secret rotation, connection-mode change, and validation 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.