开发指南

本指南介绍如何调用服务端 API，调用前需了解开发前须知及调用流程。本文提供了调用服务端API示例，供开发者参考。。

如何调用服务端 API

调用前提

如下图所示，在调用吱吱服务端接口前，您需要完成以下准备工作：

步骤一：从企业后台通知机器人处获取appkey和appsecret和调用的host

步骤二：根据AppKey和AppSecret，获取企业应用内部访问接口凭证accessToken。

步骤三：携带accessToken，调用服务端api。

alt text

调用服务端 API 的通用方式：

  • 协议：HTTPS
  • 认证：header需要携带 X-AccessToken:<token>
  • 请求格式：application/json
  • 返回格式：application/json

接口响应成功以响应header中的code为200，标识是否成功，不为200的则查找对应的错误码

示例（cURL）

curl -X GET "https://api.example.com/v1/endpoint" \
  -H "X-AccessToken: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

获取 Token

调用 Token 接口获取访问凭证，凭证有效期为2个小时，获取后缓存起来

  • URL: /api/open/agent/accessToken
  • 是否需要认证: false
  • Method: POST
  • 参数:
名称类型必填说明
appkeystringtrueappkey
timestampint64true当前毫秒时间戳
noncestringtrue随机字符串
signstringtrue签名

签名生成方式

接口调用需要对请求参数进行签名校验。签名生成规则如下：

1. 排序参数

将所有待签名的参数按照 key 的字典序（升序） 排序。

例如：

{
  "timestamp": 1743436800000,
  "appkey": "testApp",
  "nonce": "123456"
}

排序后：

appkey=testApp
nonce=123456
timestamp=1692435600

2. 拼接字符串

按照 key=value 的形式拼接，中间用 & 连接。

示例：

appkey=testApp&nonce=123456&timestamp=1692435600

3. 使用 HMAC-SHA256 计算签名

使用 appSecret 作为密钥，对拼接后的字符串进行 HMAC-SHA256 计算。

4. 最终签名

最终得到的签名字符串即为 sign，在请求头或参数中传给服务端。

请求示例

curl -X POST "https://api.example.com/api/open/agent/accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "timestamp": "1743436800000",
  "appkey": "testApp",
  "nonce": "123456",
  "sign":"sign"
}'

响应示例

{
  "accessToken": "token",
  "expire": 7200,//单位秒
}
错误代码说明
200OK
400参数错误
500服务端错误
401appkey无效
402签名无效

获取用户列表

增量升序获取用户基本信息

  • URL: /api/open/user/list
  • Method: POST
  • 是否需要认证: true
  • 参数:
名称类型必填说明
uidint64true第一次拉取为0，后续请求为上次拉取的最后一个uid
limitint64true拉取的条数，最大100

请求示例

curl -X GET "https://api.example.com/api/open/user/list" \
  -H "X-AccessToken: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
  -d '{
  "uid": 0,
  "limit": 100,
}'

响应示例

{
    "users": [
        {
            "uid": 24,
            "uname": "杨某",
            "phone": "86-xxxxxxxxxxx"
        },
        {
            "uid": 32,
            "uname": "徐某",
            "phone": "86-xxxxxxxxxxx"
        }
    ]
}
错误代码说明
200OK
400参数错误
404没有token
405token无效
429请求频率过高
500服务端错误

获取群列表

增量升序获取群列表

  • URL: /api/open/group/list
  • Method: POST
  • 是否需要认证: true
  • 参数:
名称类型必填说明
gidint64true第一次拉取为0，后续请求为上次拉取的最后一个gid
limitint64true拉取的条数，最大100

请求示例

curl -X GET "https://api.example.com/api/open/group/list" \
  -H "X-AccessToken: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
  -d '{
  "gid": 0,
  "limit": 100,
}'

响应示例

{
    "groups": [
        {
            "gid": 301,//群id
            "name": "测试"//群名称
        },
        {
            "gid": 303,
            "name": "研发"
        }
    ]
}
错误代码说明
200OK
400参数错误
404没有token
405token无效
429请求频率过高
500服务端错误

调用机器人发消息

  • URL: /api/open/msg/send
  • Method: POST
  • 是否需要认证: true
  • 参数:
名称类型必填说明
gids[]int64false机器人消息发送的群对应的id
uids[]int64false机器人消息发送的人对应id
msgstringtrue文本消息 换行符为\n
gids和uids至少传一个

请求示例

curl -X POST "https://api.example.com/api/open/msg/send" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gids": [1,2],
    "uids":[1,2]
    "msg": "大家好，我是机器人~"
  }'

响应示例

{
  
}
错误代码说明
200OK
400参数错误
404没有token
405token无效
429请求频率过高
500服务端错误

注意事项

  1. header中的code为405时请重新获取token,重试请求

2、每秒最多允许 1000 次请求，如果短时间内请求达到 1000，则多余请求会被限流