API 定义
下面列出目前第三方应用可以使用的 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"
}