企业微信传统应用

企业微信传统应用使用企业微信的回调模式接收用户消息，通过 Sira AI 的 Agent System 处理后返回响应。

应用场景

适用于需要主动控制消息发送逻辑的场景：

企业内部通知系统
审批流程机器人
自动化任务助手
无需打字机效果的问答助手

提示

如果需要流式打字机效果的实时响应，请使用企业微信 AI Bot。

前置要求

1. 创建企业微信应用

登录企业微信管理后台：

应用管理 → 自建 → 创建应用
填写应用信息：
- 应用名称：例如 "智能助手"
- 应用介绍：简要说明功能
- 可见范围：选择允许使用的部门/成员
点击创建应用

2. 获取配置参数

创建应用后，在应用详情页获取以下信息：

参数	说明	示例
企业ID (corp_id)	企业唯一标识	`ww123456789abc`
应用ID (agent_id)	应用的AgentId	`1000001`
应用密钥 (secret)	调用API的密钥	`abc123...xyz`

创建 Application

1. 进入应用管理

导航路径：Agent System → 应用管理 → 创建应用

2. 填写基础信息

应用名称：

系统内部使用的标识符
建议使用英文和下划线，例如：wework_customer_service

显示名称：

用户可见的友好名称
例如：客服助手

描述（可选）：

简要说明应用功能
例如：处理客户咨询和常见问题

3. 选择接入平台

从平台下拉菜单中选择：企业微信 (回调) 💼

4. 选择 Orchestrator

从下拉列表中选择要使用的 Orchestrator（编排器）。

注意

必须先创建 Orchestrator 才能创建 Application。如果列表为空，请先前往创建 Orchestrator。

5. 配置企业微信参数

必填参数

字段	说明	获取方式
企业ID (corp_id)	企业唯一标识	企业微信管理后台 → 我的企业 → 企业信息
应用ID (agent_id)	应用的AgentId	应用详情页 → 基本信息
应用密钥 (secret)	调用API的密钥	应用详情页 → Secret
回调Token	验证回调请求	自定义字符串（8-32位）
EncodingAESKey	消息加解密密钥	自定义字符串（43位Base64）

Token 和 EncodingAESKey

Token：可以使用任意 8-32 位字符串
EncodingAESKey：必须是 43 位字符，可使用企业微信后台的"随机生成"按钮

可选参数

API地址 (api_base_url)：

默认：https://qyapi.weixin.qq.com
私有化部署时需要配置自定义地址
公有云环境可留空

6. 激活状态

激活：应用立即可用
未激活：应用已创建但不处理消息

7. 保存应用

点击创建按钮，系统会自动生成回调地址。

配置回调地址

1. 复制回调地址

创建成功后，在应用卡片中找到回调地址字段，点击复制图标 📋

回调地址格式：

https://your-domain.com/api/agent-system/callback/wework/{application_id}

2. 配置企业微信

返回企业微信应用详情页：

找到接收消息 → 设置API接收
填写以下信息：
- URL：粘贴刚才复制的回调地址
- Token：与 Sira AI 中配置的 Token 一致
- EncodingAESKey：与 Sira AI 中配置的密钥一致
点击保存

3. 验证配置

企业微信会发送验证请求到回调地址：

✅ 验证成功：提示"已保存"
❌ 验证失败：检查以下内容
- 回调地址是否可公网访问
- Token 和 EncodingAESKey 是否一致
- 防火墙是否允许企业微信IP

重要

回调地址必须支持 HTTPS 和 公网访问。本地开发可使用 ngrok、frp 等内网穿透工具。

消息流程

用户发送消息

mermaid

sequenceDiagram
    participant U as 用户
    participant W as 企业微信
    participant S as Sira AI
    participant O as Orchestrator
    participant A as Agent

    U->>W: 发送消息
    W->>S: POST /callback/wework/{app_id}
    S->>S: 解密消息
    S->>O: 执行编排
    O->>A: 调用 Agent
    A-->>O: 返回结果
    O-->>S: 返回响应
    S->>S: 加密响应
    S-->>W: 返回加密消息
    W-->>U: 显示消息

消息格式

企业微信发送（加密）：

xml

<xml>
  <ToUserName><![CDATA[ww123456]]></ToUserName>
  <AgentID><![CDATA[1000001]]></AgentID>
  <Encrypt><![CDATA[加密内容...]]></Encrypt>
</xml>

解密后内容：

xml

<xml>
  <FromUserName><![CDATA[zhangsan]]></FromUserName>
  <CreateTime>1688888888</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[你好]]></Content>
  <MsgId>1234567890</MsgId>
