Robot API接口

Robot API是供机器人服务器调用的。所有的请求都是POST请求，请求body使用json格式。所有接口的调用都必须经过签名。所有的响应数据都是JSON格式。端口使用80端口，不同于Sever API的端口(默认18080)。

关于机器人的更多理解和应用，请参考如何正确地理解机器人和野火IM应用之Webhook机器人

我们提供有Java版本的SDK，建议使用Java语言的客户使用这个SDK，其它语言可以按照本文档对接。

1. 签名规则

以下参数需要放在Http Request Header中

参数	参数说明
nonce	随机数
timestamp	当前的时间戳，为了防止重放攻击，时间戳与野火IM服务器时间戳差2个小时的请求会被拒绝
sign	签名
rid	机器人用户id

签名的计算方法： sign = sha1(nonce + "|" + SECRET_KEY + "|" + timestamp)。其中SECRET_KEY在创建机器人时指定。

2. Content-Type

"Content-Type": "application/json; charset=utf-8"

3. 响应

所有响应都是如下这个格式。成功时code为0，result为请求返回对于的数据；失败时code为错误码，msg为失败提示。

{
  "code":0,
  "msg":"success",
  "result":{
    "userId":"a"
  }
}

4. 发送消息

4.0.1. 地址

http://domain/robot/message/send

4.0.2. body

参数	类型	必需	描述
conv	json	是	会话
payload	json	是	消息负载
toUsers	string[]	否	群组或者频道中发给指定用户

4.0.3. 响应

参数	类型	必需	描述
messageUid	long	是	消息唯一ID
timestamp	long	是	服务器处理时间

4.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d   \
  "{                       \
    \"conv\": {              \
      \"type\":1,            \
      \"target\":\"a\",      \
      \"line\":0,           \
    },                        \
    \"payload\":{                 \
      \"type\":1,                       \
      \"searchableContent\":\"hello\"   \
    }                                   \
  }"                                \
  http://localhost/robot/message/send

{
  "code":0,
  "msg":"success",
  "result":{
    "messageUid":5323423532,
    "timestamp":13123423234324,
  }
}

5. 获取单条消息

5.0.1. 地址

http://domain/robot/message/get_one

5.0.2. body

参数	类型	必需	描述
messageUid	long	是	消息唯一ID

机器人只能获取自己参与会话中的消息；其它会话/无权限的消息会返回错误。文本消息的正文在响应 payload.searchableContent 中（引用消息场景：客户端引用里携带的 u（被引消息uid）即为本接口的 messageUid，可用它取回被引消息的完整原文）。

5.0.3. 响应

result 为消息数据（OutputMessageData），主要字段如下：

参数	类型	描述
messageId	long	消息ID
sender	string	发送者uid
conv	json	会话
payload	json	消息负载（文本正文在 searchableContent）
toUsers	string[]	消息的目标用户（群/频道中指定接收者时才有）
timestamp	long	服务器时间

5.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d   \
  "{                       \
    \"messageUid\":574459227613954178    \
  }"                                \
  http://domain/robot/message/get_one

{
  "code":0,
  "msg":"success",
  "result":{
    "messageId":160399542,
    "sender":"user1",
    "conv":{
      "type":1,
      "target":"groupId",
      "line":0
    },
    "payload":{
      "type":1,
      "searchableContent":"hello world"
    },
    "toUsers":[],
    "timestamp":17123423234324
  }
}

6. 更新消息

6.0.1. 地址

http://domain/robot/message/update

6.0.2. body

参数	类型	必需	描述
messageUid	long	是	消息唯一ID
payload	json	是	消息负载
distribute	int	是	是否重新分发给用户，0不重新分发，1重新分发，建议用1

消息内容对应的json格式payload请参考内置消息机器人只有普通用户的权限，不是所有消息都可以更新。可以更新的消息类型在IM服务配置文件中的message.allow_client_update_types列表中。

6.0.3. 响应

N/A

