WeCom

Last updated 10/07/2026

1. Prerequisites

• You have permissions for the WeCom Admin Console and can create intelligent bots. If you need OAuth, you also need to create a self-built enterprise app.
• You have permission to access System Admin > Channels in Agentic Engine.
• The Agentic Engine channel management feature is enabled.
• The deployment server can access the official WeCom persistent connection address wss://openws.work.weixin.qq.com.
• For member OAuth binding, the platform must be open to users over HTTPS, and an available public domain must be ready.

2. Create a WeCom intelligent bot and get credentials

Log in to the WeCom Admin Console and configure it as follows:

1. Go to Security and Management > Management Tools, find Intelligent Bot, and click Create Bot > Create manually.
2. Scroll to the bottom and select Create in API mode, and select Use persistent connection as the connection method.
3. Enter the bot name, description, and visibility scope, and save the configuration.
4. In the API configuration area, copy the following credentials and store them securely:

WeCom field	Platform field	Description
Bot ID	Bot ID	Unique identifier of the intelligent bot, used for persistent connection authentication.
Secret	Bot Secret	Intelligent bot secret. Store it only in a secure location, and don't put it in code, tickets, or chat records.

tip

No public callback URL is needed for the bot: Agentic Engine actively establishes a persistent WebSocket connection and authenticates with the Bot ID and Bot Secret.

Optional: Create a self-built app for member OAuth

OAuth isn't required for the bot to send and receive messages. You only need to create a self-built app in the same company if users need to bind their WeCom member identity with one click in the browser.

1. In the WeCom Admin Console, create a self-built enterprise app, and add the members who need to use it to the app's visibility scope.
2. Record the company and app credentials:

WeCom field	Platform field	Description
Company ID	Corp ID	Usually starts with ww. You can find it in the company information.
AgentId	Agent ID	App ID of the self-built app.
Secret	Corp Secret	Secret of the self-built app, used by the server to get member identities.

Required: Complete trusted domain and URL (domain) entity verification

The callback domain used by WeCom OAuth must first be configured as a trusted domain of the self-built app. Before the trusted domain is saved, WeCom may check both domain ownership and the domain ICP filing entity, and both checks must pass.

1. Go to WeCom Admin Console > App Management > Self-built > Target app > Web Authorization and JS-SDK, and click Set Trusted Domain.
2. Enter the domain actually used to access the platform, such as agent.example.com. Enter only the domain, without https://, the port, or the path. If you use a subdomain, configure the actual subdomain separately.
3. Click Apply for Domain Verification, or follow the on-page prompt to download the WW_verify_*.txt verification file generated by WeCom.
4. Keep the file name and content unchanged, and deploy the file to the website root directory of the domain. Make sure the browser can access it directly:

域名所有权校验文件

https://agent.example.com/WW_verify_xxxxxxxxxxxx.txt

1. The request must directly return the content of the verification file. It can't redirect to a login page, be blocked by authentication, or return a frontend SPA page.
2. Return to the WeCom Admin Console, select Domain ownership verification file uploaded, and save. If the file is accessible but verification still fails, check the DNS/CDN cache and try again later.

warning

URL entity verification: The ICP filing entity of the trusted domain must match the certified/verified entity of the current WeCom organization, or have an affiliation recognized by WeCom. If you see "URL entity verification failed" or "Domain entity mismatch", application code can't work around it. Use a filed domain with a matching entity instead, or complete the filing and entity affiliation first and then configure it.

Config items	Example	Requirement
Trusted domain	agent.example.com	Enter only the host name in the WeCom Admin Console
Verification file URL	https://agent.example.com/WW_verify_xxxxxxxxxxxx.txt	Deployed in the domain root directory and returns the file content directly
OAuth callback URL	https://agent.example.com/agent/api/wecom-oauth/callback	The example is a deployment that uses the /agent subpath
Origin whitelist	ALLOWED_ORIGINS=https://agent.example.com	Include the protocol and host name, without the path

tip

Don't confuse the two URLs: The verification file must be in the domain root directory, while the OAuth callback still uses /agent/api/wecom-oauth/callback. The two paths are different, but the host name must match the trusted domain.

1. After you complete trusted domain, ownership, and entity verification, make sure the following OAuth callback URL can be accessed normally from a browser:

未配置子路径时

https://<your-domain>/agent/api/wecom-oauth/callback

In production environments, we recommend configuring an authorization origin whitelist. Separate multiple origins with commas:

ALLOWED_ORIGINS=https://<your-domain>

