IM 机器人对接指南
本平台支持将 AI 助手接入多个 IM 平台。选择您使用的平台，按照步骤完成对接。
前置条件
- •您需要拥有企业微信管理员权限
- •确保您的企业已开通企业微信
- •本平台已创建好 API Key（用于关联机器人）
找到智能机器人入口
登录后，按照以下路径找到智能机器人管理页面：
在左侧菜单栏，点击「安全与管理」
展开后，点击「管理工具」
在右侧内容区域，找到并点击「智能机器人」卡片
创建 API 模式机器人
进入智能机器人页面后，按照以下步骤创建机器人：
3.1 点击「创建机器人」
在页面右上角找到「创建机器人」按钮并点击。
3.2 切换至 API 模式（重要）
在创建弹窗的最底部，您会看到「切换至 API 模式创建」的链接，点击切换到 API 模式。
API 模式允许您通过回调地址接收用户消息并返回 AI 回复。
3.3 填写机器人基本信息
- • 机器人名称：给机器人起一个名字，例如「AI 助手」
- • 机器人头像：可选，上传一个头像图片
获取凭证信息
您需要从企业微信管理后台获取以下凭证：
被动回复所需（回调验证）
Token
用于验证回调请求的合法性。可点击「随机获取」自动生成。
获取路径：创建 API 模式机器人时自动生成
EncodingAESKey
用于消息加解密的密钥，共 43 个字符。点击「随机获取」自动生成。
获取路径：创建 API 模式机器人时自动生成
主动推送所需（定时任务 / Webhook）
企业 ID (CorpId)
企业的唯一标识，以 ww 开头。
获取路径：我的企业 → 企业信息 → 页面底部
Secret
智能机器人的密钥，用于获取 access_token 调用主动发消息 API。
获取路径：安全与管理 → 管理工具 → 智能机器人 → 详情
注意：CorpId 和 Secret 仅在需要主动推送消息时才需要配置。如果只需要被动回复（群里 @机器人），只需 Token 和 EncodingAESKey 即可。
在本平台创建机器人
回到本平台，进入 「IM 机器人」 页面，选择「企业微信」平台创建机器人，填写上述凭证。
创建成功后获取回调地址：
- 创建完成后，进入机器人「详情/编辑」页面
- 在「平台配置」区域找到「回调地址」卡片
- 点击「复制」按钮获取完整回调地址
配置回调地址并测试
返回企业微信管理后台，将从平台复制的回调地址填入「URL」字段：
https://pinyou.xin/api/v1/imbot/wecom/callback/{机器人ID}回调地址格式示例，实际地址以机器人创建后生成的为准。
- 保存后企业微信会验证回调地址有效性
- 将机器人添加到企业微信群聊
- 在群里 @机器人 发送消息进行测试
凭证速查表
| 字段 | 获取路径 | 用途 |
|---|---|---|
| Token / EncodingAESKey | 创建 API 模式机器人时生成 | 被动回复 |
| CorpId | 我的企业 → 企业信息 → 页面底部 | 主动推送 |
| Secret | 安全与管理 → 管理工具 → 智能机器人 → 详情 | 主动推送 |
| 智能机器人 ID | 智能机器人详情页 URL 中的 ID | 主动推送 |
主动消息推送（进阶功能）
所有平台的机器人均支持通过定时任务和 Webhook 主动推送 AI 生成的消息。
1curl -X POST "https://pinyou.xin/api/v1/imbot/webhook/trigger/{webhookId}" \2 -H "Content-Type: application/json" \3 -H "X-Webhook-Secret: your-webhook-secret" \4 -d '{"variables": {"content": "CPU使用率超过90%", "level": "warning"}}'
常见问题
Q: 回调地址验证失败？
检查：1) 服务是否正常运行；2) 凭证信息是否正确（企微检查 Token/EncodingAESKey，钉钉检查 AppSecret）；3) 服务器是否可公网访问。
Q: 机器人不回复消息？
检查：1) 机器人状态是否「启用」；2) API Key 是否有效；3) 是否正确 @机器人（群聊场景）。
Q: 定时任务 / Webhook 推送失败？
检查：1) 推送凭证是否已配置（企微需 CorpId+Secret，钉钉需 ClientID+ClientSecret）；2) 任务/Webhook 状态是否「启用」；3) 目标 ID 是否正确。
Q: 钉钉和企业微信有什么区别？
企业微信：HTTP 回调模式，消息加密传输，支持流式回复，凭证较多。钉钉：Stream 模式（WebSocket 长连接），无需公网回调地址，支持图片多模态，配置更简单。两者都支持定时任务和 Webhook 主动推送。