6.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d   \
  "{                       \
    \"messageUid\":5323423532,       \
    \"distribute\":1,            \
    \"payload\":{                 \
      \"type\":1,                       \
      \"searchableContent\":\"world\"   \
    }                                   \
  }"                                \
  http://domain/robot/message/update

{
  "code":0,
  "msg":"success"
}

7. 撤回消息

7.0.1. 地址

http://domain/robot/message/recall

7.0.2. body

参数	类型	必需	描述
messageUid	long	是	消息唯一ID

机器人只有普通用户的权限，一般情况下只能撤回自己发送的消息，且时限在IM服务配置的允许撤回的时间内。在群组中，如果机器人是群主或者群管理员，可以根据群主或者群管理员的权限来撤回其他人的消息。

7.0.3. 响应

参数	类型	必需	描述
result	string	是	撤回结果

7.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"messageUid\":5323423532}" http://localhost/robot/message/recall

{
  "code":0,
  "msg":"success",
  "result":"success"
}

8. 获取用户信息

8.0.1. 地址

http://domain/robot/user_info

8.0.2. body

参数	类型	必需	描述
userId	string	否（三个参数必须且只能存在一个）	用户ID
name	string	否（三个参数必须且只能存在一个）	登录名
mobile	string	否（三个参数必须且只能存在一个）	用户手机号码

8.0.3. 响应

参数	类型	必需	描述
userId	string	是	用户ID
name	string	是	登录名
displayName	string	是	显示名字
portrait	string	否	用户头像
mobile	string	否	用户手机号码
email	string	否	用户邮箱
address	string	否	用户地址
company	string	否	用户公司
extra	string	否	附加信息

8.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"userId\":\"a\"}" http://localhost/robot/user_info

{
  "code":0,
  "msg":"success",
  "result":{
    "userId":"a",
    "name":"usera"
  }
}

9. 回复消息

回复指定消息，用于机器人的自动回复功能。

9.0.1. 地址

http://domain/robot/message/reply

9.0.2. body

参数	类型	必需	描述
messageUid	long	是	被回复的消息UID
payload	json	是	回复消息负载
only2Sender	bool	否	是否只发送给原发送者，默认false

消息内容对应的json格式payload请参考内置消息

9.0.3. 响应

参数	类型	必需	描述
messageUid	long	是	消息唯一ID
timestamp	long	是	服务器处理时间

9.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d   \
  "{                       \
    \"messageUid\":5323423532,       \
    \"only2Sender\":false,            \
    \"payload\":{                 \
      \"type\":1,                       \
      \"searchableContent\":\"收到\"   \
    }                                   \
  }"                                \
  http://localhost/robot/message/reply

{
  "code":0,
  "msg":"success",
  "result":{
    "messageUid":5323423533,
    "timestamp":13123423234324,
  }
}

10. 设置回调地址

10.0.1. 地址

http://domain/robot/set_callback

10.0.2. body

参数	类型	必需	描述
url	string	否	当前机器人消息回调地址

10.0.3. 响应

N/A

10.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"url\":\"http:://localhost:8081/robot/message\"}" http://localhost/robot/set_callback

{
  "code":0,
  "msg":"success",
}

11. 获取回调地址

11.0.1. 地址

http://domain/robot/get_callback

11.0.2. body

N/A

11.0.3. 响应

参数	类型	必需	描述
url	string	否	当前机器人消息回调地址

11.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota"  http://localhost/robot/get_callback

{
  "code":0,
  "msg":"success",
  "result":{
    "url":"http:://localhost:8081/robot/message"
  }
}

12. 删除回调地址

注意不能使用设置回调地址为空的方式删除回调地址，必须调用删除回调地址接口。

12.0.1. 地址

http://domain/robot/delete_callback

12.0.2. body

N/A

12.0.3. 响应

N/A

12.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" http://localhost/robot/delete_callback

{
  "code":0,
  "msg":"success",
}

13. 获取用户信息

13.0.1. 地址

http://localhost/robot/get_info

13.0.2. body