3. Add a WeCom channel in the platform

As an admin, log in to Agentic Engine and go to System Admin > Channels:

1. Click New Channel and select WeCom as the channel type.
2. Fill in the following configuration items:

Config items	Required	Description
Channel Name	Required	Display name, such as "WeCom Robot".
Bot ID	Required	Bot ID of the WeCom intelligent bot.
Bot Secret	Required	Secret of the WeCom intelligent bot.
Enable member OAuth binding	Optional	When turned on, browser authorization binding is used first. When turned off, binding codes can still be used.
Corp ID	Conditionally required	Required when OAuth is enabled.
Agent ID	Conditionally required	Required when OAuth is enabled.
Corp Secret	Conditionally required	Required when OAuth is enabled.
Default Model	Optional	If not selected, the system-wide default model is used.
System Prompt	Optional	Applies only to Agent sessions in this channel.

1. Click Save, and then turn on the channel's Enable switch.
2. Make sure the channel status changes to Online. If it's still Offline or Error, check it by following the troubleshooting section of this document.

tip

Only one instance can be created for each channel type. The Secret is stored encrypted and isn't displayed again. When you edit a channel, leaving the Secret empty keeps the original value. Turning off OAuth deletes the entire set of OAuth credentials.

4. Bind a WeCom account

Method 1: OAuth authorization binding

1. Log in to Agentic Engine and click your avatar in the lower-left corner.
2. In the account menu, find WeCom and click Bind.
3. The system opens the WeCom member authorization page. Complete authorization with an internal member account of the same company.
4. After authorization succeeds, the window closes automatically, and the WeCom status in the menu changes to Bound.

Method 2: One-time binding code

If OAuth isn't enabled, or if the platform is accessed over HTTP, the system automatically uses a binding code:

1. Click your avatar in the lower-left corner, and click Bind in the WeCom row.
2. Copy the 6-character binding code generated by the system. The binding code is valid for 10 minutes and can be used only once.
3. In WeCom, send either of the following commands to the intelligent bot:

绑定 ABC234
+bind ABC234

After the bot replies "WeCom account bound successfully", the platform menu automatically updates to Bound. The same WeCom member can't override another Agentic Engine user's active binding.

Unbind

1. Click your avatar in the lower-left corner, and click Unbind in the WeCom row.
2. After you confirm the unbinding, the status changes to Unbound. To switch to a different Agentic Engine account, unbind the original account first.

5. FAQ

Channel status is Offline or Error

• Make sure the Bot ID and Bot Secret come from the same intelligent bot, and that no extra spaces were copied.
• Make sure the bot isn't disabled in the WeCom Admin Console, and that API mode and persistent connection are selected.
• Make sure the server can access wss://openws.work.weixin.qq.com.
• After the Secret is regenerated, the old value becomes invalid. Edit the channel, enter the new Secret, and enable the channel again.

OAuth reports that it isn't enabled or is incompletely configured

• Make sure the WeCom channel is enabled and the Enable member OAuth binding switch is turned on.
• Make sure Corp ID, Agent ID, and Corp Secret are all filled in and come from a self-built app in the same company.
• Make sure the visibility scope of the self-built app includes the current member.

OAuth callback failure

• Make sure the callback domain, protocol, port, and path exactly match the address actually used to access the platform.
• When you use NEXT_PUBLIC_BASE_PATH, the callback URL must include that subpath.
• After you configure ALLOWED_ORIGINS, make sure the current access origin is in the whitelist.
• OAuth binding requires an internal company member. External contacts can't be bound.

Binding code is invalid or expired

• Generate a new binding code and use it within 10 minutes.
• Make sure the command format is 绑定 ABC234 or +bind ABC234.
• A binding code can be consumed only once. A used binding code can't be submitted again.

The bot can reply with text but can't read attachments

• Make sure channel.wecom.fileUploads.enabled isn't turned off.
• Make sure the file type is supported, and that the single-file size and the number of attachments per message don't exceed the configured limits.
• Make sure sandbox attachment storage and the file API work properly.

No response after clicking a template card

• Make sure the channel's persistent connection is online.
• Make sure the interaction for the card hasn't expired or been answered, and that the user clicking it is the bound user.
• Check whether the server can process and update the card within the time WeCom requires.

---

Related pages and next steps

• See the setup instructions for other platforms: Channel management.
• Learn about the overall flow of channel connection and binding: Channel overview and binding.
• Configure the Agent to use: Agent.
• See how to use conversations in the platform: Conversations.