Gateway WeCom Integration Setup Guide ​

This document describes how to integrate CodeBuddy Agent into the WeCom (WeChat Work) ecosystem using the /gateway feature of CodeBuddy CLI. Two integration methods are supported:

  • Method A: Tencent Customer Service (WeChat Customer Service) — Provide AI services externally through a WeChat Customer Service account
  • Method B: WeCom Custom App — Provide AI services internally through a custom-built app within WeCom

Method A: Tencent Customer Service (WeChat Customer Service) ​

1. Prerequisites ​

1.1 Register a WeCom Organization ​

  1. Visit the WeCom official website and register an organization (you can use personal information to create one)
  2. Complete organization verification (basic features do not require verification, but unverified organizations can only serve up to 100 customers cumulatively)
  3. Log in to the WeCom Admin Console, go to the "My Organization" page, and find and record the Corp ID at the bottom of the page

Get Corp ID

1.2 Enable Tencent Customer Service and Configure Callback ​

  1. Visit the WeChat Customer Service Admin Console and log in by scanning the QR code with a WeCom admin account
  2. Go to the "Developer Configuration" page in the left menu, and set the following parameters in the "Callback Configuration" section (these will be configured as environment variables later):
    • Token: A token for callback signature verification (custom string)
    • EncodingAESKey: Message encryption key (43 characters, click "Generate Random" to create one)

WeChat Customer Service Developer Configuration

Note: The callback URL needs to be obtained and configured in Steps 2 and 3. The Secret can only be retrieved after the callback URL verification passes, so record the Token and EncodingAESKey first, then continue with the following steps.

2. Start Gateway to Obtain the Webhook URL ​

2.1 Configure Environment Variables (First Launch) ​

For the first launch, since the Secret has not been obtained yet, configure only the 3 available environment variables:

bash
export CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN="<your Token>"
export CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY="<your EncodingAESKey, 43 characters>"
export CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID="<Corp ID>"

2.2 Launch CLI and Execute /gateway ​

bash
codebuddy

After entering interactive mode, execute:

/gateway

Once started successfully, the terminal will output information similar to:

Gateway started

  ├─ Status    connected
  ├─ Mode      tunnel
  ├─ Local     http://127.0.0.1:8321
  ├─ Tunnel    https://xxx-yyy.trycloudflare.com
  └─ Webhook   https://xxx-yyy.trycloudflare.com/gateway/webhook/:platform

Record the Webhook URL.

3. Configure Callback URL and Obtain the Secret ​

Replace :platform in the Webhook URL with wechat-kf to get the full callback URL:

https://xxx-yyy.trycloudflare.com/gateway/webhook/wechat-kf

Go back to the "Developer Configuration" page in the WeChat Customer Service Admin Console:

  1. In the "Callback Configuration" section, enter the URL above into the "Callback URL" field
  2. Confirm that the Token and EncodingAESKey match those configured in your environment variables
  3. Click "Save". The system will send a GET verification request, and Gateway will automatically respond to the verification

After verification passes, user messages from WeChat Customer Service will be pushed to Gateway through this callback.

3.1 Obtain the Secret ​

After callback verification passes, you can obtain the Secret in the "Developer Information" section of the "Developer Configuration" page. Add the environment variable:

bash
export CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET="<WeChat Customer Service app Secret>"

After adding this, restart Gateway for the Secret to take effect (for subsequent normal launches, configure all 4 environment variables).

4. Environment Variables Overview ​

Environment VariableRequiredDescription
CODEBUDDY_GATEWAY_WECHAT_KF_TOKENYesCallback signature verification Token
CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEYYesMessage encryption key (43 characters)
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_IDYesWeCom Corp ID
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRETYesWeChat Customer Service app Secret

5. Verify the Integration ​

After configuration is complete, Gateway will automatically create a customer service account named CodebuddyCode. You can:

  1. View the newly created customer service account in the WeChat Customer Service management page
  2. Obtain the QR code or link associated with the customer service account
  3. Scan the QR code with WeChat or open the link to start a customer service conversation, and send a message to test whether the Agent responds correctly

Method B: WeCom Custom App ​

1. Prerequisites ​

1.1 Register a WeCom Organization ​

  1. Visit the WeCom official website and register an organization (you can use personal information to create one)
  2. Log in to the WeCom Admin Console, go to the "My Organization" page, and find and record the Corp ID at the bottom of the page

Get Corp ID

1.2 Create a Custom App ​

  1. In the Admin Console, go to "App Management" -> scroll to the "Custom" section at the bottom -> click "Create App"

Create Custom App

  1. Fill in the app name, logo, visibility scope, and other information to complete the creation
  2. Go to the app details page and record the following information:
    • AgentId: The app ID
    • Secret: Click "View" to obtain the app secret (used to get the access_token)

App AgentId and Secret

1.3 Configure IP Allowlist ​

When a WeCom custom app calls APIs (such as sending messages), the request source IP must be on the allowlist. You need to add your local public static IP to the app's "Trusted Enterprise IPs" list:

  1. On the app details page, find "Trusted Enterprise IPs" in the "Developer Interface" section
  2. Click configure and add your public IP to the allowlist