参数	类型	必需	描述
userId	string	否（三个参数必须且只能存在一个）	用户ID
name	string	否（三个参数必须且只能存在一个）	登录名
mobile	string	否（三个参数必须且只能存在一个）	用户手机号码

13.0.3. 响应

参数	类型	必需	描述
userId	string	是	用户ID
name	string	是	登录名
displayName	string	是	显示名字
portrait	string	否	用户头像
mobile	string	否	用户手机号码
email	string	否	用户邮箱
address	string	否	用户地址
company	string	否	用户公司
extra	string	否	附加信息

13.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"userId\":\"a\"}" http://localhost/robot/get_info

{
  "code":0,
  "msg":"success",
  "result":{
    "userId":"a",
    "name":"usera"
  }
}

14. 更新自己的信息

14.0.1. 地址

http://localhost/robot/update_profile

14.0.2. body

参数	类型	必需	描述
type	int	是	更新那个字段。0，昵称；1，头像；2，性别；4，邮箱；5，地址；6，公司；7，社交账户；8，附加信息。如果要更新电话号码，需要使用admin api更新机器人信息
value	string	是	字段的新值

14.0.3. 响应

N/A

14.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"type\":1,\"value\":\"awsome robot\"}" http://localhost/robot/update_profile

{
  "code":0,
  "msg":"success"
}

15. 获取机器人资料

获取机器人自己的资料信息。

15.0.1. 地址

http://domain/robot/profile

15.0.2. body

N/A

15.0.3. 响应

参数	类型	必需	描述
userId	string	是	机器人用户ID
name	string	是	登录名
displayName	string	是	显示名字
portrait	string	否	机器人头像
mobile	string	否	手机号码
email	string	否	邮箱
address	string	否	地址
company	string	否	公司
extra	string	否	附加信息
owner	string	是	机器人拥有者
secret	string	是	机器人密钥
callback	string	否	回调地址
robotExtra	string	否	机器人附加信息

15.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" http://localhost/robot/profile

{
  "code":0,
  "msg":"success",
  "result":{
    "userId":"robot1",
    "name":"robot1",
    "owner":"user1",
    "secret":"secret123"
  }
}

16. 获取机器人owner的好友列表

获取机器人owner的好友列表。

16.0.1. 地址

http://domain/robot/friend/list

16.0.2. body

N/A

16.0.3. 响应

参数	类型	必需	描述
friends	string[]	是	好友用户ID列表

16.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" http://localhost/robot/friend/list

{
  "code":0,
  "msg":"success",
  "result":{
    "friends":["userId1","userId2","userId3"]
  }
}

17. 根据昵称搜索用户

根据昵称搜索用户。

17.0.1. 地址

http://domain/robot/user/search

17.0.2. body

参数	类型	必需	描述
keyword	string	是	搜索关键词，匹配用户昵称
searchType	int	否	搜索类型
userType	int	否	用户类型
page	int	否	分页页码，从0开始

17.0.3. 响应

参数	类型	必需	描述
userInfos	json[]	是	匹配的用户列表
keyword	string	是	搜索关键词

17.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"keyword\":\"user\"}" http://localhost/robot/user/search

{
  "code":0,
  "msg":"success",
  "result":{
    "userInfos":[
      {
        "userId":"userId1",
        "name":"user1",
        "displayName":"用户1"
      }
    ],
    "keyword":"user"
  }
}

18. 获取指定用户拥有的机器人列表

获取指定用户所拥有的机器人列表。

18.0.1. 地址

http://domain/robot/user/get_user_robots

18.0.2. body

参数	类型	必需	描述
userId	string	是	用户ID（机器人owner）

18.0.3. 响应

参数	类型	必需	描述
robotInfoList	json[]	是	机器人信息列表

18.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d "{\"userId\":\"user1\"}" http://localhost/robot/user/get_user_robots

{
  "code":0,
  "msg":"success",
  "result":{
    "robotInfoList":[
      {
        "userId":"robot1",
        "name":"robot1",
        "displayName":"测试机器人",
        "owner":"user1",
        "callback":"http://127.0.0.1:8883/robot/recvmsg"
      }
    ]
  }
}

