WeCom Application Integration (On-premises Deployment)

1. Overview

QuickAudience (QA) upgraded its WeCom integration from the service provider model to a self-built application model. With your own application, you can access more WeCom data without API call limits, reducing data acquisition costs.

2. Prerequisites

2.1 Resource checklist

No.	Resource Name	Specification	Resource requirements	Notes
1	Second-level domain	qawecom.xxx.com	The ICP filing entity for the domain must match the company registered with WeCom.	You can reuse an existing public domain. Forward requests from the specified path.
2	Elastic IP Address (EIP)	5 Mbps bandwidth	Point the second-level domain to this public IP address.	Recommended bandwidth by WeCom user count: <= 1 million: 5 Mbps > 1 million and <= 5 million: 10 Mbps > 5 million: 15 Mbps
3	SSL Certificate		An SSL certificate that matches the second-level domain.	Required. Without it, communication falls back to HTTP (security risk). Also required for WeCom session archiving.

2.2 Information checklist

No.	Purpose	Information	How to Obtain (WeCom Link)
1	WeCom account association	corpid, secret	https://developer.work.weixin.qq.com/document/path/90665#secret
2	WeCom API callback	corpid	https://developer.work.weixin.qq.com/document/path/90930

3. Network deployment instructions

3.1 Forward WeCom callback requests

Forward requests from the `/restapi/thirdservice/we/com` path of your public domain to the QA service IP or SLB address.

3.2 Add WAF access whitelist

To keep QA accessible only from the internal network, add a WAF whitelist rule to allow WeCom callbacks.

Add the `/restapi/thirdservice/we/com` path of your public domain to the whitelist. Only this path is publicly accessible.

4. WeCom backend configuration instructions

Complete WeCom authorization per the WeCom Authorization Configuration Guide before proceeding. The following example uses an application named "Test Space".

As an example

4.1 Configure application visibility

4.2 Configure permissions

Grant the application permission to access customer information before calling the API. Without this, requests fail.

1. Go to Customers and Upstream/Downstream.

   Go to Customers and Upstream/Downstream > Customer Contacts > Customers and bind your WeChat Developer ID.

   Note

   Without this binding, customer data retrieval fails.

   

2. Add applications that can call the API.

   Select the "Lingyang QA WeCom Application".

   Overview - Document - WeCom Developer Center.

   

4.3 Configure callback API information

1. Go to your self-built WeCom application and click Set API Reception.

   

2. Set API reception.

   

Configuration details

Configuration Item	Value	Description
URL	https://{domain}.com/restapi/thirdservice/we/com/inner/event/oneparty/callback/{corpid}	Replace {domain} with your actual domain name. Replace {corpid} with your corporate corpid. Example: https://test.lydaas.com/restapi/thirdservice/we/com/inner/event/oneparty/callback/wwb697d33134e48cfc
Token	Generate randomly	Record this value for WeCom account association in QA.
EncodingAESKey	Generate randomly	Record this value for WeCom account association in QA.

5. Other notes

5.1 Character encoding for Huawei Cloud GaussDB analysis sources [Important]

When creating a Huawei Cloud GaussDB database as a QA analysis source, set the character encoding to UTF-8. The default SQL_ASCII encoding causes parsing errors with WeCom Unicode data, leading to failed scheduling tasks.

5.2 Historical data compatibility and migration (Optional)

If you previously used the service provider model, historical WeCom data remains in QA. Contact QuickAudience technical support for migration options.

5.3 Network diagram for on-premises deployment

In on-premises deployments, QA runs in your cloud environment and pulls WeCom data directly per WeCom security standards. Event callbacks require a public domain. The domain's registered entity must match the WeCom-registered company. This routes WeCom callbacks to QA.

6. FAQ

6.1 WeCom API calls return error 48002

Symptom

WeCom error description

Solution

Configure permissions in the WeCom backend (see Section 4.2).

6.2 Manually trigger a scheduling task

Go to the core container and manually run the command

curl --location 'http://127.0.0.1:9001/swagger/test/invoke/day/dataimport/{organizationid}/{workspaceid}/WECHAT_WECOM'

Replace {organizationid} and {workspaceid} with your organization ID and workspace ID.

Example

Organization Name: Test Organization

Organization ID: 0a27b751-db52-4ec2-b2bc-e7b747c0bfb6

Workspace Name: Default Workspace

Workspace ID: 5a3e3999-fccb-43ef-b232-9cbbae053e8b

curl --location 'http://127.0.0.1:9001/swagger/test/invoke/day/dataimport/0a27b751-db52-4ec2-b2bc-e7b747c0bfb6/5a3e3999-fccb-43ef-b232-9cbbae053e8b/WECHAT_WECOM'

curl --location 'http://127.0.0.1:9001/swagger/test/invoke/day/dataimport/27edd606-d875-42a1-812b-e823a2727e75/27c4853e-f2c5-44c8-866d-42488e9ef999/WECHAT_WECOM'

6.3 Common WeCom error codes

https://developer.work.weixin.qq.com/document/path/96213