服务器端API

服务器端 API 是开放的,你可以使用自己熟悉的技术(例如 node.js、go、swift)实现自己的服务器端。

请参考以下 API 设计来开发自己的服务器端。

数据库设计参考

MySql 数据库参见 https://github.com/easysoft/xuanxuan/blob/master/ranzhi/db/xuanxuan.sql

Chat 表

存储会话数据。

名称类型必须/可选说明
idnumber必须存储在远程数据库的id,客户端根据此id值是否设置来判定是否为远程保存的对象
gidstring必须当客户端向系统提交新的会话时,会创建全局唯一的id
namestring可选会话名称,当为空时,客户端会自动生成会话名称
typestring可选表明会话类型:system(系统), one2one(一对一), gourp(多人讨论组), project, product等
adminsstring可选会话管理员用户列表
committersstring可选会话允许发言用户清单
subjectint可选主题会话关联的主题(product, project等)ID
publicbool可选是否公共会话
createdBystring必须创建者的账号
createdDatedatetime必须创建会话时服务器的时间戳
editedBystring可选编辑者的账号
editedDatedatetime可选编辑会话时服务器的时间戳
lastActiveTimedatetime可选会话最后一次发送消息时服务器的时间戳
[users]关联数据集必须包含此会话的所有成员,和每个成员加入此会话的时间
[messages]关联数据集必须包含此会话的所有消息

Message 表

存储会话消息数据。

名称类型必须/可选说明
idnumber必须存储在远程数据库的id,客户端根据此id值是否设置来判定是否为远程保存的对象
gidstring必须当客户端向系统提交新的消息时,会创建全局唯一的id
cgidstring必须此消息所属于的会话的gid属性,会话根据此值来查询包含的消息
userstring可选此消息发送者的用户名,广播类的消息没有此值
datenumber必须消息发送的时间戳
typestring可选消息的类型,为'normal'(默认), 'broadcast'
contentstring必须消息的内容,如果消息内容类型不是文本,则已此值为json格式的对象
contentTypestring必须消息内容的类型,为'text'(默认), 'emoticon', 'image', 'file'

UserMessageStatus

记录消息状态。

名称类型必须/可选说明
usernumber必须离线消息的目标用户id,对应用户表的id
gidstring必须当客户端向系统提交新的消息时,会创建全局唯一的id
statusstring必须消息状态

ChatsOfUser 表

存储参与会话的成员数据。

名称类型必须/可选说明
idnumber必须存储在远程数据库的id
cgidstring必须会话的gid属性
usernumber必须用户id,对应用户表的id
ordernumber可选会话显示顺序
starbool可选用户是否收藏会话
hidebool可选用户是否隐藏会话
mutebool可选用户是否开启免打扰
quitdatetime可选用户退出会话时服务器的时间戳
joindatetime必须用户加入会话时服务器的时间戳

 

API说明

名词约定

client:喧喧客户端 xxd:GO 聊天服务器 xxb:后台然之服务器

API数据格式

常见的请求对象格式

{
    userID, // 用户id,xxd -> xxb 非登录时必须
    module, // 模块名称,必须
    method, // 方法名称,必须
    test,   // 可选参数,bool,默认为false。
    params, // 参数对象,可选
    data    // 请求数据,可选,与params配合使用,通常data传输是对象
}

常见的响应数据格式

{
    module,    // 模块名称,必须
    method,    // 方法名称,必须
    users[],   // 该数据响应给哪些用户,users为空表示所有在线用户
    params,    // 参数对象,可选
    result:,   // 响应状态,可为'success'(成功), 'fail'(失败), 'denied'(拒绝,需要登录),
    message:,  // 消息,可选,当result不为success时,使用此字段来解释原因
    data       // 数据 
}

xxd启动

xxd启动时会向xxb发送一条请求,xxb收到请求将所有用户状态重置为offline。

请求

方向:xxd --> xxb
{
    module: 'chat',
    method: 'serverStart'
}

响应

方向:xxb ---> xxd
HTTP Status Code

登录

请求

方向:client --> xxd
{
    module: 'chat',
    method: 'login',
    params: 
    [
        serverName, //多然之时客户端登录的服务器名称
        account,    // 用户名
        password,   // 加密后的密码
        status      // 登录后设置的状态,包括online,away,busy
    ]
 }
