API 参考
圈组

开通和配置第三方机器人

更新时间: 2024/07/29 17:31:56

本文主要介绍如何在控制台开通并配置第三方机器人。

配置好第三方机器人后,可在单聊或群聊中与机器人进行互动。

前提条件

已注册计划接入的第三方机器人服务的相应账号,获取 API 密钥。

实现流程

  1. 在控制台首页应用管理中选择应用,然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。

    image.png
  2. 顶部选择账号管理页签,单击机器人右侧的子功能配置

    机器人子功能配置.png

  3. 单击添加机器人按钮,进入机器人具体配置页。

    • 填写机器人信息

      机器人信息.png

      字段 必填 说明
      机器人accid 输入机器人对应的 IM 账号(accid)
      可以是已注册的云信 IM 账号,也可以是未注册过的用户自定义的账号(云信后台会自行注册对应的 IM 账号)
      机器人名称 输入机器人名称
      头像 上传机器人头像,支持 jpg/png/jpeg 格式,单个文件大小限制 5MB 以内
      机器人能力 选择机器人的能力,默认为“微软openAI ChatGPT”,也可以选择自定义的机器人能力
    • 配置机器人能力

      微软openAI ChatGPT

      若选择 “微软openAI ChatGPT” 机器人能力,则需要配置对应的 Azure OpenAI,具体请参考微软官网文档

      AzureOpenAI.png

      自定义的机器人

      若选择 “自定义” 机器人能力,则需要配置对应的 Webhook 地址。自定义机器人 Webhook 的请求和响应格式需要满足具体的接口规范,否则云信服务器将不会处理相关请求。

      自定义机器人配置.png

    • 配置消息逻辑

      机器人消息逻辑.png

      字段 必填 说明
      消息回溯条数 发给 ChatGPT 需要往前回溯的消息条数限制
      消息回溯时间 发给 ChatGPT 需要往前回溯消息的时间限制
      回复消息是否直接下放 直接下发的消息不会回调至业务服务器,也不会通过云信自带审核服务,默认为是
  4. 配置完后,单击保存,即机器人创建完成,可以与机器人开始对话。

    可以配置多个机器人,且 webhook 地址可以相同。

自定义机器人 Webhook 接口规范

自定义机器人 Webhook 的请求和响应格式需要满足具体的规范要求,否则云信服务器将不会处理相关请求。

请求格式

请求头说明

您需在请求头中传入如下参数:

Header 参数 类型 说明
AppKey String 您的应用的 App Key,具体获取方式请参见获取 App Key
CurTime Long 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数(Long)
MD5 String 根据请求中的 request body 计算出来的 MD5 值
CheckSum String 校验值
Content-Type String 请求消息体类型,一般为:application/json
  • MD5值计算示例:

    java
        String requestBody = "{}";
        String MD5 = CheckSumBuilder.getMD5(requestBody); //参考 接口概述 -> API checksum校验 部分
    
    
  • CheckSum值计算示例:

    java
        String AppSecret = "90ud57s6****";
        String MD5 = "9894907e4ad9de467809127750******";
        String CurTime = "1440570500855";  ////当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String)
        String CheckSum = CheckSumBuilder.getCheckSum(AppSecret, MD5, CurTime); //参考 接口概述 -> API checksum校验 部分
    

请求的 HTTP Body 说明

Body 为消息体,统一为 JSON 格式。

具体字段信息如下:

参数名称 类型 必须 说明
msg JSON 用户发送给机器人的消息
lastMsgs JSONArray 需要回溯的消息,每个JSON 为一条回溯的 msg

示例:

java{
  "msg": {
    "fromAccount": "xx",
    "to": "acc2",
    "robotAccid": "acc2",
    "robotFunction": "acc2",
    "robotTopic": "aaa",
    "robotCustomContent": "xx",
    "msgType": "TEXT",
    "body": "XX",
    "attach": "xx",
    "ext": "xx",
    "msgTimestamp": 123,
    "msgidClient": "xxx",
    "msgidServer": 222
  },
  "lastMsgs": [
    {},
    {}
  ]
}

响应格式

响应的 Content-Type Header 需要设置为 application/json; charset=utf-8

响应消息体为 JSON 格式,示例:

java{
  "code":200,
  "data":{
        "type":0,
        "body":"xxx",
        "antispam":false
     }
}

data 中为第三方机器人返回的消息体详情,具体参数说明请参考以下表格:

  • 消息体中并不是每个字段都一定会返回,注意对各字段的判空处理。
  • 第三方机器人返回的参数字段(响应参数)与云信 IM 发送消息接口(/msg/sendMsg.action)接口的请求参数一致。
单击查看具体参数说明 ​ ​ ​
参数类型说明
typeInteger
  • 0:文本消息
  • 1:图片消息
  • 2:语音消息
  • 3:视频消息
  • 4:地理位置消息
  • 6:文件消息
  • 10:提示消息
  • 100:自定义消息对于未开通安全通(即易盾反垃圾)功能的应用,自定义消息不会过内容审核。
bodyString 消息内容,最大长度 5000 字符,JSON 格式,具体请参见:消息格式示例消息格式示例
msgDescString消息描述文本,对文本消息和提示消息以外的消息类型有效,最大长度 500 字符。该描述信息可用于云端历史消息关键词检索
antispam Boolean 已开通安全通的前提下,是否对自定义消息的指定内容(antispamCustom)进行审核,默认 false
该参数只对自定义消息(消息类型为:100 )生效。
antispamCustom String 在 antispam 参数为 true 时生效
自定义的反垃圾检测内容, JSON 格式,长度限制同 body 字段,不能超过 5000 字符,要求 antispamCustom 格式如下:

