服务端开发指南（API）

本页面供快速集成使用，了解更多请访问详细文档，或者直接访问 Swagger页面。

入门

术语介绍

• app_id

  app_id是创建App时，蓝莺IM为App生成的唯一标识，是字符串类型。可从云控制台"应用信息"页面获取。

• api_endpoint

  api_endpoint是App所在API服务的地址。可从云控制台"应用信息"页面获取。

• access-token

  access-token用作权限校验。可在云控制台"Token管理"页面为App生成access-token或选用已有access-token。

API概述

蓝莺IM API服务基于HTTPS安全协议，保证了调用时数据传输的安全性。同时API服务提供访问控制，调用前先需要获取 特有的access-token，才有权限操作App下用户、群组等数据。涉及的access-token请妥善保存。

调用所有蓝莺IM API前，要获取参数api_endpoint、app_id、access-token。 参数app_id，access-token在请求的Header中使用，未特殊说明的请求Content-Type类型为application/json。

调用蓝莺IM API的请求的通用示例（请根据具体值替换用{}表示的变量）：

curl -X {METHOD} '{api_endpoint}/{URI}' \
-H "Content-Type: application/json" \
-H 'access-token: {access-token}' \
-H 'app_id: {app_id}' \

API分类

蓝莺IM API主要分为用户API、好友API、群组API、消息API、推送API， AI API。

• 用户API

  用户隶属于单个App，是即时通讯的基础。有了用户才能实现好友、群组功能。用户数据分为基本信息和设置信息。 基本信息包括邮箱、手机号、用户名、密码。设置信息包括是否自动下载缩略图和文件、邀请入群是否需要确认等。 总体上讲，用户API主要涉及到其基本信息的更新和用户的设置，相关API以/user开头，后面接具体的资源，如获取用户设置API为"GET /user/settings"。

• 好友API

  好友是用户之间的关系，蓝莺IM好友设计中用户可为好友设置备注、设置好友消息的通知方式、可申请加好友、拉黑好用等。 好友API提供了好友信息、好友申请、好友列表、好友黑名单列表等相关操作，其API以/roster开头。

• 群组API

  群组可以实现多用户通讯。蓝莺IM设计中群成员角色分为群主、群管理员、普通群成员，权限等级依次降低，群主拥有群的所有权限，管理员有操作 群成员和修改群信息群设置的权限，根据群设置能普通群成员是否具有修改群信息以及邀请用户加入群组的权限。群成员功能设计有入群邀请、入群申请、 群黑名单、群禁言列表。 主要API包括群组数据操作和群成员操作，群数据操作主要有创建群、解散群、转让群以及群信息、群设置的更新、 群公告操作、群共享文件操作，群成员操作主要有邀请用户入群、管理员处理邀请、用户申请入群、用户处理申请、设置群黑名单、设置群禁言列表、 用户退出群、将用户踢出群等，API以/group开头。

• 消息API

  消息相关API是对IM服务的封装，旨在为使用者提供简便方法以实现通讯功能。消息API以/message开头。

• 推送API

  推送相关API用于推送通知到设备，其API以/push开头。

一般情况下，请求到蓝莺IM服务的API如遇业务错误，则返回的http code为200，在response body会返回蓝莺IM自定义错误码。 具体错误码的含义见错误码页面。

下面以以下值为例介绍部分关键API，实际请求中请予以替换。

• app_id: welovemaxim
• api_endpoint: https://api.maximtop.com
• access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg

用户API

注册用户

• API描述

  为指定App注册蓝莺IM用户。

• 请求说明

  Http方法: POST 资源路径: /user/register/v2

• 参数说明
  • Header参数

• Request Body参数

• cURL请求示例

    curl -X POST 'https://api.maximtop.com/user/register/v2' \
    -H "Content-Type: application/json" \
    -H 'app_id: welovemaxim' \
    -d '{ "username": "test_user", "password": "asd"}'
  

• 返回结果示例

    {
        "code": 200,
        "data": {
            "user_id": 2302128618880,
            "auto_download": false,
            "group_confirm": false,
            "no_sounds": false,
            "no_push": false,
            "vibratory": false,
            "no_push_detail": false,
            "auth_mode": 0,
            "no_push_start_hour": 0,
            "no_push_end_hour": 0
        }
    }
  

好友API

添加好友

• API描述

  为指定用户添加好友。

• 请求说明

  Http方法: POST 资源路径: /user/add_roster

