通信报文¶
目录
授权服务¶
信令操作¶
申请信令¶
用于终端向服务器申请可用的访问令牌。
Action
applyToken
- C -> S
字段
类型
必填
描述
domain
string
Y
App 的访问域
appKey
string
Y
App 的 Key 串
- S -> C
字段
类型
必填
描述
code
int
Y
data
JSON
Y
申请到的令牌数据,参看 Auth Token
获取指定令牌码的令牌¶
用于通过令牌编码查找其对应的令牌信息。
Action
getToken
- C -> S
字段
类型
必填
描述
code
string
Y
令牌编码
- S -> C
字段
类型
必填
描述
code
int
Y
data
JSON
Y
令牌数据,参看 Auth Token
联系人服务¶
终端操作¶
终端签入¶
用于终端将指定联系人及其当前设备签入到服务器。签入操作是客户端获得一切服务操作的前提,服务器将签入的联系人及其提供的合法令牌进行绑定,从而授权签入联系人进行相关操作。
Action
signIn
- C -> S
使用联系人和令牌签入¶ 字段
类型
必填
描述
self
JSON
Y
当前终端的联系人描述,参看 Contact
token
JSON
Y
当前使用的令牌,参看 Auth Token
使用令牌码签入¶ 字段
类型
必填
描述
code
string
Y
当前有效令牌的令牌码,参看 Auth Token
联系人操作¶
获取联系人附录数据¶
获取指定联系人对应的附录数据。
Action getAppendix
- C -> S
字段
类型
必填
描述
contactId
long
Y
联系人 ID
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
联系人附录数据,参看 Contact Appendix
更新联系人附录¶
更新联系人关联的附录数据。
Action
updateAppendix
- C -> S
字段
类型
必填
描述
contactId
long
Y
附录的联系人 ID
remarkName
string
N
指定该联系人的新的备注名
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
联系人附录数据,参看 Contact Appendix
群组操作¶
获取群组附录数据¶
获取指定群组对应的附录数据。
Action
getAppendix
- C -> S
字段
类型
必填
描述
groupId
long
Y
群组 ID
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
群组附录数据,参看 Group Appendix
按照最近活跃时间查找联系人的群组¶
用于客户单列出所有当前签入的联系人所在的群组。查询条件为该群组的最近一次活跃时间。
Action
listGroups
- C -> S
字段
类型
必填
描述
beginning
long
Y
查询起始的最近一次活跃时间戳
ending
long
N
查询截止的最近一次活跃时间戳。
如果不填写,使用当前实时时间戳。state
int
N
查询 群组的状态 。
如果不填写,默认使用Normal
状态。pageSize
int
N
指定返回数据时每个数据包内包含的群组数量。
如果不填写,默认指定为4
。
添加联系人到群组¶
向指定的群组添加联系人。
Action
addGroupMember
- C -> S
字段
类型
必填
描述
groupId
long
Y
群组的 ID
memberIdList
Array<long>
Y
加入群组的联系人 ID
operator
JSON
Y
执行该操作的操作员,参看 Contact
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
群组的变化数据,参看 Group Bundle
移除群组里的联系人¶
从指定群组移除联系人。
Action
removeGroupMember
- C -> S
字段
类型
必填
描述
groupId
long
Y
群组的 ID
memberIdList
Array<long>
Y
加入群组的联系人 ID
operator
JSON
Y
执行该操作的操作员,参看 Contact
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
群组的变化数据,参看 Group Bundle
更新群组附录¶
更新群组关联的附录数据。
Action
updateAppendix
- C -> S
字段
类型
必填
描述
groupId
long
Y
附录的群组 ID
notice
string
N
群组公告内容
memberRemark
JSON
N
指定群成员备注名。JSON 结构:
id
- long :成员的 ID
name
- string : 成员的备注名remark
string
N
指定对该群的备注
following
boolean
N
指定是否关注该群组
memberNameDisplayed
boolean
N
指定群组是否显示群成员名称
commId
long
N
指定群组当前的通讯 ID
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
群组附录数据,参看 Group Appendix
联系人分区操作¶
创建分区¶
创建指定名称的新分区。
Action
createContactZone
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
participants
Array<JSON>
N
分区参与人列表。
列表里存储参与人的 JSON 数据,
参看 Contact Zone ParticipantdisplayName
string
N
指定分区的显示名
peerMode
boolean
N
指定是否使用对等模式。
默认值:false
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
新的分区,参看 Contact Zone
删除分区¶
删除指定名称的分区。
Action
deleteContactZone
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
客户端发送的数据,JSON 结构:
name
- string : 被删除的分区名称。
获取分区数据¶
获取指定名称的分区数据。
Action
getContactZone
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
compact
boolean
N
是否返回紧凑结构,紧凑结构不包括参与人列表
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
分区数据,参看 Contact Zone 。
如果请求数据设置compact
为true
,
则 Contact Zone 数据没有participants
字段。
添加参与人到指定分区¶
向指定分区添加参与人。
Action
addParticipantToZone
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
participant
JSON
Y
待添加的分区参与人,参看 Contact Zone Participant
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
JSON 结构:
name
- string : 分区名称
participant
- JSON : 添加的参与人 Contact Zone Participant
timestamp
- long : 新的分区时间戳
从指定分区删除参与人¶
将指定的参与人从分区移除。
Action
removeParticipantFromZone
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
participant
JSON
Y
待删除的分区参与人,参看 Contact Zone Participant
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
JSON 结构:
name
- string : 分区名称
participant
- JSON : 删除的参与人 Contact Zone Participant
timestamp
- long : 新的分区时间戳
修改分区参与人数据¶
修改指定分区参与人数据。
Action
modifyZoneParticipant
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
participant
JSON
Y
新的分区参与人,参看 Contact Zone Participant
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
新的参与人数据,参看 Contact Zone Participant
分区是否包含指定参与人¶
判断指定的参与人是否已经在指定分区里。
Action
containsParticipantInZone
- C -> S
字段
类型
必填
描述
name
string
Y
分区名称
participantId
long
Y
指定参与人 ID
- S -> C
字段
类型
必填
描述
code
int
Y
参看 联系人服务状态码
data
JSON
Y
JSON 结构:
contained
- boolean : 是否包含指定的参与人
name
- string : 分区名称
participantId
- long : 参与人 ID
文件存储服务¶
文件数据流操作¶
数据上传¶
使用 HTTP 协议分块上传文件数据。
URI :
/filestorage/file/
Content-Type :
application/octet-stream
- Form fields :
字段
类型
必填
描述
cid
long
Y
当前上传数据的联系人 ID
domain
string
Y
当前工作域
fileSize
long
Y
文件大小,单位:字节
lastModified
long
Y
文件最近一次修改时间
cursor
long
Y
当前文件区块游标
size
int
Y
当前文件区块大小,单位:字节
- HTTP Response
- FormatJSON
字段
类型
必填
描述
code
int
Y
状态码,参看 文件存储服务状态码
data
JSON
Y
负载数据
data
格式 :字段
类型
必填
描述
fileName
string
Y
文件名
fileSize
long
Y
文件大小,单位:字节
fileCode
string
Y
文件码
lastModified
long
Y
文件修改时间
position
long
Y
当前上传块所在文件的结束位置
文件/目录操作¶
获取文件信息¶
通过指定文件码获取文件信息。
Action
getFile
- C -> S
字段
类型
必填
描述
fileCode
string
Y
文件码
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 文件存储服务状态码
data
JSON
Y
参看 File Label
获取目录下的文件列表¶
获取指定目录下的满足条件的文件。
Action
listFiles
- C -> S
字段
类型
必填
描述
root
long
Y
根目录 ID
id
long
Y
指定目录的 ID
begin
int
Y
查询的起始索引
end
int
Y
查询的结束索引
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 文件存储服务状态码
data
JSON
Y
JSON 字段:
root
- long : 根目录 ID
id
- long : 目录 ID
begin
- int : 起始索引
end
- int : 结束索引
list
- Array< File Label > :文件标签列表
删除子目录¶
删除指定目录下的子目录,可以进行批量删除或者递归删除。
Action
deleteDir
- C -> S
字段
类型
必填
描述
root
long
Y
根目录 ID
workingId
long
Y
工作目录的 ID
dirList
Array<long>
Y
待删除目录的 ID 列表
recursive
boolean
Y
是否递归删除
注解
当
recursive
设置为false
时,待删除目录不为空目录时则无法删除该目录。
将文件插入到目录¶
将文件插入到指定的目录。
Action
insertFile
- C -> S
字段
类型
必填
描述
root
long
Y
根目录 ID
dirId
long
Y
目标目录的 ID
fileCode
string
Y
指定待插入的文件的文件码
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 文件存储服务状态码
data
JSON
Y
JSON 结构:
directory
- Directory :操作的目录数据。
file
- File Label :插入文件的文件标签。
将文件从目录删除¶
将指定文件从指定目录删除。支持批量操作。
Action
deleteFile
- C -> S
字段
类型
必填
描述
root
long
Y
根目录 ID
workingId
long
Y
工作目录的 ID
fileList
Array<string>
Y
待删除的文件的文件码。
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 文件存储服务状态码
data
JSON
Y
JSON 结构:
workingId
- long :工作目录 ID
workingDir
- Directory :工作的目录数据。
deletedList
- Array< File Label > :已删除的文件标签。
即时消息服务¶
会话操作¶
获取会话列表¶
获取最近有消息记录的会话列表。
Action
getConversations
- C -> S
字段
类型
必填
描述
limit
int
Y
获取会话的最大数量
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 即时消息服务状态码
data
JSON
Y
JSON 结构:
total
- int :会话总数。
list
- Array< Conversation > :会话列表。
更新会话¶
用于客户端更新指定的会话数据
Action
updateConversation
- C -> S
包负载
描述
会话数据
参看 Conversation
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 即时消息服务状态码
data
JSON
Y
会话数据,参看 Conversation
消息操作¶
拉取消息¶
从服务器拉取消息。
Action
pull
- C -> S
字段
类型
必填
描述
id
long
Y
签入的联系人的 ID
domain
string
Y
签入的联系人的域
device
JSON
Y
当前拉取消息的设备,参看 Device
beginning
long
Y
消息时间戳的起始时间
ending
long
Y
消息时间戳的结束时间
标记消息已读¶
将指定消息标记为已读。服务器会实时将已读状态发送给相关联系人。
Action
read
- C -> S
对单条消息进行标记¶ 字段
类型
必填
描述
contactId
long
Y
当前签入的联系人 ID
messageId
long
Y
消息 ID
对消息进行批量标记¶ 字段
类型
必填
描述
contactId
long
Y
当前签入的联系人 ID
messageIdList
Array<long>
Y
消息 ID 列表
messageFrom
long
Y
该次操作的消息发件人 ID
对消息进行批量标记¶ 字段
类型
必填
描述
contactId
long
Y
当前签入的联系人 ID
messageIdList
Array<long>
Y
消息 ID 列表
messageSource
long
Y
该次操作的消息的群组
- S -> C [仅应答]
字段
类型
必填
描述
code
int
Y
状态码,参看 即时消息服务状态码
data
JSON
Y
客户端发送的请求数据
撤回消息¶
在有效时间内撤回已发送的消息。
Action
recall
- C -> S
字段
类型
必填
描述
contactId
long
Y
消息所属的联系人 ID
messageId
long
Y
撤回消息的 ID
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 即时消息服务状态码
data
JSON
Y
JSON 结构:
contactId
- long :联系人 ID
messageId
- long :消息 ID注解
客户端需要多次处理该数据报文。服务器会实时将被撤回的消息发送给客户端。
多方通讯服务¶
通讯场域操作¶
获取场域数据¶
获取场域的数据。
Action
getField
- C -> S
字段
类型
必填
描述
commFieldId
long
Y
场域 ID
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 多方通讯服务状态码
data
JSON
Y
场域数据,参看 Comm Field
创建场域数据¶
创建新的场域。
Action
createField
- C -> S
包负载
描述
场域的数据
参看 Comm Field
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 多方通讯服务状态码
data
JSON
Y
场域数据,参看 Comm Field
销毁场域数据¶
销毁指定的场域。
Action
destroyField
- C -> S
字段
类型
必填
描述
commFieldId
long
Y
场域 ID
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 多方通讯服务状态码
data
JSON
Y
场域数据,参看 Comm Field
通话操作¶
申请发起通话¶
用于客户端申请在指定场域内通话。
Action
applyCall
- C -> S
字段
类型
必填
描述
field
JSON
Y
场域数据,参看 Comm Field
participant
JSON
Y
参与人,参看 Contact
device
JSON
Y
参与人使用的设备,参看 Device
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 多方通讯服务状态码
data
JSON
Y
场域数据,参看 Comm Field
申请加入场域¶
用于客户端申请加入场域进行通话。
Action
applyJoin
- C -> S
字段
类型
必填
描述
field
JSON
Y
场域数据,参看 Comm Field
participant
JSON
Y
参与人,参看 Contact
device
JSON
Y
参与人使用的设备,参看 Device
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 多方通讯服务状态码
data
JSON
Y
场域数据,参看 Comm Field
申请终止在场域内的通话¶
用于客户端申请终止通话。
Action
applyTerminate
- C -> S
字段
类型
必填
描述
field
JSON
Y
场域数据,参看 Comm Field
participant
JSON
Y
参与人,参看 Contact
device
JSON
Y
参与人使用的设备,参看 Device
- S -> C
字段
类型
必填
描述
code
int
Y
状态码,参看 多方通讯服务状态码
data
JSON
Y
场域数据,参看 Comm Field