方向:xxd --> xxb

xxd服务器根据module、method和serverName把请求发送给指定的xxb

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'login',
    result,
    users[],
    data: 
    {             // 当前登录的用户数据
        id,       // ID
        account,  // 用户名
        realname, // 真实姓名
        avatar,   // 头像URL
        role,     // 角色
        dept,     // 部门ID
        status,   // 当前状态
        admin,    // 是否超级管理员,super 超级管理员 | no 普通用户
        gender,   // 性别,u 未知 | f 女 | m 男
        email,    // 邮箱
        mobile,   // 手机
        site,     // 网站
        phone,    // 电话
        ranzhiUrl // 当前用户所在的然之站点地址(可选,1.3新增)
    }
}

登录成功以后xxd主动从xxb服务器获取用户列表、用户所参与的会话信息和用户的离线消息发送给当前客户端。最后把xxb服务器响应给xxd服务器的登录信息去掉users字段后,发送给此会话包含的所有在线用户。

登出

请求

方向:client --> xxd
{
    userID, //登出用户的id号
    module: 'chat',
    method: 'logout',
}
方向:xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向 xxb --> xxd
{
    module: 'chat',
    method: 'logout',
    result,
    users[],
    data:
    {             // 当前登录的用户数据
        id,       // ID
        account,  // 用户名
        realname, // 真实姓名
        avatar,   // 头像URL
        role,     // 角色
        dept,     // 部门ID
        status,   // 当前状态
        admin,    // 是否超级管理员,super 超级管理员 | no 普通用户
        gender,   // 性别,u 未知 | f 女 | m 男
        email,    // 邮箱
        mobile,   // 手机
        site,     // 网站
        phone     // 电话
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的登出信息去掉users字段后,发送给此会话包含的所有在线用户。

重复登录

当同一用户重复登录时,系统会向前一个登录的用户推送一条特殊的消息,客户端接收到该消息后应该将用户登出,并关闭相关的网络连接。该消息不需要响应或返回结果。

方向:xxd --> client
{
    module:  'chat',
    method:  'kickoff',
    message: 'This account logined in another place.'
}

获取所有用户列表

请求

方向: client --> xxd
{
    userID, //用户的id号
    module: 'chat',
    method: 'userGetlist',
    params:
    [
        idList,   // 要获取的用户信息id编号数组,可选,如果留空则获取所有用户(1.3新增)
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'userGetlist',
    result,
    users[],
    data:
    [                 // 所有用户状态数组
        {             // 其中一个用户数据
            id,       // ID
            account,  // 用户名
            realname, // 真实姓名
            avatar,   // 头像URL
            role,     // 角色
            dept,     // 部门ID
            status,   // 当前状态
            admin,    // 是否超级管理员,super 超级管理员 | no 普通用户
            gender,   // 性别,u 未知 | f 女 | m 男
            email,    // 邮箱
            mobile,   // 手机
            site,     // 网站
            phone     // 电话
        },
        // 更多用户数据...
    ],
    roles: {
        "dev": "开发者",
        "productManager": "产品经理"   
        // 更多角色表数据,格式为键名为角色代号,键值为角色显示名称
    },
    depts: [
        {id: 2343, name: "研发部", parent: 0},
        {id: 2344, name: "项目部", parent: 2343},
        // 更多部门表数据,每个对象表示一个部门信息,parent 为上级部门id,如果没有上级部门parent值为0
    ]
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

获取当前登录用户所有会话数据

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'getList',
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'getList',
    result,
    users[],
    data:
    [                       // 所有会话信息数组
        {                   // 其中一个会话信息
            id,             // 会话在服务器数据保存的id
            gid,            // 会话的全局id,
            name,           // 会话的名称
            type,           // 会话的类型
            admins,         // 会话允许发言的用户列表
            subject,        // 主题会话的关联主题ID
            public,         // 是否公共会话
            createdBy,      // 创建者用户名
            createdDate,    // 创建时间
            editedBy,       // 编辑者用户名
            editedDate,     // 编辑时间
            lastActiveTime, // 会话最后一次发送消息的时间
            star,           // 当前登录用户是否收藏此会话
            hide,           // 当前登录用户是否隐藏此会话
            members: 
            [               // 当前会话中包含的所有用户信息,只需要包含id即可
                {
                    id,     //用户id
                },
                // 更多用户...
            ],
        },
        // 更多会话数据...
    ]
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

获取当前登录用户所有离线消息

请求

方向: xxd --> xxb
{
    userID,
    module: 'chat',
    method: 'getOfflineMessages',
}

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'message',
    result,
    users[],
    data:  // 一个包含一条或多条离线消息的数组
    [
        {                // 其中一条离线消息
            id,          // 消息在服务器保存的id
            gid,         // 此消息的gid
            cgid,        // 此消息关联的会话的gid
            user,        // 消息发送的用户名
            date,        // 消息发送的时间
            type,        // 消息的类型
            contentType, // 消息内容的类型
            content,     // 消息内容
        },
        // 更多离线消息
    ]
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给当前登录用户。

更改当前登录用户的信息

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'userChange',
    params:
    [                 // 更改后的用户        
        user:         // 一个用户对象
        {
            id,       // ID
            account,  // 用户名
            realname, // 真实姓名
            avatar,   // 头像URL
            role,     // 角色
            dept,     // 部门ID
            status,   // 要设置的新状态,包括online, away, busy
            admin,    // 是否超级管理员,super 超级管理员 | no 普通用户
            gender,   // 性别,u 未知 | f 女 | m 男
            email,    // 邮箱
            mobile,   // 手机
            site,     // 网站
            phone     // 电话
        }
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'userChange',
    result,
    users[],
    data: 
    {             //当前登录用户数据     
        id,       // ID
        account,  // 用户名
        realname, // 真实姓名
        avatar,   // 头像URL
        role,     // 角色
        dept,     // 部门ID
        status,   // 状态
        admin,    // 是否超级管理员,super 超级管理员 | no 普通用户
        gender,   // 性别,u 未知 | f 女 | m 男
        email,    // 邮箱
        mobile,   // 手机
        site,     // 网站
        phone     // 电话
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

创建聊天会话

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'create',
    params:
    [
        gid,     // 会话的全局id,
        name,    // 会话的名称
        type,    // 会话的类型
        members: [{id}, {id}...] // 会话的成员列表 
        subject, //可选,主题会话的关联主题ID,默认为0
        pulic    //可选,是否公共会话,默认为false
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

服务器在创建会话时应该先检查gid是否已经存在,如果存在则直接为当前登录用户返回已存在的会话信息。

方向:xxb --> xxd
{
    module: 'chat',
    method: 'create',
    result,
    users[],
    data:               
    {                   // 新创建的会话完整信息
        id,             // 会话在服务器数据保存的id
        gid,            // 会话的全局id,
        name,           // 会话的名称
        type,           // 会话的类型
        admins,         // 会话允许发言的用户列表
        subject,        // 主题会话的关联主题ID
        public,         // 是否公共会话
        createdBy,      // 创建者用户名
        createdDate,    // 创建时间
        editedBy,       // 编辑者用户名
        editedDate,     // 编辑时间
        lastActiveTime, // 会话最后一次发送消息的时间
        members: [{id}, {id}...] // 会话的成员列表 
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

加入或退出聊天会话

用户可以加入类型为group并且公共的会话;用户可以退出类型为group的会话。

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'joinchat',
    params: 
    [
        gid, // 要加入或退出的会话id
        join // 可选, true加入会话, false退出会话, 默认为true
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'joinchat',
    result,
    users[],
    data:
    {                   // 会话的完整信息
        id,             // 会话在服务器数据保存的id
        gid,            // 会话的全局id,
        name,           // 会话的名称
        type,           // 会话的类型
        admins,         // 会话允许发言的用户列表
        subject,        // 主题会话的关联主题ID
        public,         // 是否公共会话
        createdBy,      // 创建者用户名
        createdDate,    // 创建时间
        editedBy,       // 编辑者用户名
        editedDate,     // 编辑时间
        lastActiveTime, // 会话最后一次发送消息的时间
        members: [{id}, {id}...] // 会话的成员列表 
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户(包括退出会话的当前用户)。

更改会话名称

用户可以更改类型为group的会话的名称。

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'changeName',
    params:
    [
        gid, // 要更改的会话id
        name // 新的名称
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'changeName',
    result,
    users[],
    data:
    {                   // 会话的完整信息
        id,             // 会话在服务器数据保存的id
        gid,            // 会话的全局id,
        name,           // 会话的名称
        type,           // 会话的类型
        admins,         // 会话允许发言的用户列表
        subject,        // 主题会话的关联主题ID
        public,         // 是否公共会话
        createdBy,      // 创建者用户名
        createdDate,    // 创建时间
        editedBy,       // 编辑者用户名
        editedDate,     // 编辑时间
        lastActiveTime, // 会话最后一次发送消息的时间
        members: [{id}, {id}...] // 会话的成员列表 
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

收藏或取消收藏会话

每个用户都可以单独决定收藏或取消收藏会话(加星标记)。

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'star',
    params: 
    [
        gid, // 要收藏会话id
        star // 可选, true收藏会话, false取消收藏会话, 默认为true
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'star',
    result,
    users[],
    data:
    {        // 会话的完整信息
        gid, // 会话的全局id,   
        star // true收藏会话, false取消收藏会话, 默认为true
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给当前用户。

邀请新的用户到会话或者将用户踢出会话

请求

用户可以邀请一个或多个用户到类型为group的已有会话中;会话管理员可以将一个或多个用户踢出类型为group的会话。

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'addmember',
    params: 
    [
        gid,     // 要操作的会话id
        members, // 用户id数组
        join     // 可选, true邀请用户加入会话, false将用户踢出会话, 默认为true
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

当新用户被添加到会话之后或者用户被踢出会话后,服务器应该主动推送此会话的信息给此会话的所有在线成员;此响应与chat/create/响应的结果一致。

方向:xxb --> xxd
{
    module: 'chat',
    method: 'addmember',
    result,
    users[],
    data: // 会话的完整信息
    {
        id,             // 会话在服务器数据保存的id
        gid,            // 会话的全局id,
        name,           // 会话的名称
        type,           // 会话的类型
        admins,         // 会话允许发言的用户列表
        subject,        // 主题会话的关联主题ID
        public,         // 是否公共会话
        createdBy,      // 创建者用户名
        createdDate,    // 创建时间
        editedBy,       // 编辑者用户名
        editedDate,     // 编辑时间
        lastActiveTime, // 会话最后一次发送消息的时间
        members: [{id}, {id}...] // 会话的成员列表 
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

向会话发送消息

请求

用户向一个或多个会话中发送一条或多条消息,服务器推送此消息给此会话中的所有在线成员;当前不在线的成员会在下次上线时通过离线消息送达。

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'message',
    params: 
    [                    // 一个包含一条或多条新消息的数组
        {
            gid,         // 此消息的gid
            cgid,        // 此消息关联的会话的gid
            user,        // 如果为空,则为发送此请求的用户
            date,        // 如果为空,则已服务器处理时间为准
            type,        // 消息的类型
            contentType, // 消息内容的类型
            content      // 消息内容
        },
        // 可以在一个请求中发送多个消息
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

当有新的消息收到时,服务器会所有消息,并发送给对应会话的所有在线成员

方向:xxb --> xxd
{
    module: 'chat',
    method: 'message',
    result,
    users[],
    data:                // 一个包含一条或多条新消息的数组
    [
        {
            id,          // 消息在服务器保存的id
            gid,         // 此消息的gid
            cgid,        // 此消息关联的会话的gid
            user,        // 消息发送的用户名
            date,        // 消息发送的时间
            type,        // 消息的类型
            contentType, // 消息内容的类型
            content,     // 消息内容
        },
        // 可以有更多的消息
    ]
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

获取会话的所有消息记录

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'history',
    params: 
    [
        gid,         // 要获取消息记录的会话gid
        recPerPage,  // 每页记录数
        pageID,      // 当前也数
        recTotal,    // 总记录数
        continued,   // 是否继续获取历史记录
        startDate,   // 历史记录最早的日期时间戳(秒)(1.3新增)
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'history',
    result,
    users[],
    data: 
    [
        {                // 一条历史消息
            gid,         // 此消息的gid
            cgid,        // 此消息关联的会话的gid
            user,        // 如果为空,则为发送此请求的用户
            date,        // 如果为空,则已服务器处理时间为准
            type,        // 消息的类型
            contentType, // 消息内容的类型
            content      // 消息内容
        },
        // 更多历史消息
    ],
    pager: // 分页数据
    {
        recPerPage, // 每页记录数
        pageID,     // 当前页数
        recTotal,   // 总记录数
        gid,        // 当前会话id
        continued   // 是否继续获取历史记录
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

获取会话的所有成员信息

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'members',
    params:
    [
        gid // 要获取成员列表的会话gid
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'members',
    result,
    users[],
    data: 
    [
        {
            gid, // 此消息的gid
            members: 
            [
                {
                    id,
                    // ...
                } 
            ]
        },
    ]
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

隐藏或显示会话

每个用户都可以单独决定隐藏或显示已参与的会话。

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'hide',
    params: 
    [
        gid, // 要收藏会话id
        hide // 可选, true隐藏会话, false显示会话, 默认为true
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'hide',
    result,
    users[],
    data:
    {
        gid, // 要隐藏或显示的会话id
        hide // true隐藏会话, false显示会话, 默认为true
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给当前用户。

将会话设置为公共会话或者取消设置公共会话

用户可以将一个非主题会话设置为公共会话或者取消设置公共会话。

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'changePublic',
    params: 
    [
        gid,
        public, // 可选,true设置公共会话,false取消设置公共会话,默认为true
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: ' chat';
    method: 'changepublic',
    result,
    users[],
    data: 
    {                   // 会话的完整信息
        id,             // 会话在服务器数据保存的id
        gid,            // 会话的全局id,
        name,           // 会话的名称
        type,           // 会话的类型
        admins,         // 会话允许发言的用户列表
        subject,        // 主题会话的关联主题ID
        public,         // 是否公共会话
        createdBy,      // 创建者用户名
        createdDate,    // 创建时间
        editedBy,       // 编辑者用户名
        editedDate,     // 编辑时间
        lastActiveTime, // 会话最后一次发送消息的时间
        members: [{id}, {id}...] // 会话的成员列表 
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

获取所有公共会话列表

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'getPublicList'
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'getPublicList',
    result,
    users[],
    data: 
    [         // 所有公共会话信息数组
        {     // 其中一个会话信息
            id,
            gid,
            name,
            type,
            admins, 
            subject,
            public,
            createdBy,
            createdDate,
            editedBy,
            editedDate,
            lastActiveTime
        },
        // 更多会话数据...
    ]
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

设置会话管理员

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'setAdmin',
    params: 
    [
        gid,  
        admins: [{id},{id}...], // 指定的用户列表
        isAdmin //可选, true允许指定用户发言, false禁止指定用户发言, 默认为true 
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'setAdmin',
    result,
    users[],
    data: 
    {
        id,
        gid,
        name,
        type,
        admins,
        subject,
        public,
        createdBy,
        createdDate,
        editedBy,
        editedDate
        lastActiveTime
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

设置会话允许发言的人

通过此功能可以设置会话白名单。

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'setCommitters',
    params: 
    [
        gid,  
        committers: [{id},{id}...] // 指定的用户列表
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'setCommitters',
    result,
    users[],
    data: 
    {
        id,
        gid,
        name,
        type,
        admins,
        subject,
        public,
        createdBy,
        createdDate,
        editedBy,
        editedDate
        lastActiveTime
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给此会话包含的所有在线用户。

上传下载用户在客户端的配置信息

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'settings',
    params: 
    [
        account, //用户名
        settings //用户配置信息, 可选, 为空表示下载用户配置信息, 不为空表示上传用户配置信息, 默认为空 
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'settings',
    users[],
    result, 
    data // 用户配置信息
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给当前登录用户。

为会话设置分组(1.3新增)

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'category',
    params: 
    [
        gids, // 要设置新的分组的会话 gid 数组
        category, // 新的分组名称
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'category',
    users[],
    result, 
    data: {
        gids, // 同参数
        category // 同参数
    }
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给当前登录用户。

管理员请求解散一个讨论组(1.3新增)

请求

方向:client --> xxd
{
    userID,
    module: 'chat',
    method: 'dismiss',
    params: 
    [
        gid, //要解散的讨论组gid
    ]
}
方向: xxd --> xxb

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'dismiss',
    users[],
    result, 
    data // 解散后的讨论组对象
}
方向:xxd --> client

把xxb服务器响应给xxd服务器的信息去掉users字段后,发送给当前登录用户。

通知接口

请求

方向:xxd --> xxb
{
    module: 'chat',
    method: 'notify',
    params:
    [
        offline:'', //离线用户
        sendfail:'',//失败消息
    ] 
}
响应:xxb --> xxd
{
    module: 'chat',
    method: 'notify',
    data:
    [
      {
        id:
        [
            {
                gid:                //全局唯一ID
                title:              //通知标题
                subtitle:           //通知副标题
                content:            //通知内容
                date:               //通知时间戳
                contentType:        //内容格式
                url:                //连接
                read:false          //是否已读
                actions:[
                    {
                        label:      //操作标题
                        url:        //操作指向
                        type:       //操作类型
                    }
                ]
                sender:{
                    id:             //发送方唯一标识
                    name:           //应用名称
                    avatar:         //发送方头像
                }
            }
            ...
        ]
      }
      ....
    ] 
}
方向:xxd --> client

如果有通知从xxd返回,则xxd会将消息分发给对应的用户

{
    module: 'chat',
    method: 'notify',
    data:
    [
        {
            gid:                //全局唯一ID
            title:              //通知标题
            subtitle:           //通知副标题
            content:            //通知内容
            date:               //通知时间戳
            contentType:        //内容格式
            url:                //连接
            read:false          //是否已读
            actions:[
                {
                    label:      //操作标题
                    url:        //操作指向
                    type:       //操作类型
                }
            ]
            sender:{
                id:             //发送方唯一标识
                name:           //应用名称
                avatar:         //发送方头像
            }
        }
        ...
    ] 
}

离线通知

请求

方向:xxd --> xxb

用户登录的时候会请求未读的离线消息

{
    module: 'chat',
    method: 'getOfflineNotify',
    userID: //用户ID
}
响应:xxb --> xxd
{
    module: 'chat',
    method: 'notify',
    data:
    [
        {
            gid:                //全局唯一ID
            title:              //通知标题
            subtitle:           //通知副标题
            content:            //通知内容
            date:               //通知时间戳
            contentType:        //内容格式
            url:                //连接
            read:false          //是否已读
            actions:[
                {
                    label:      //操作标题
                    url:        //操作指向
                    type:       //操作类型
                }
            ]
            sender:{
                id:             //发送方唯一标识
                name:           //应用名称
                avatar:         //发送方头像
            }
        }
        ...
    ] 
}

检测用户变更

请求

方向:xxd --> xxb

用户登录的时候会请求未读的离线消息

{
    module: 'chat',
    method: 'checkUserChange',
    params: ''
}
响应:xxb --> xxd
{
    module: 'chat',
    method: 'checkUserChange',
    data:   'yes' //是否有变更 yes或者no
}

如果返回为yes,则会请求userGetlistAPI

上传文件

请求

方向:client --> xxd

客户端通过 https 向 xxd 服务器发起 POST 请求。 请求头部需要包含如下内容:

  • ServerName:然之服务器名称;
  • Authorization:用户 token;

请求表单需要包含如下字段:

  • file:文件域,包括文件名;
  • gid:该文件所属会话的 gid;
  • userID:当前用户 id;

以下为以 JavaScript 对象存储的请求数据示例:

{
    headers: {
        ServerName: 'ranzhiServer1',
        Authorization: '12345678888888888888888888888888'
    },
    multipart: {
        {
            'Content-Disposition': 'form-data; name="file"; filename="example.txt"',
            body: e.target.result
        }, {
            'Content-Disposition': 'form-data; name="gid"',
            body: '1&2'
        }
    }
}
方向: xxd --> xxb
{
    userID,
    module: 'chat',
    method: 'uploadFile',
    params: 
    [
        fileName, // 文件名(带扩展名)
        path,     // 文件在xxd的路径
        size,     // 文件大小
        time,     // 时间戳
        gid,      // 会话ID
    ]
}

xxd把client发送的数据转发给xxb。

响应

方向:xxb --> xxd
{
    module: 'chat',
    method: 'uploadFile',
    users[],
    result, 
    data: fileID  // 文件在然之服务器数据库存储的id
}
方向:xxd --> client

xxd 服务器在客户端发起的 POST 请求中以 JSON 文本格式返回文件基本信息。

{
    result: 'success',
    data: 
    {
        url,      // 文件在xxd服务器上的下载地址(可选,无此属性会按照规则生成 URL 地址)
        time,     // 时间戳
        id,       // 文件 ID 
        name,     // 文件标题
    }
}