• 参数说明
  • Header参数

• Request Body参数

• cURL请求示例

    curl -X POST 'https://api.maximtop.com/user/add_roster' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880' \
    -d '{ "list": [2199040544848, 2199040544992]}'
  

• 返回结果示例

    {
        "code": 200,
        "data": true
    }
  

获取好友列表

• API描述

  获取指定用户的好友列表。

• 请求说明

  Http方法: GET 资源路径: /user/rosters

• 参数说明
  • Header参数

• Request Body参数

  无

  • cURL请求示例

  curl -X GET 'https://api.maximtop.com/user/rosters' \
  -H "Content-Type: application/json" \
  -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
  -H 'app_id: welovemaxim' \
  -H 'user_id: 2302128618880'
  

  • 返回结果示例

  {
      "code": 200,
      "data": [{
          "user_id": 2199040544848,
          "name": "a"
      }, {
          "user_id": 2199040544992,
          "name": "b"
      }]
  }
  

群组API

创建群

• API描述

  以指定用户为群主创建群组。

• 请求说明

  Http方法: POST 资源路径: /group/create

• 参数说明
  • Header参数

• Request Body参数

• cURL请求示例

    curl -X POST 'https://api.maximtop.com/group/create' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880' \
    -d '{ "name": "g001", "description": "test-group"}'
  

• 返回结果示例

    {
        "code": 200,
        "data": {
            "name": "g001",
            "status": 0,
            "description": "test-group",
            "type": 0,
            "group_id": 2306414607729,
            "owner_id": 2302128618880,
            "created_at": 1569615417000,
            "updated_at": 1569615417000,
            "member_invite": true,
            "apply_approval": 1,
            "read_ack": false,
            "history_visible": false,
            "member_modify": false
        }
    }
  

邀请用户加群

• API描述

  以指定用户为群主邀请用户加入群组。

• 请求说明

  Http方法: POST 资源路径: /group/invite

• 参数说明
  • Header参数

• Request Body参数

• cURL请求示例

    curl -X POST 'https://api.maximtop.com/group/invite' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880' \
    -d '{ "group_id": 2306414607729, "user_list": [2199040544848, 2199040544992]}'
  

• 返回结果示例

    {
        "code": 200,
        "data": [{
            "result": "success",
            "user_id": 2199040544848
        }, {
            "result": "success",
            "user_id": 2199040544992
        }]
    }
  

获取群成员列表

• API描述

  获取群成员列表，支持分页。 分页由limit和cursor字段控制，limit是每页的大小，cursor是游标。 cursor：取第某页数据后若还有成员数据，会返回cursor字段，传cursor字段会取游标的下一页数据。

• 请求说明

  Http方法: GET 资源路径: /group/member_list

• 参数说明
  • Header参数

• 查询参数参数

• cURL请求示例

    curl -X GET 'https://api.maximtop.com/group/member_list?group_id=2306414607729&limit=50' \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880'
  

• 返回结果示例

    {
        "code": 200,
        "data": [{
            "user_id": 2302128618880,
            "join_time": 1569615417000
        }, {
            "user_id": 2199040544848,
            "join_time": 1569615490000
        }, {
            "user_id": 2199040544992,
            "join_time": 1569615490000
        }],
        "version": 1569586735861
    }
  

解散群

• API描述

  解散群组。

• 请求说明

  Http方法: DELETE 资源路径: /group/destroy

• 参数说明
  • Header参数

• cURL请求示例

    curl -X DELETE 'https://api.maximtop.com/group/destroy?group_id=2306414607729' \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -H 'user_id: 2302128618880'
  

• 返回结果示例

    {
        "code": 200,
        "data": true
    }
  

发送消息API

管理员发送单聊文本消息

• API描述

  给指定目标发送消息，可以批量发给群或用户。 指定目标用targets字段表示，列表类型，列表中id只能为用户id或群id的一种，两者不能混合发送。

• 请求说明

  Http方法: POST 资源路径: /message/send

• 参数说明
  • Header参数

• Request Body参数

• cURL请求示例

    curl -X POST 'https://api.maximtop.com/message/send' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"targets":[2302128618880],"type":1,"content":"hello","content_type":0}'
  

• 返回结果示例

    {
        "code": 200,
        "data": true
    }
  

推送API

管理员发送推送通知

• API描述

  给指定目标发送通知，可以推送给APP下的所有人，也可以按标签/别名/PushToken/用户ID来推送。

