1. Object content replacement in the form of json, with high scalability and compatibility
example:
The various data settings of members share one entity, and only need to continuously merge the value of the corresponding key from the json request.
Set the administrator status of the specified group members
{
"GroupId": "@TGS#2CLUZEAEJ", // 要操作的群组（必填）
"Member_Account": "bob", // 要操作的群成员（必填）
"Role": "Admin" // 设置管理员
}Set member message mask bit
{
"GroupId": "@TGS#2CLUZEAEJ", // 要操作的群组（必填）
"Member_Account": "bob", // 要操作的群成员（必填）
"MsgFlag": "AcceptAndNotify" // AcceptAndNotify、Discard或者AcceptNotNotify，消息屏蔽类型
}Set member's group business card
{
"GroupId": "@TGS#2CLUZEAEJ", // 要操作的群组（必填）
"Member_Account": "bob", // 要操作的群成员（必填）
"NameCard": "鲍勃" // 群名片（选填）
}Set member custom fields
{
"GroupId": "@TGS#2CLUZEAEJ", // 要操作的群组（必填）
"Member_Account": "bob", // 要操作的群成员（必填）
"AppMemberDefinedData": [ // 要操作的成员自定义字段（选填）
{
"Key":"MemberDefined1", // 要操作的群成员自定义字段Key
"Value":"ModifyData1" // 要设置的数据内容
},
{
"Key":"MemberDefined3",
"Value":"ModifyData3"
}
]
}2. The object hierarchical design is in place, and the business logic is unfolded layer by layer, well-proportioned
top content
Pull the read receipt information of group messages in batches, including read and unread information.
{
"GroupId":"@TGS#2TTV7VSII",
"MsgSeqList":[ // 拉取消息的 seq 列表
{"MsgSeq":1},
{"MsgSeq":2}
]
}Field Type Property Description
GroupId String Mandatory The ID of the group whose read receipt details are to be fetched
MsgSeqList Array Mandatory Seq list of pulled messages
MsgSeq Integer Mandatory The seq of the pulled message
{
"ActionStatus": "OK",
"ErrorCode": 0,
"ErrorInfo": "",
"GroupMsgReceiptList": [ // 已读回执信息
{
"Code": 0,
"MsgSeq": 1,
"ReadNum": 1, // 群消息已读数
"UnreadNum": 6 // 群消息未读数
},
{
"Code": 0,
"MsgSeq": 2,
"ReadNum": 1,
"UnreadNum": 6
}
]
}Detailed content
Pull the read or unread member list of group messages in batches.
{
"GroupId":"@TGS#2TTV7VSII",
"MsgSeq": 1, // 拉取消息的 seq
"Filter": 1, // 0表示拉取已读成员列表，1表示拉取未读列表
"Cursor":"", // 上一次拉取到的成员位置，第一次填写""
"Count":5 // 最多拉取多少个成员
}{
"ActionStatus": "OK",
"Cursor": "144115213529088617", // 下一次请求应该传的 Cursor 值
"ErrorCode": 0,
"ErrorInfo": "",
"IsFinish": 0, // 未拉取完毕，需要续拉
"MsgSeq": 1,
"UnreadList": [ // 未读成员列表
{
"Unread_Account": "test"
},
{
"Unread_Account": "test6"
},
{
"Unread_Account": "test3"
},
{
"Unread_Account": "test5"
},
{
"Unread_Account": "test4"
}
]
}3. Pagination design
pagination with range
example:
The administrator can query the message records of a single chat session from the perspective of one party in the session according to the time range.
For example, users user1 and user2 are chatting, and now it is necessary to query the chat records of the session between 2020-03-20 10:00:00 - 2020-03-20 11:00:00 from the perspective of user2.
{
"Operator_Account":"user2",
"Peer_Account":"user1",
"MaxCnt":100,
"MinTime":1584669600,
"MaxTime":1584673200,
"LastMsgKey":"" // 这里可以不写，为了展示完全协议结构，写上了
}Request packet field description
Field Type Property Description
Operator_Account String Mandatory UserID of one party in the session, query messages from the perspective of this UserID. In the same session, if you query messages from the perspectives of both sides of the session, the results may be different, please refer to the interface description of this interface
Peer_Account String Mandatory UserID of the other party of the session
MaxCnt Integer Mandatory Number of messages requested
MinTime Integer Mandatory The minimum value of the requested message time range (unit: second)
MaxTime Integer Mandatory The maximum value of the requested message time range (unit: second)
LastMsgKey String Optionally fill in the MsgKey of the last message pulled last time, this field needs to be filled in when continuing to pull
Response example
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"Complete": 0, // 没有结束，后面还有内容
"MsgCnt": 12, //本次拉取返回了12条消息
"LastMsgTime": 1584669680,
"LastMsgKey": "549396494_2578554_1584669680",
"MsgList": [
{
"From_Account": "user1",
"To_Account": "user2",
"MsgSeq": 549396494,
"MsgRandom": 2578554,
"MsgTimeStamp": 1584669680,
"MsgFlagBits": 0,
"IsPeerRead": 0,
"MsgKey": "549396494_2578554_1584669680",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "msg 1"
}
}
],
"CloudCustomData": "your cloud custom data"
}
{ ... } //为节省篇幅，余下的10条消息未列出
]
}"Complete": 0 in the response indicates that not all the messages in this time range have been pulled and need to be pulled continuously.
The MaxTime in the continuation request should be changed to the value of the LastMsgTime field of the response, and the LastMsgKey field of the response should be filled in at the same time, as follows:
{
"Operator_Account":"user2",
"Peer_Account":"user1",
"MaxCnt":100,
"MinTime":1584669600,
"MaxTime":1584669680,
"LastMsgKey": "549396494_2578554_1584669680"
}Response example
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"Complete": 1, // 内容结束了，不用续拉消息
"MsgCnt": 5, // 本次拉取返回了5条消息
"LastMsgTime": 1584669601,
"LastMsgKey": "1456_23287_1584669601",
"MsgList": [
{
"From_Account": "user1",
"To_Account": "user2",
"MsgSeq": 1456,
"MsgRandom": 23287,
"MsgTimeStamp": 1584669601,
"MsgFlagBits": 0,
"IsPeerRead": 1,
"MsgKey": "1456_23287_1584669601",
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "msg 13"
}
}
],
"CloudCustomData": "your cloud custom data"
},
{ ... } //为节省篇幅，余下的3条消息未列出
]
}"Complete": 1 in the response indicates that all messages in this time range have been fetched.
If the value of Complete is 0 in the response of the continuous pull, it means that the pull needs to be continued until the value of Complete is 1.
Pagination for full content
Pull all blacklists by page.
{
"From_Account": "id",
"StartIndex": 0,
"MaxLimited": 30,
}Field Type Property Description
From_Account String Required to pull the blacklist of the UserID
StartIndex Integer Mandatory The starting position of the pull
MaxLimited Integer Mandatory The maximum number of blacklists pulled per page
Response example
{
"BlackListItem": [
{
"To_Account": "id1",
"AddBlackTimeStamp": 1430000001
},
{
"To_Account": "id2",
"AddBlackTimeStamp": 1430000002
}
],
"Complete": "0" // 这个可以有，也可以隐含表达在其他字段，比如下面的字段
"StartIndex": 100, // 下页拉取的起始位置，0表示已拉完
"ActionStatus": "OK",
"ErrorCode": 0,
"ErrorInfo": "",
"ErrorDisplay": ""
} 4. Business intersection of different dimensions
The operation of different members joining different groups here conforms to the expression form of business intersection, which is a complex form that should be considered when designing APIs.
example:
Add groups in batches, and add designated friends to the newly added groups.
{
"From_Account":"id",
"GroupName":["group1","group2","group3"],
"To_Account":["id1","id2","id3"]
}Field Type Property Description
From_Account String Required A new group needs to be added for this UserID
GroupName Array Mandatory New group list
To_Account Array Optionally fill in the UserID list of friends who need to join the new group
5. Types and functions of callback design
From a processing perspective, callbacks can be divided into the following two categories:
Callback before the event occurs: The main purpose of the callback is to allow the user to intervene in the processing logic of the event, and the SDK will determine the subsequent processing process according to the callback return code (for example, callback before sending a group message).
Notification after the event occurs: The main purpose of the callback is to allow the user to achieve the necessary data synchronization, and the SDK ignores the callback return code (such as notification after the group member leaves the group).
The processing strategy for the callback timeout before the event occurs
If the callback times out before the event occurs, the default policy is to send the message normally.
The SDK also supports self-configuration of the "handling strategy for callback failure before an event occurs". For example, if the "callback before sending a group message" times out, the follow-up processing strategy is whether to send the message normally or not.
Security Considerations for Network Callbacks
Instant messaging IM supports three callback types:
HTTP callback.
For HTTPS callback, the WebServer in the background of the App is configured with a certificate issued by a CA or a free certificate issued by IM.
HTTPS 双向认证回调，App 后台的 WebServer 配置的是 CA 机构签发的证书或即时通信 IM 免费签发的证书，且启用双向认证能力。
三种方案的安全性逐步递增：
HTTP 回调存在两个缺陷：一是明文传输的数据容易被窃听，二是第三方 App 无法判断回调请求是否真正来自于即时通信 IM。
对于 HTTPS 回调，如果不启用双向认证，可以解决数据的加密问题，但依然无法确保回调的请求来源是即时通信 IM。
只有 HTTPS 与双向认证结合，才能确保第三方回调的安全性。
6. api设计的领域语义——RESTful
GET、POST、PUT、DELETE
GET用来获取资源，POST用来新建资源，PUT用来更新资源，DELETE用来删除资源
7. 大规模会议下消息命令的幂等性设计
question, // host permission
answer, // host permission + question exist[客户端做]
upvote // host permission + question exist[客户端做] + upvote exist[客户端做]
这里的upvote重复来，也只点赞一次。
之所以需要幂等性设计，主要是因为在大规模数据量中，是不可能存在上帝视角的全局checker的，比如在几千万个点赞中，找到某个人的点赞是否存在，
以此决定某个点赞可以产生与否，在一个filter之中是不会有这种检查的。
那么这种检查只能留给数据库或者客户端，留给数据库就是耗时比较高，留给客户端则是当客户端接收到点赞的时候，如果是重复的，就什么都不发生即可。
这个事情也告诉我们，大数据之中的全局map不存在，全局map只在客户端一次一次接收到所有消息的过程中，不断形成一个全局map，这个全局往往也不会绝对全局，
因为接收到的量总是不够多的，从这个层面上，没有绝对全局的这个事情还是有哲学意义的。
幂等-个体组装-个体的无绝对全局观-所有个体的最终一致。