# Configure WeCom application messages and contacts

A WeCom custom app lets an agent send application messages to members within the app's visibility scope and query contacts. Configure callbacks separately when incoming messages should trigger MOI.

## Prepare a custom app

You need access to the [WeCom administration console](https://work.weixin.qq.com/wework_admin/) and permission to manage custom apps. Otherwise, ask an administrator to create the app and provide matching CorpID, AgentID, and Secret values.

### 1. Create the app

Open **App management → App management**. In the custom-app section, select **Create app**. Enter a name such as “MOI notifications,” include at least the test members in its visibility scope, and create it.

### 2. Copy enterprise and app credentials

Open **My enterprise → Enterprise information** and copy the enterprise ID; this is MOI's **CorpID**.

Return to app management, open the created app, and copy **AgentId** and **Secret**. They correspond to **AgentID** and **Secret** in MOI. Use credentials belonging to the same enterprise and app.

## Create the MOI instance

Open **Resource Center → Tools → WeCom → Add → Application messages/Contacts**. Enter the instance name and app credentials. Generate callback values only if the receiving workflow needs them.

| MOI field | Value |
| --- | --- |
| Tool instance name | A name such as “MOI WeCom test app” |
| CorpID | Enterprise ID from My enterprise → Enterprise information |
| AgentID | The custom app's AgentId |
| Secret | The same custom app's Secret |
| Callback Token | Generate and fill for receiving-message callbacks |
| EncodingAESKey | Generate and fill only when callbacks use encryption |
| Connection timeout (seconds) | Optional; default 30 |

Save and test. A successful test indicates MOI can call the app interfaces using the current CorpID, AgentID, and Secret. It does not establish delivery to a member.

## Receive message callbacks (optional)

Use this flow only when incoming WeCom messages should trigger an agent or task.

1. Open the saved instance's details and copy its **Public callback URL**.
2. Edit the instance, select **Generate** for **Callback Token**, and copy the value. Generate and copy **EncodingAESKey** too when using encrypted callbacks. Save the matching values.
3. In the custom app's receive-messages settings, enter the public URL, token, and encryption key if applicable, then complete URL verification.
4. Return to MOI instance details and add a forwarding rule pointing to the target agent or task.
5. Send a test message to the app in WeCom and verify that the target runs.

## Validate and troubleshoot

Bind the instance to the target agent and request a test message to a member within the app's visibility scope. Confirm receipt in the WeCom client.

| Symptom | Check first | Next action |
| --- | --- | --- |
| Connection test fails | Matching CorpID, AgentID, and Secret | Copy them again and inspect app permissions and trusted-IP settings |
| Sending fails | Test member in the app's visibility scope | Add the intended member to that scope and retry |
| Callback URL verification fails | URL, token, and encryption key from the same instance | Copy matching values; leave EncodingAESKey empty in plaintext mode |
| Verified but no execution | Enabled MOI forwarding rule | Add a rule and specify its agent or task |

- [WeCom configuration](../wecom.md)