• 请求说明

  Http方法: POST 资源路径: /push/notify

• 参数说明：
  • Header参数

• Request Body主要参数

• audience：推送目标。类型为字符串或JSONObject:

    "all", 表示发给所有设备
    {"tag":["tag1","tag2"]} 表示发给标签为tag1或tag2的设备
    {"alias":["alias1","alias2"]} 表示发给别名为alias1或alias2的设备
    {"user_id":[111,222]} 表示发给用户ID为111或222的设备
    {"push_token":["push_token1","push_token2"]} 表示发给PushToken为push_token1或push_token2的设备
    使用标签/别名/用户ID/pushToken推送时，列表长度不能超过500
  

• message:推送消息体, 主要字段如下，全部字段请参考API详细文档

• cURL请求示例

    推送文本给APP下所有设备：
    curl -X POST 'https://api.maximtop.com/push/notify' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"audience": "all","message": {"type": "text","title": "this is push title","body": "this is push body"}}'
  

    推送图片给push_token为token1或token2的设备:
    curl -X POST 'https://api.maximtop.com/push/notify' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"audience": {"push_token":["token1","token2"]},"message": {"type": "image","title": "this is push title","body": "this is push body","attachment_url": "https://xxx.com/images/1.jpg"}}'
  

    推送透传消息给标签为beijing或shanghai的所有设备，透传消息不会展示到通知栏上:
    curl -X POST 'https://api.maximtop.com/push/notify' \
    -H "Content-Type: application/json" \
    -H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
    -H 'app_id: welovemaxim' \
    -d '{"audience": {"tag":["beijing","shanghai"]},"message": {"type": "cmd","title": "this is push title","body": "this is push body","ext": {"key1": 12345, "key2": "xxx" }}}'
  

• 返回结果示例

    {
        "code": 200,
        "data": true
    }
  

AI API

使用API上传知识库

可以以消息形式上传文档,主要是用以下接口：

1. 发消息： https://docs.lanyingim.com/reference/server-api/message.html#put__message_send
2. 获取上传文件的上传地址和下载地址： https://docs.lanyingim.com/reference/server-api/file.html#get__file_upload_chat

上传网页文件(URL的格式，只支持HTML）：

curl --request POST \
  --url https://s-1-3-s-api.maximtop.cn/message/send \
  --header 'access-token: {管理员Token}' \
  --header 'app_id: {APPID}' \
  --header 'content-type: application/json' \
  --data '{
    "from_user_id": {知识库管理员的用户ID},
    "content":"{网页URL地址，需要以https://开头}",
    "content_type":0, //文本消息
    "ext":"{\"ai\":{\"metadata\":{}}}", //文档的metadata
    "targets":[{ChatbotID}],
    "type":1 //发送给用户
}'

上传其它格式文件：

1. 获取文件上传和下载地址

   curl --request GET \
   --url https://s-1-3-s-api.maximtop.cn/file/upload/chat?file_type=100&to_type=1&to_id={ChatbotID} \
   --header 'access-token: {管理员Token}' \
   --header 'app_id: {APPID}' \
   --header 'user_id: {知识库管理员的用户ID}' \
   --header 'content-type: application/json'
   可以得到：
   ⇥ download_url  string  下载地址
   ⇥ oss_body_param    object  上传时需要设置的OSS参数
   ⇥ upload_method string  上传方式: POST/PUT
   ⇥ upload_url    string  上传地址
   

2. 上传文件

   curl -- request {upload_method} \
   --url {upload_url}
   --data-raw '{需要以multipart/form-data的格式把oss_body_param和文件提交上来}'
   

3. 发送文件消息

   curl --request POST \
   --url https://s-1-3-s-api.maximtop.cn/message/send \
   --header 'access-token: {管理员Token}' \
   --header 'app_id: {APPID}' \
   --header 'content-type: application/json' \
   --data '{
    "from_user_id": {知识库管理员的用户ID},
    "content_type":4, //文件消息、
    "attachment": "{\"dName\":\"{文件名}\",\"url\":\"{download_url}\"}", //需要替换文件名和download_url
    "ext":"{\"ai\":{\"metadata\":{}}}", //文档的metadata
    "targets":[{ChatbotID}],
    "type":1 //发送给用户
   }'
   

   附录

错误码说明

• 1xxxx表示用户/好友体系问题
• 2xxxx表示群组体系问题
• 3xxxx表示license问题