⚠️ 注：自喧喧2.5.5版本后， 变更了应用集成 API 接口xxbserver.com/api.php，将应用集成 API 接口并入x.php，之前的api.php已弃用！

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

im/getGroupChats

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

• 请求方式：GET；
• 模块名称：im；
• 方法名称：getGroupChats；
• 参数：无；
• 返回值：JSON 对象，该对象属性定义如下：

属性名称	类型	说明
result	字符串	如果为'success'则操作成功，如果为其他值则表示操作失败
message	字符串	如果操作失败，则使用此属性返回失败原因提示文本
data	对象	该对象定义了系统中的讨论组清单，对象属性名为讨论组的全局唯一 标识字符串（GID），属性对应的值为讨论组名称

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

https://myxxb.com/x.php?m=
                    im&f=
                    getGroupChats&code=
                    myAppCode&token=
                    f5633c34c0c551a16c1d63bceb38d6a8

正常情况下返回值如下：

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

im/getChatUsers

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

• 请求方式：GET；

• 模块名称：im；

• 方法名称：getChatUsers；

• 参数：

  • gid：设置为要获取用户成员信息的讨论组的全局唯一 标识字符串（GID），如果留空，则请求会返回系统所有成员信息。

• 返回值：JSON 对象，该对象属性定义如下：

属性名称	类型	说明
result	字符串	如果为'success'则操作成功，如果为其他值则表示操作失败
message	字符串	如果操作失败，则使用此属性返回失败原因提示文本
data	对象	该对象定义了成员清单，对象属性名为成员 ID，属性对应的值为成员显示名称

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

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

正常情况下返回值如下：

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

im/sendNotification

此接口用于向通知中心（小喧喧）推送通知消息。

• 请求方式：POST；
• 模块名称：im；
• 方法名称：sendNotification；
• 参数：无；
• 返回值：JSON 对象，该对象属性定义如下：

属性名称	类型	说明
result	字符串	如果为'success'则操作成功，如果为其他值则表示操作失败
message	字符串	如果操作失败，则使用此属性返回失败原因提示文本

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

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

属性名称	类型	可选性	说明
users	数组	特定条件必须	使用一个用户 ID 数组指定通知发送给哪些用户，例如[1, 4]，也可以指定一个用户账号组成的数组，例如['admin', 'zhangsan', 'lisi']
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/x.php?m=
        im&f=
        sendNotification&code=
        myAppCode&token=
        f5633c34c0c551a16c1d63bceb38d6a8

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

const data = {
    users: [1, 3],
    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 postUrl = 'https://myxxb.com/x.php?m=im&f=sendNotification&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8';
fetch(postUrl, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(data),
    credentials: 'omit'
}).then(r => {
    return r.json();
}).then(response => {
    if (response && response.result === 'success') {
        console.log('操作成功');
    }
});

正常情况下返回值如下：

{
    "result": "success"
}

im/sendChatMessage

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

• 请求方式：POST；
• 模块名称：im；
• 方法名称：sendChatMessage；
• 参数：无；
• 返回值：JSON 对象，该对象属性定义如下：

属性名称	类型	说明
result	字符串	如果为'success'则操作成功，如果为其他值则表示操作失败
message	字符串	如果操作失败，则使用此属性返回失败原因提示文本

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

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

属性名称	类型	可选性	说明
gid	字符串	特定条件必须	为讨论组的全局唯一字符串，指定通知发送到的讨论组，当向讨论组发送通知时必须（即receiver为'group'）
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/x.php?m=
        im&f=
        sendChatMessage&code=
        myAppCode&token=
        f5633c34c0c551a16c1d63bceb38d6a8

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

const data = {
    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 postUrl = 'https://myxxb.com/x.php?m=im&f=sendChatMessage&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8';
fetch(postUrl, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(data),
    credentials: 'omit'
}).then(r => {
    return r.json();
}).then(response => {
    if (response && response.result === 'success') {
        console.log('操作成功');
    }
});

正常情况下返回值如下：

{
    "result": "success"
}