> ## Documentation Index
> Fetch the complete documentation index at: https://java.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WeCom Channel

`agentscope-extensions-channel-wecom` connects your Agent to WeCom (企业微信 / WeChat Work) via the **encrypted callback** mechanism. A Spring `@RestController` receives message callbacks, decrypts them, and dispatches through the Gateway.

## When to use

* Your Agent needs to respond to WeCom bot messages in 1:1 chats or group chats.
* Your application already runs Spring Boot.

## Add the dependency

```xml theme={null}
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-channel-wecom</artifactId>
    <version>${agentscope.version}</version>
</dependency>
```

## Prerequisites

1. Create an **Application** in the [WeCom Admin Console](https://work.weixin.qq.com/).
2. Enable the **Receive Messages** API and configure the callback URL:
   `https://your-host/api/channels/wecom/{channelId}/callback`
3. Note down the **Corp ID**, **Agent ID**, **Secret**, **Token**, and **EncodingAESKey**.

## Quickstart

```java theme={null}
WeComChannel channel = WeComChannel.fromProperties(
    "my-wecom",
    ChannelConfig.of("my-wecom", "main"),
    Map.of(
        "corpId",         "your-corp-id",
        "agentId",        "1000002",
        "secret",         "your-secret",
        "token",          "your-callback-token",
        "encodingAesKey",  "your-encoding-aes-key"
    ));

GatewayBootstrap gw = GatewayBootstrap.builder()
    .agent("main", agent)
    .channel(channel)
    .build();

gw.start();
```

## Configuration properties

| Property | Required | Default | Description |
| - | - | - | - |
| `corpId` | Yes | — | Enterprise Corp ID |
| `agentId` | Yes | — | Application Agent ID |
| `secret` | Yes | — | Application secret for access token |
| `token` | Yes | — | Callback token for signature verification |
| `encodingAesKey` | Yes | — | AES key for message encryption/decryption |
| `callbackPath` | No | `/api/channels/wecom/{channelId}/callback` | Override the callback URL path |
| `apiBase` | No | `https://qyapi.weixin.qq.com` | WeCom API base URL |

## Encryption

All WeCom callbacks are encrypted. The adapter handles decryption and signature verification automatically using `WeComCrypto`, which implements the [WeCom callback encryption spec](https://developer.work.weixin.qq.com/document/path/90238).

## Message flow

**Inbound:** `WeComCallbackController` → URL verification (echostr) → decrypt → MsgId dedup → `WeComInboundMapper` (text messages) → bot-loop guard → Gateway.

**Outbound:** `WeComOutboundClient` sends replies via `/cgi-bin/message/send` (DMs) or `/cgi-bin/appchat/send` (groups), authenticating with an `access_token` from `WeComAccessTokenProvider`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.