WeCom Customer Service

By binding a WeCom custom enterprise app to a WeCom Customer Service (微信客服) account, CowAgent can take over inbound inquiries from external WeChat users and serve them through links or QR codes embedded in WeChat Mini Programs, Official Accounts, Video Channels, and Video Channel stores.

WeCom Customer Service only supports Docker deployment or server Python deployment. A publicly reachable callback URL is required; local run mode is not supported.

1. Prerequisites

Required resources:

A server with a public IP
A registered and verified WeCom account
WeCom Customer Service capability enabled

It is recommended to create a dedicated WeCom custom app for Customer Service rather than reusing the existing wechatcom_app one — otherwise the two channels will compete for the same callback URL.

2. Create a WeCom Custom App

In the WeCom Admin Console, go to Application Management → Create Application:

Click My Enterprise and find the Corp ID at the bottom of the page (it goes into wechat_kf_corp_id):

Open the app you just created and click “View” next to Secret. The Secret will be pushed to the admin’s phone via the WeCom app, where it can be viewed:

Open the app’s Receive Messages → Set API Reception page, click “Random Generate” to generate the Token and EncodingAESKey, and save them:

Saving the API reception configuration will fail at this point because the program has not started yet. Come back to save it after the project is running.

3. Configuration and Run

Fill in the 4 fields collected from the previous step (Corp ID / Secret / Token / EncodingAESKey):

Web Console
Config File

Start the Cow project and open the Web Console. Go to the Channels menu, click Connect, choose WeCom Customer Service, fill in Corp ID / Secret / Token / AES Key (port defaults to 9888, configurable), and click Connect.

Add the following configuration to config.json (each parameter maps to a field shown in the screenshots above):

{
  "channel_type": "wechat_kf",
  "wechat_kf_corp_id": "YOUR_CORP_ID",
  "wechat_kf_secret": "YOUR_SECRET",
  "wechat_kf_token": "YOUR_TOKEN",
  "wechat_kf_aes_key": "YOUR_AES_KEY",
  "wechat_kf_port": 9888
}

Parameter	Description
`wechat_kf_corp_id`	Corp ID
`wechat_kf_secret`	Secret of the WeCom custom app bound to Customer Service
`wechat_kf_token`	Token from the API reception config
`wechat_kf_aes_key`	EncodingAESKey from the API reception config
`wechat_kf_port`	Listening port, default 9888

After connecting, start the program (the Web Console method restarts the channel automatically). When the log shows Listening on http://0.0.0.0:9888/wxkf/, the program is running successfully. You need to open this port externally (e.g., allow it in the cloud server security group). Then go back to Receive Messages → Set API Reception in the WeCom console and set the callback URL to http://<your-host>:9888/wxkf/, then click Save. After saving successfully, you also need to add the server IP to Enterprise Trusted IPs, otherwise messages cannot be sent or received:

If URL verification fails or the configuration is unsuccessful:

Ensure the server firewall is disabled and the security group allows the listening port (default 9888)
Carefully check that Token, Secret, EncodingAESKey and other parameters are consistent, and the URL format is correct
Verified WeCom accounts must use a filed domain matching the entity

4. Bind a WeCom Customer Service Account

In the WeCom Admin Console, go to WeCom Customer Service, create a customer service account, and bind it to the custom app you created above:

After binding, go to WeCom Customer Service → Account Details, and under “Access Link”:

Click “Copy Link” to get an access link like https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be
Click “Generate QR Code” to get the corresponding QR code

Distribute the link or QR code to your WeChat customers:

5. Usage

After WeChat users enter the customer service conversation via the link or QR code, they can chat with the AI across multiple turns, with support for text, image, and voice messages:

Beyond that, leveraging the official WeChat ecosystem, WeCom Customer Service can also be embedded into Official Accounts, Mini Programs, Video Channels and more. See the WeCom Customer Service → Access Scenarios section in the WeCom Admin Console for details:

FAQ

Make sure the following dependencies are installed:

pip install websocket-client pycryptodome

Documentation Index

​1. Prerequisites

​2. Create a WeCom Custom App

​3. Configuration and Run

​4. Bind a WeCom Customer Service Account

​5. Usage

​FAQ

1. Prerequisites

2. Create a WeCom Custom App

3. Configuration and Run

4. Bind a WeCom Customer Service Account

5. Usage

FAQ