</xml>

Sira AI 响应（加密）：

xml

<xml>
  <Encrypt><![CDATA[加密后的响应内容...]]></Encrypt>
  <MsgSignature><![CDATA[签名]]></MsgSignature>
  <TimeStamp>1688888888</TimeStamp>
  <Nonce><![CDATA[随机数]]></Nonce>
</xml>

测试应用

1. 添加可见范围

在企业微信应用详情页：

可见范围 → 添加成员
将自己添加到可见范围

2. 发送测试消息

在企业微信客户端：

打开工作台
找到刚才创建的应用
发送消息："你好"

3. 查看响应

正常情况下，应该收到 Agent 的回复。

4. 调试问题

如果没有响应，检查：

应用是否处于激活状态
Orchestrator 是否配置正确
Agent 是否正常工作
查看日志 → 系统日志，搜索关键词：wework、callback

高级配置

私有化部署

如果使用企业微信私有化部署版本：

在创建 Application 时，填写 API地址：
```
https://qyapi.your-private-domain.com
```
确保 Sira AI 服务器能访问该地址

IP白名单

在 Application 配置中，可设置 allowed_ip_ranges：

json

{
  "allowed_ip_ranges": [
    "182.254.0.0/16",
    "101.226.0.0/16"
  ]
}

企业微信公网IP段

可在企业微信开发者文档查看官方IP段。

限流配置

在 Application 配置中，可设置 rate_limit_config：

json

{
  "rate_limit_config": {
    "enabled": true,
    "max_requests_per_minute": 60,
    "max_requests_per_hour": 1000
  }
}

常见问题

回调验证失败

现象：企业微信提示"请求失败"或"URL验证失败"

排查步骤：

检查回调地址是否可公网访问（使用 curl 测试）
确认 Token 和 EncodingAESKey 配置一致
查看 Sira AI 日志：docker compose logs backend | grep "企业微信应用回调验证"
确保使用 HTTPS

消息无响应

现象：发送消息后没有任何回复

排查步骤：

检查应用是否激活
确认 Orchestrator 已正确配置
查看日志：docker compose logs backend | grep "wework"
测试 Agent 是否正常工作（使用 Web 客户端测试）

消息解密失败

现象：日志中出现 "解密失败" 错误

原因：

EncodingAESKey 配置错误
企业微信和 Sira AI 中的密钥不一致

解决方法：

重新检查 EncodingAESKey（必须 43 位）
在 Sira AI 中更新配置
在企业微信中重新保存回调配置

无法接收图片消息

现象：文本消息正常，但图片消息无响应

说明：

企业微信传统应用支持多模态消息
确认 Agent 使用的 LLM 模型支持视觉能力（如 GPT-4o、Claude 3）
查看多模态支持文档

与 AI Bot 的区别

特性	传统应用 (回调)	AI Bot (流式)
响应方式	一次性返回完整内容	逐字流式显示
用户体验	等待时间较长	打字机效果，体验更好
配置难度	中等	简单
消息控制	完全自主控制	企业微信托管
适用场景	通知、审批、结构化消息	对话、咨询、智能助手
API调用	需要手动调用企业微信API	企业微信自动处理

推荐使用 AI Bot 提供更好的用户体验。传统应用适用于需要精细控制消息格式和发送逻辑的场景。

下一步

配置企业微信 AI Bot - 获得流式打字机效果
多模态支持 - 处理图片和文件消息
Orchestrator 配置 - 优化业务逻辑编排
Agent 配置 - 调整 Agent 行为

相关文档：

企业微信传统应用 ​

应用场景 ​

前置要求 ​

1. 创建企业微信应用 ​

2. 获取配置参数 ​

创建 Application ​

1. 进入应用管理 ​

2. 填写基础信息 ​

3. 选择接入平台 ​

4. 选择 Orchestrator ​

5. 配置企业微信参数 ​

必填参数 ​

可选参数 ​

6. 激活状态 ​

7. 保存应用 ​

配置回调地址 ​

1. 复制回调地址 ​

2. 配置企业微信 ​

3. 验证配置 ​

消息流程 ​

用户发送消息 ​

消息格式 ​

测试应用 ​

1. 添加可见范围 ​

2. 发送测试消息 ​

3. 查看响应 ​

4. 调试问题 ​

高级配置 ​

私有化部署 ​

IP白名单 ​

限流配置 ​

常见问题 ​

回调验证失败 ​

消息无响应 ​

消息解密失败 ​

无法接收图片消息 ​

与 AI Bot 的区别 ​

下一步 ​