PPAgent 文档

Appearance

企微应用/客服 ​

企业微信应用的消息源。支持应用单聊，客服聊天以及应用和机器人的单向群推送（应用推送仅支持通过应用接口创建的群，没有机器人方便，且机器人支持Markdown，但是机器人不支持发送视频）。

步骤

  • 创建一个企业，确保有外网地址。（如果自用，不建议认证，否则后续域名必须备案且为自有域名才能使用，比如用第三方的穿透则不行）
  • 登录企微后台，选择我的企业，拉倒最下，看到corpId并记录下来
  • 在应用管理中创建自建应用（获取AgentId和Secret），设置应用的可见范围
    • 在接收消息中，开启API接收，可以获取到Token和EncodingAESKey，URL地址为 http(s)://你的域名/api/{instanceName}/receive 。接收的类型有普通消息、自定义菜单、##微信客服消息##（如果要支持客服消息，这个必须打开）
    • 开发者接口-网页授权及JS-SDK中，添加可作为应用OAuth2.0网页授权功能的回调域名的域名为你的域名
    • 企业可信IP中，添加你服务器的IP
  • 如果要启用客服支持。则还需要以下步骤：
    • 在应用管理菜单下，选择微信客服，并开启
    • 设置可见范围
    • 创建客服账号，具体信息可以随意填，因为后续会通过应用接管
    • 拉到最下方的通过API管理会话消息，点开企业内部开发，选择之前创建的应用来管理这个客服账号
  • 根据拿到的各个信息，按本文后续的代码创建实例（或者在可视化平台填入）

支持的消息类型 ​

  • 文本消息（TEXT）
  • 图片消息（IMAGE）
  • 语音消息（AUDIO）
  • 视频消息（VIDEO）
  • 文件消息（FILE）
  • 图文消息（ARTICLE）
  • 音乐消息（MUSIC）
  • 位置消息（POSITION）
  • 小程序消息（MP）- 仅客服模式支持
  • 自定义消息（CUSTOM）- 支持 "ca_link" 类型

使用代码配置 ​

typescript
const ppagent = new PPAgent({
    // ... 其他配置
    sources: [
        {
            type: "wework-app",
            name: "企业微信应用", // 可自定义名称
            corpId: "ww123456789", // 企业ID，在企微后台-我的企业最下方查看
            agentId: "1000001", // 应用的Agent ID，在企微后台-应用管理-自建应用页面详情查看
            secret: "xxxxxxxxxxxx", // 应用的Secret，在企微后台-应用管理-自建应用页面详情查看
            token: "xxxxxxxxxxxx", // API接口消息的Token，在企微后台-应用管理-自建-应用详情页-功能-消息接收-启用API接口中配置查看
            aesKey: "xxxxxxxxxxxx", // API接收消息的AES Key，在企微后台-应用管理-自建-应用详情页-功能-消息接收-启用API接口中配置查看

            // 以下为可选配置
            apiHost: "https://qyapi.weixin.qq.com", // API地址，默认为https://qyapi.weixin.qq.com
            welcomeInKfMode: false, // 客服模式下，用户第一次进入时是否发送欢迎语，默认为false
            welcomePrompt: "__欢迎{nickName}，有任何问题都可以跟我咨询", // 欢迎词的提示语，可以使用{nickName}对用户的昵称进行占位，如果以__开头，表示直接发送该欢迎词
            // 通过应用自动创建群组。自动创建的群组可以由应用主动推送消息，否则只能被动回复用户的消息或者使用webhook进行推送。
            appChatGroups: [
                {
                    userlist: ["zhangsan", "lisi"], // 群成员列表，第一个人是群主
                    chatid: "group_chat_1", // 群聊ID
                    name: "测试群聊", // 群名称
                },
            ],
        },
    ],
    // ... 其他配置
});

服务器运行请参考 install_code.md 文件。

作为应用接入 ​

默认即应用接入，支持单聊和群聊自动回复（被@）。

流式回复支持 ​

企业微信应用支持流式回复，可以通过Markdown消息进行格式化展示。

webhook机器人 ​

WARNING

默认情况使用的是应用机器人。由于webhook机器人无法接受消息，所以只能通过代码调用发送消息的接口实现发送。 ##企业微信支持通过webhook机器人发送消息到群聊。webhook机器人支持更丰富的消息格式，特别是支持Markdown格式的消息，可以实现更好的展示效果。 要使用webhook机器人，需要在企业微信群聊中添加机器人，获取webhook地址，然后配置到toInfo[0].userId中作为机器人的ID。##

作为客服接入 ​

  • 后台创建应用
  • 设置应用可以通过API访问（允许的JS回调需先配置）
  • 设置可信IP
  • 设置API接收，勾选接收客服消息
  • 企业微信客服中创建一个客服，指定一个接待人员，最下方打开通过API管理会话消息的企业内部开发，选中之前创建的应用。

注意事项 ​

  1. 只有应用创建的群聊才能够主动推送群消息，因此需要先创建群聊。往群里推消息建议使用webhook机器人，而不是应用机器人，webhook支持Markdown消息。

  2. 当启动后第一次收到客服消息时，仅会处理最新的一条客服消息。后续有新的消息进来时，将会处理最后一次到当前消息之间所有的消息。

  3. 群消息一次只发送一个群。只有机器人消息支持@。

  4. 如果希望一次性发给一群人，可以使用应用单聊同时发送多个对象，支持发群到部门ID或者标签ID，而不需要通过群。

  5. 未认证的企业，可以配置第三方域名，已经认证的企业则必须配置自己的已备案的的域名。