PPAgent 文档

Appearance

钉钉应用 ​

步骤

  • 钉钉后台创建内部应用
  • 添加应用的机器人能力
  • 事件订阅方式选择Stream模式推送
  • 开通通讯录、卡片、消息等权限。如果不清楚，可以尽可能多的开通。建议开启企业已安装的应用列表查询权限（用于匹配当前应用的icon等信息）。
  • 应用发布后配置生效

权限列表

  • 确保应用信息修改后已经发布

支持的消息类型 ​

  • 文本消息
  • 富文本消息
  • 图片消息
  • 音频消息（支持转文字识别）
  • 视频消息
  • 文件消息
  • 文章消息（链接类型）

流式回复支持 ​

钉钉支持使用AI卡片进行流式回复，需要配置streamTemplateId参数。您可以参考钉钉文档创建流式回复的卡片模板。

创建流式模板后，需要在应用管理后台开放卡片相关权限（后台应用权限搜索"卡片"全选批量开通即可）。

使用卡片时，因为钉钉只支持markdown类型的卡片（text类型），所以需要关闭相关文字转语音技能对该source的使用，否则会出现卡片内容无法更新的情况。

使用代码配置 ​

typescript
const app = new PPAgent({
  sources: [
    {
      name: "dingbot",
      options: {
        // 必填配置
        instanceName: "ding-robot", // 实例名称，全局唯一
        clientId: "你的Client ID", // 客户端ID，在应用列表-应用管理-基础信息-凭证与基础信息页面查看
        clientSecret: "你的Client Secret", // 客户端密钥，同上
        corpId: "你的企业ID", // 企业ID，一般以ding开头，在钉钉开放平台首页可以看到
        agentId: 123456789, // 应用的AgentId，在应用管理-基础信息页面可查看，名为"原企业内部应用AgentId"
        robotCode: "dingxxxxxxxx", // 机器人代码，在应用管理-应用能力-机器人页面点击复制RobotCode获取
        
        // 以下为可选配置
        apiHost: "https://api.dingtalk.com", // API主机地址，默认为https://api.dingtalk.com
        oldApiHost: "https://oapi.dingtalk.com", // 旧API主机地址，默认为https://oapi.dingtalk.com
        debug: false, // 是否开启调试模式，默认使用环境变量中的值
        
        // 消息展示相关配置
        markdownMsgTitle: "AI助手回复", // Markdown消息标题，默认使用回复内容的前16个字
        sendAudioFormat: "amr", // 发送音频格式，支持"wav"或"amr"，默认为amr（尺寸小但效率略低于wav）
        
        // 流式回复配置
        streamTemplateId: "你的流式模板ID", // 流式回复模板ID，配置后开启流式回复
        
        // 联系人管理相关配置
        contactsCacheTime: 86400, // 联系人缓存时间（秒），默认24小时
        contactDepartId: 1, // 联系人列表ID，默认为1（根路径）。如果只希望部分部门的用户可被前端选择，可设置上级部门ID
        contactAutoloadOnStart: true, // 启动时自动加载联系人，默认为true。建议开启，避免第一次使用时等待时间过长
        contactSleepMS: 30 // 联系人获取间隔（毫秒），默认30ms。如递归调用获取用户接口触发限流，可适当调大此值
      }
    }
  ],
  // bots: [...],
  // agents: [...]
});

使用Webhook机器人 ​

WARNING

钉钉除了应用机器人外，还支持Webhook机器人，用于发送消息到群聊。与应用机器人不同，Webhook机器人支持@群成员功能，但不支持接收用户消息，所以webhook机器只能通过代码调用发送接口实现消息的发送，适合用于做消息通知。

配置方法 ​

  1. 在钉钉群中添加自定义机器人，获取Webhook地址
  2. 在配置联系人时，将Webhook URL作为用户ID使用
typescript
// 在agent配置中，toInfo参数使用webhook URL
const toInfo = [{
  userId: "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx", // Webhook URL
  userName: "群聊名称"
}];

// 支持@功能
message.atList = ["@all"]; // @所有人
// 或者@指定成员，支持使用手机号或userId
message.atList = ["13800138000", "user123"];

支持的消息类型 ​

Webhook机器人支持以下类型的消息：

  • 文本消息（会转为markdown格式发送）
  • 音频消息（仅发送识别的文本内容）
  • 图片消息（转为markdown内嵌图片发送）
  • 文章消息（转为link类型消息发送）

注意事项 ​

  1. 权限设置：需要开启机器人发消息相关权限、通讯录和部门管理相关权限、应用管理相关权限、互动卡片相关权限。

  2. 网络要求：钉钉支持直接引用外部图片显示，因此需要服务器具备公网访问能力。

  3. @功能支持：钉钉应用机器人暂不支持@人，只有webhook机器人支持@功能。

  4. 音频格式：目前测试显示钉钉支持wav格式播放，但转文字可能会失败；amr格式文件尺寸更小。

  5. 联系人获取：如果您的企业员工较多，建议设置contactAutoloadOnStart: true，避免第一次使用时等待时间过长。读取范围可以通过contactDepartId参数进行控制。如果不知道Id，可以先使用默认值，系统启动时（设置contactAutoloadOnStart为true）会输出获取到的各个部门Id。

  6. 流式回复：使用流式回复需要配置streamTemplateId并开通相关权限。使用卡片时应避免同时使用文字转语音功能。

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