API 定义

2022-05-19 16:49 更新

下面列出目前第三方应用可以使用的 API。

chat/getChatGroups

此接口用于获取系统中的讨论组列表。

  • 请求方式:GET  ;
  • 模块名称:chat  ;
  • 方法名称:getChatGroups  ;
  • 参数:无;
  • 返回值:JSON 对象,该对象属性定义如下:
属性名称类型说明
result字符串如果为 ‘success’ 则操作成功,如果为其他值则表示操作失败
message字符串如果操作失败,则使用此属性返回失败原因提示文本
data对象该对象定义了系统中的讨论组清单,对象属性名为讨论组的全局唯一 标识字符串(GID),属性对应的值为讨论组名称

下面为一个示例请求地址:

https://myxxb.com/api.php?m=chat&f=getChatGroups&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

正常情况下返回值如下:

{
    "result": "success",
    "data": {
        "30683aea-7a1f-4ec8-a6d6-834e0310fd7d": "第四期项目讨论",
        "81c6ba89-00ab-4431-8e47-063556ae4886": "研发部",
        "64da14c3-c07a-45af-9c61-4e638de4af26": "公司总群"
    }
}

chat/getChatUsers

此接口用于获取指定讨论组中的成员信息或者获取系统中全部成员信息。

  • 请求方式:GET  ;
  • 模块名称:chat  ;
  • 方法名称:getChatUsers  ;
  • 参数:
  • gid  :设置为要获取用户成员信息的讨论组的全局唯一 标识字符串(GID),如果留空,则请求会返回系统所有成员信息。
  • 返回值:JSON 对象,该对象属性定义如下:
属性名称类型说明
result字符串如果为 ‘success’ 则操作成功,如果为其他值则表示操作失败
message字符串如果操作失败,则使用此属性返回失败原因提示文本
data对象该对象定义了成员清单,对象属性名为成员 ID,属性对应的值为成员显示名称

下面为获取 GID 为 '30683aea-7a1f-4ec8-a6d6-834e0310fd7d'  的讨论组成员信息的示例请求地址:

https://myxxb.com/api.php?m=chat&f=getChatUsers&gid=30683aea-7a1f-4ec8-a6d6-834e0310fd7d&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

正常情况下返回值如下:

{
    "result": "success",
    "data": {
        "1": "管理员",
        "3": "张三",
        "4": "李四"
    }
}

notifyMSG

此接口用于向指定的讨论组推送通知消息。

  • 请求方式:POST  ;
  • 模块名称:chat  ;
  • 方法名称:notifyMSG  ;
  • 参数:无;
  • 返回值:JSON 对象,该对象属性定义如下:
属性名称类型说明
result字符串如果为 ‘success’ 则操作成功,如果为其他值则表示操作失败
message字符串如果操作失败,则使用此属性返回失败原因提示文本

将要推送的通知消息对象转换为 JSON 字符串形式,然后使用 data  域通过 POST 请求发送到服务器。

一个通知消息对象拥有如下属性:

属性名称类型可选性说明
receiver字符串必须值为 'users'  或者 'group'  ,如果为 'users'  则将消息通知发送给用户,用户会在通知中心(小喧喧)中接收到通知,如果是 'group'  则是向讨论组里发通知
gid字符串特定条件必须为讨论组的全局唯一字符串,指定通知发送到的讨论组,当向讨论组发送通知时必须(即 receiver 为 'group'  )
userList数组特定条件必须使用一个用户 ID 数组指定通知发送给哪些用户,当向用户发送通知时必须(即 receiver 为 'users'  )
title字符串必须通知消息的标题
subtitle字符串可选通知消息的副标题
content字符串可选通知消息的内容文本
contentType字符串必须可选值包括:'plain'  表示纯文本,'text'  表示 Markdown 格式的文本
url字符串可选该通知消息所指向的网页链接
actions对象数组可选使用  操作对象数组表示该通知支持的操作
sender对象可选通知的  发送方信息对象

通知的  操作对象包含如下属性:

属性名称类型可选性说明
label字符串必须操作按钮上显示的文本
icon字符串可选操作按钮上显示的图标
url字符串必须点击此操作按钮时要打开的页面链接
type字符串可选操作按钮类型,影响操作按钮外观,可选值包括 'primary'  、'success'  、'danger'  、'warning' 、'info'  、'important' 、'special'

发送方信息对象包容如下属性:

属性名称类型可选性说明
id字符串或数字必须标识发送方唯一身份的字符串或数字
name字符串可选发送方在界面上显示的名称
avatar字符串必须发送方头像图片链接地址

下面为一个发送通知消息的示例 POST 请求地址:

https://myxxb.com/api.php?m=chat&f=notifyMSG&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

下面为使用 JavaScript  Fetch API 发起请求示例代码:

const notifycationData = {
    receiver: 'group',
    gid: 'f3de9ff9-dcb4-49de-915b-377ee9143418',
    title: '测试通知消息',
    subTitle: '测试通知消息副标题',
    content: '**测试消息**内容',
    contentType: 'text',
    url: 'http://xuan.im',
    actions: [
        {
            type: 'danger',
            label: '更新日志',
            url: 'https://xuan.im/page/changelogs.html'
        }, {
            type: 'normal',
            label: '下载地址',
            url: 'http://xuan.im/page/download.html'
        }
    ],
    sender: {
        avatar: 'https://avatars2.githubusercontent.com/u/472425?s=460&v=4',
        name: 'Catouse',
        id: 'catouse'
    }
};
const formData = new FormData();
formData.append('data', JSON.stringify(data));
const postUrl = 'https://myxxb.com/api.php?m=chat&f=notifyMSG&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8';
fetch(postUrl, {
    method: 'POST',
    body: formData
}).then(r => {
    return r.json();
}).then(response => {
    if (response && response.result === 'success') {
        console.log('操作成功');
    }
});

正常情况下返回值如下:

{
    "result": "success"
}


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号