Configure IP Allowlist

Note: The custom app method requires a public static IP. If you do not have a static public IP, consider using Method A (Tencent Customer Service).

1.4 Configure Message Receiving ​

  1. On the app details page, find the "Receive Messages" card in the "Features" section, and click "API Receiving Enabled" to enter the configuration page

Enable API Message Receiving

  1. In the "Receive Message Server Configuration", set the following parameters (these will be configured as environment variables later):
    • Token: A token for callback signature verification (custom string)
    • EncodingAESKey: Message encryption key (43 characters, click "Generate Random" to create one)

Note: Do not fill in the URL yet. Complete Step 2 first to obtain the Webhook URL, then come back to configure it.

2. Start Gateway to Obtain the Webhook URL ​

2.1 Configure Environment Variables ​

Before launching the CLI, set the following environment variables:

bash
export CODEBUDDY_GATEWAY_WECOM_TOKEN="<your Token>"
export CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY="<your EncodingAESKey, 43 characters>"
export CODEBUDDY_GATEWAY_WECOM_CORP_ID="<Corp ID>"
export CODEBUDDY_GATEWAY_WECOM_CORP_SECRET="<Custom app Secret>"
export CODEBUDDY_GATEWAY_WECOM_AGENT_ID="<Custom app AgentId>"

2.2 Launch CLI and Execute /gateway ​

bash
codebuddy

After entering interactive mode, execute:

/gateway

Once started successfully, the terminal will output information similar to:

Gateway started

  ├─ Status    connected
  ├─ Mode      tunnel
  ├─ Local     http://127.0.0.1:8321
  ├─ Tunnel    https://xxx-yyy.trycloudflare.com
  └─ Webhook   https://xxx-yyy.trycloudflare.com/gateway/webhook/:platform

Record the Webhook URL.

3. Configure Callback URL ​

Replace :platform in the Webhook URL with wecom to get the full callback URL:

https://xxx-yyy.trycloudflare.com/gateway/webhook/wecom

Go back to the "Receive Message Server Configuration" page of the custom app in the WeCom Admin Console:

  1. Enter the URL above into the "URL" field
  2. Enter the Token and EncodingAESKey you set earlier
  3. Click "Save". The system will send a GET verification request, and Gateway will automatically respond to the verification

Callback URL Configuration Complete

After verification passes, messages sent by WeCom users to this app will be pushed to Gateway through this callback.

4. Environment Variables Overview ​

Environment VariableRequiredDescription
CODEBUDDY_GATEWAY_WECOM_TOKENYesCallback signature verification Token
CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEYYesMessage encryption key (43 characters)
CODEBUDDY_GATEWAY_WECOM_CORP_IDYesWeCom Corp ID
CODEBUDDY_GATEWAY_WECOM_CORP_SECRETYesCustom app Secret
CODEBUDDY_GATEWAY_WECOM_AGENT_IDYesCustom app AgentId

5. Verify the Integration ​

After configuration is complete:

  1. Open the WeCom client (desktop or mobile)
  2. Find your custom app in the Workbench
  3. Send a message to the app to test whether the Agent responds correctly

6. (Optional) Enable WeChat Plugin ​

After enabling the "WeChat Plugin" in WeCom, you can chat with the custom app directly in WeChat without opening the WeCom client:

  1. In the WeCom Admin Console, go to "My Organization" -> "WeChat Plugin"
  2. Follow the instructions to enable the WeChat Plugin feature

Enable WeChat Plugin

Once enabled, organization members can receive message notifications from the custom app in WeChat and reply directly to interact with CodeBuddy Code.

Comparison of the Two Methods ​

ComparisonTencent Customer Service (WeChat CS)WeCom Custom App
Use CaseRemotely control CodeBuddy Code via WeChat Customer Service entryRemotely control CodeBuddy Code via WeCom app
User EntryWeChat QR code / Customer Service linkWeCom Workbench (also available in WeChat after enabling the WeChat Plugin)
User ScopeWeChat users (external customers)WeCom members (internal employees)
Environment Variables Required45 (additionally requires AGENT_ID)
Message MechanismCallback notification + active pull (sync_msg)Callback directly pushes complete messages
Network RequirementsNo static public IP requiredRequires a static public IP with allowlist configuration
Platform Identifierwechat-kfwecom

FAQ ​

Callback Verification Fails ​

  • Verify that environment variables are set correctly and Gateway is running
  • Confirm that Token and EncodingAESKey match those entered in the admin console
  • Confirm that the Tunnel URL is accessible from the public internet (local mode is only suitable for intranet environments)

No Response After Sending Messages ​

  • Check the CLI terminal for error log output
  • Verify that CORP_SECRET is correct (used to obtain access_token for API calls)
  • For WeCom custom apps, verify that AGENT_ID is correct

Tunnel URL Changes ​

Each time /gateway is executed, a new Tunnel URL is generated (using Cloudflare Quick Tunnel), and the callback URL needs to be updated accordingly. For a fixed domain, consider using Cloudflare Named Tunnel or configuring a reverse proxy yourself.

Gateway Default Port ​

Gateway listens on port 8321 by default. To change it, specify a different port via parameters at startup.