{"type":1,"data":"custom content"}

字段说明:
type: 1:文本,2:图片
data: 文本内容或图片地址
option String 发消息时特殊指定的行为选项,JSON 格式,可用于指定消息的漫游、存云端历史、发送方多端同步、推送、消息抄送等特殊行为。option 中字段不填时表示默认值 ,option 示例:

{"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true}

字段说明:
  • roam: 该消息是否需要漫游,默认 true(需要已为应用开通漫游消息功能)
  • history: 该消息是否存云端历史,默认 true
  • sendersync: 该消息是否需要发送方多端同步,默认 true
  • push: 该消息是否需要 APNs 推送或 Android 系统通知栏推送,默认 true
  • route: 该消息是否需要抄送至指定的应用服务器;默认 true (需要已为应用开通消息抄送功能);
  • badge: 该消息是否需要计入到未读计数中,默认 true;
  • needPushNick: 推送文案是否需要带上昵称,不设置该参数时默认 true
  • persistent: 是否需要存离线消息,不设置该参数时默认 true。离线消息指不在线时其他人发来的消息。如果存离线,在用户下次登录时,IM 服务端会自动将离线期间暂存的离线消息自动下发到客户端SDK。单聊场景下发最近 30 天内的最新的 5000 条离线消息,且每个会话最多 100 条最新的离线消息;群聊场景下发最近 30 天内的离线消息,且每个群聊会话最多下发 100 条最新的离线消息。
  • sessionUpdate: 是否将本消息更新到服务端会话列表中本会话的最后一条消息(lastmsg),默认 true
pushcontent String 推送文案,最长 500 字符。option 选项中允许推送(push=true)后才能配置推送文案。pushcontent 如果不填,则使用默认文案。推送文案的显示规则如下:
  • pushcontent不为空且needPushNick=true,最终推送文案为:推送者昵称+pushcontent
  • pushcontent不为空且needPushNick=false,最终推送文案为:pushcontent
  • pushcontent为空且needPushNick=true ,最终推送文案为:推送者昵称+默认文案
  • pushcontent为空且needPushNick=false,最终推送文案为:默认文案
其中,根据消息类型,默认文案分为以下几种:
  • 文本消息默认文案:发来了一条消息
  • 地理位置默认文案:发来了一个地理位置
  • 语音消息默认文案:发来了一段语音
  • 视频消息默认文案:发来了一段视频
  • 文件消息默认文案:发来了一个文件
  • 图片消息默认文案:发来了一张图片
  • 语音聊天邀请消息默认文案:发来了语音聊天邀请
  • 视频聊天邀请消息默认文案:发来了视频聊天邀请
payload String 推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置
ext String 开发者扩展字段,必须是 JSON 格式,长度限制1024字符
forcepushall Boolean 发送群消息时,强推(@操作)列表是否为群里除发送者外的所有有效成员,默认为 false
forcepushlist String 发送群消息时的强推(@操作)用户列表,格式为JSONArray,如["accid1","accid2"]。若 forcepushall 为 true,则 forcepushlist 为除发送者外的所有有效群成员最多可强推 100 个用户,如果超过将报错(状态码:811)。
forcepushcontent String 发送群消息时,针对强推列表forcepushlist中的用户,强制推送的内容,最大 500 字符
useYidun Integer 单条消息(包括自定义消息)是否使用安全通(即易盾反垃圾),只能传 0,传其他值相当于不传
0:(在已开通安全通的情况下)不使用安全通

若不填此字段,即在默认情况下,若应用开通了易盾反垃圾功能,则使用易盾反垃圾来进行垃圾消息的判断
bid String 安全通业务 ID,可以指定当前消息过安全通某个检测配置,若不填则使用原来的检测配置
yidunAntiCheating String 透传给易盾的反作弊检测参数,格式为 JSON,长度限制 1024 字符(具体请参见易盾的反垃圾防刷版专属字段
  • 反作弊相关的email、phone、token、extension,抄送到yidunAntiCheating。其他用户增值信息,抄送到 yidunAntiSpamExt。
  • yidunAntiSpamExt 传入的值默认覆盖 extension。
  • yidunAntiSpamExt String 透传给易盾的反垃圾含圈组版的检测参数,格式为 JSON,长度限制 1024 字符(具体请参见易盾的反垃圾含圈组版用户可扩展字段反作弊相关的email、phone、token、extension,抄送到 yidunAntiCheating。其他用户增值信息,抄送到 yidunAntiSpamExt。
    markRead Integer 群消息是否需要已读业务(仅对群消息有效),0:不需要,1:需要
    async Boolean 是否异步,默认 false
    checkFriend Boolean 是否为好友关系才能发送消息,默认为 false
    如需设置为好友关系才能发送消息,需先在云信控制台完成配置。
    subType Integer 自定义消息子类型,大于0
    msgSenderNoSense Integer 发送方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息发送者无该消息的多端、漫游、历史记录等可设置是否在历史记录查询结果中包含无感知消息,具体参见单聊云端历史消息查询群聊云端历史消息查询
    msgReceiverNoSense Integer 接受方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息接收者者无该消息的多端、漫游、历史记录等可设置是否在历史记录查询结果中包含无感知消息,具体参见单聊云端历史消息查询群聊云端历史消息查询
    env String 当前消息需要抄送到的环境的名称,对应您在云信控制台中配置的自定义抄送的环境名称,最大 32 个字符
    此文档是否对你有帮助?
    有帮助
    去反馈
    • 前提条件
    • 实现流程
    • 自定义机器人 Webhook 接口规范
    • 请求格式
    • 请求头说明
    • 请求的 HTTP Body 说明
    • 响应格式