19. 发送会议请求

机器人发送会议相关请求。

19.0.1. 地址

http://domain/robot/conference/request

19.0.2. body

参数	类型	必需	描述
robotId	string	是	机器人ID
clientId	string	是	客户端ID
request	string	是	请求类型
sessionId	long	是	会话ID
roomId	string	否	房间ID
data	string	否	附加数据
advance	bool	否	是否高级会议

19.0.3. 响应

参数	类型	必需	描述
result	string	是	请求结果

19.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d   \
  "{                       \
    \"robotId\":\"robot1\",       \
    \"clientId\":\"client1\",                        \
    \"request\":\"join\",                        \
    \"sessionId\":123456,                        \
    \"roomId\":\"room1\",                        \
    \"advance\":false                        \
  }"                                \
  http://localhost/robot/conference/request

{
  "code":0,
  "msg":"success",
  "result":"request_processed"
}

20. 设置会话级用户设置

机器人设置会话级别的用户设置，支持单聊和群聊。群聊时会写入到群内所有成员（机器人本身除外）的用户设置中；单聊时会写入到对方用户的用户设置中。

设置以用户设置的形式存储，scope为31（会话级用户设置），key的格式为 会话类型-会话线路-会话目标_type，按会话隔离。此scope只允许机器人写入，普通客户端无权修改。用户设置会自动实时同步到用户的所有端，客户端读取当前用户关于该会话的用户设置即可获取机器人写入的内容。

可用于向会话内用户同步机器人/AI的状态和进度等信息。

20.0.1. 地址

http://domain/robot/conversation/user_setting

20.0.2. body

参数	类型	必需	描述
conversation	json	是	会话，仅支持单聊（type为0）和群聊（type为1）
type	int	是	设置类型，业务方自定义
value	string	否	设置的值，可以为任意内容（如JSON），为空时清空

20.0.3. 响应

N/A

20.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robota" -d   \
  "{                       \
    \"conversation\": {              \
      \"type\":1,            \
      \"target\":\"groupId1\",      \
      \"line\":0,           \
    },                        \
    \"type\":1,                       \
    \"value\":\"processing 60%\"   \
  }"                                \
  http://localhost/robot/conversation/user_setting

{
  "code":0,
  "msg":"success"
}

21. 群操作

机器人群操作

22. 验证用户

此方法是用于开放平台应用验证用户身份的，详情请参考开放平台.

22.0.1. 地址

http://domain/robot/application/get_user_info

22.0.2. body

参数	类型	必需	描述
authCode	string	是	验证码（前端页面通过jssdk调用im sdk获取得到）

22.0.3. 响应

参数	类型	必需	描述
userId	string	是	用户ID
displayName	string	否(如果存在用户信息则一定存在)	用户昵称
portraitUrl	string	否(如果存在用户信息则一定存在)	用户头像

22.0.4. 示例

curl -X POST -H "nonce:76616" -H "timestamp":"1558350862502" -H "sign":"b98f9b0717f59febccf1440067a7f50d9b31bdde" -H "Content-Type:application/json" -H "rid":"robotId1" -d "{\"authCode\":\"auth_code\"}" http://localhost/robot/application/get_user_info

{
  "code":0,
  "msg":"success"
  "result":{
    "userId":"userid1",
    "dispalyName":"name1",
    "portraitUrl":"url"
  }
}

23. config签名

此方法是用于签名当前应用，应用前端页面调用jssdc来认证应用，详情请参考开放平台.

23.0.1. 签名方法

此功能不涉及与IM服务交互，在本地按照规则签名，然后再经JSSDK调用IMSDK，最终在IM服务使用同样的规则验证。

签名的计算方法： sign = sha1(nonce + "|" + robotId + "|" + timestamp + "|" + robotSecret)。其中robotSecret为机器人的密钥。客户端调用jssdk的config方法的参数appid、apptype、timestamp、signature分别对应channelId、0、签名的时间戳、签名。