OMTP协议说明文档
OMTP(Open Message Transport Protocol)是一套自定义IM消息传输协议。它工作在TCP/IP协议族上基于客户端-服务器即时通讯系统设计的消息通讯协议，数据编码方式为基于Tars/PB的二进制类型。
设计思想
将业务数据进行抽象归纳，分为频繁变动和稳定不变两部分；IM通道分离频繁变动的业务；IM 通道从复杂多变的业务中解放出来；OMTP协议只负责底层IM通道和稳定不变的业务部分；当业务频繁变化时，OMTP协议最大限度保持不变；增加业务的可扩展性，定制化特性；
协议包含的业务
IM协议的定义主要包含如下业务：
用户登录及身份认证退出登录用户被踢心跳业务通知消息发送/响应单聊消息发送/响应群聊消息发送/响应最新消息会话，未读数获取请求/响应历史消息获取/响应数据同步请求/响应开始旁听会话请求/响应结束旁听会很请求/响应群聊创建请求/响应群聊解散请求/响应群聊加人请求/响应群聊减人请求/响应群聊名称，头像等修改请求/响应
OMTP协议字段
协议格式
OMTP(Open Message Transport Protocol)控制报文由两部分组成，按照图示描述的顺序：
OMTP控制报文的结构：
字段长度说明Length4字节报文长度（包含本字段4字节）Header可变报文头，tars格式二进制数据Payload可变消息体，tars格式二进制数据struct OTIMPack
{
0 require OTIMHeader header;
1 require vector
};
报头 Header
每个OMTP控制报文都包含一个报头。
格式
字段类型长度说明typeshort2字节报文的类型versionshort2字节协议版本号flagslong4-8字节详见下文flags说明packIdstring可变长度报文Id，建议为UUIDstruct OTIMHeader
{
0 require short type;
1 require short version;
2 require long flags;
3 require string packId;
};
flags说明
含义长度说明ACK1 bit是否为请求响应，0:请求,1:响应；DUP1 bit是否重发，0:不重复，1:重复COUNTER1 bit是否计数，0:不计，1:计数OVERRIDE1 bit是否覆写，0:正常,1:覆写REVOKE1 bit是否撤回，0:正常,1:撤回HIGHPRJ1 bit高优先级，0:正常,1:高优先级COMPRESS3 bits压缩算法，00:无压缩，01:zlibCRYPTO3 bits加密算法，00:无加密，01:AESRESERVED13-51 bits保留
//ACK|DUP|COUNTER|OVERRIDE|REVOKE|HIGHPRJ|COMPRESS|CRYPTO|RESERVED
struct PT_FLAGS_BITS{
unsigned int ack:1;
unsigned int dup:1;
unsigned int counter:1;
unsigned int overwrite:1;
unsigned int revoke:1;
unsigned int highPRJ:1;
unsigned int compress:3;
unsigned int crypto:3;
unsigned int reserved:20;
};
报文类型
enum PACK_TYPE
{
PT_NONE = 0, //00-09 保留
PT_PING = 10, //心跳
PT_LOGIN = 11, //登录认证
PT_LOGOUT = 12, //登出
PT_KICKOUT = 13, //踢出
PT_MSG_SINGLE_CHAT = 14,//单聊消息
PT_MSG_GROUP_CHAT = 15,//群聊消息
PT_MSG_BIZ_NOTIFY = 16,//业务通知消息
PT_MSG_CTRL = 17, //消息控制指令（比如撤销，删除等）
PT_MSG_READ = 18, //消息已读
PT_HOTSESSION_SYNC = 19, //热会话同步
PT_HIGH_PRIOR_MSG_SYNC = 20, //高优先级消息同步
PT_HISTORY_MSG_PULL = 21, //拉历史消息
PT_SESSION_MONITOR_START = 22,//监控会话开始
PT_SESSION_MONITOR_STOP = 23,//监控会话结束
PT_SESSION_MONITOR_SYNC = 24, //监控会话同步（同步登陆用户的会话）
PT_SYNC_DATA_CMD = 25, //同步数据指令,根据该指令可以客户端可以进行各种增量数据同步（比如会话，好友记录，群聊等）
PT_GROUPCHAT_SYNC = 40, //同步我的群(我创建，加入，监听的群里)
PT_GROUPCHAT_CREATE = 41, //创建群聊
PT_GROUPCHAT_JION = 42, //加入群聊
PT_GROUPCHAT_QUIT = 43, //退出群聊
PT_GROUPCHAT_DISMISS = 44, //解散群聊
PT_GROUPCHAT_UPDATE_CREATOR = 45, //换群主
PT_GROUPCHAT_INFO_UPDATE = 46, //更新群资料
PT_GROUPCHAT_MEMBERS_GET = 47, //获取群成员
PT_FRIEND_ADD = 51, //添加好友
PT_FRIEND_DEL = 52, //删除好友
PT_FRIEND_SYNC = 53, //同步好友
PT_USERINFO_GET = 54, //获取用户信息
PT_USERINFO_UPDATE = 55, //用户信息更新
PT_USERATTRIBUTE_SET = 56, //设置用户属性，比如昵称
PT_USERATTRIBUTE_GET = 57, //获取用户属性，比如昵称
PT_SESSIONATTRIBUTE_SET = 58, //设置会话属性，比如置顶，免打扰
};
报文体Payload
根据不同type（报文类型），Payload内容不同；
根据不同的format，采用不同传输数据格式；
报文包含的内容信息及简单流程详见下文。
报文类型详细说明
PT_PING 心跳
报文类型值：10flags ACK位: 0Payload：无
PT_LOGIN 登录请求
报文类型：11flags ACK位: 0Payload：LoginReq
字段名称类型说明clientIdstring用户名usernamestring用户名passwordstring密码devicetypeDEVICE_TYPE设备类型：1：ios，2：android，3：windows PC,4:Mac OSdeviceNamestring设备名称deviceIdstring设备idversionstringapp版本号，如：“3.2.1”enum DEVICE_TYPE
{
DEVICE_NONE = 0,
DEVICE_IOS = 1,
DEVICE_ANDROID = 2,
DEVICE_MACOS = 3,
DEVICE_WINDOWS = 4,
DEVICE_LINUX = 5,
};
/* 登录请求 */
struct LoginReq
{
0 require string clientId ; //用户UserId
1 require string userName ; //登录名（手机号）
2 optional string password ; //密码,token（如：a502c991-9ab9-4823-bde9-520d9169545b）
3 optional DEVICE_TYPE deviceType; //设备类型：1：ios，2：android，3：windows PC,4:Mac OS 5:Linux
4 optional string deviceName; //设备名称
5 optional string deviceId; //设备唯一标识
6 optional string version; //客户端的版本号
};
PT_LOGIN 登录响应
报文类型值：11flags ACK位: 1Payload：LoginResp
字段名称类型说明codeint登录返回码descstring错误原因struct LoginResp
{
0 require int code; //认证结果码值
1 optional string clientId;
2 optional string extraData;
};
PT_LOGOUT 登出
报文类型：12flags ACK位: 0Payload：无
PT_LOGOUT 登出响应
报文类型：12flags ACK位: 1Payload：无
PT_KICKOUT 踢出
报文类型：13flags ACK位: 0Payload：KickOutReq
struct KickOutReq
{
0 require int deviceType; //准备要踢掉的 deviceType
1 require string deviceId; //准备要踢掉的 设备类型deviceId，
};
PT_KICKOUT 踢出响应
报文类型：13flags ACK位: 1Payload：无
PT_MSG_SINGLE_CHAT 单聊消息
报文类型：14flags ACK位: 0Payload：MsgReq
字段名称类型说明seqidlong序列号，排序用，服务端产生timestamplong时间戳sessionidstring会话id，发送方根据约定规则填写，具体规则后文详述fromstring发送者：用户idtostring接收者：用户idstatusint消息状态，0:正常，1:撤回，2:删除contentTypeint消息内容类型：1：文本， 2：语音，3：图片，5：位置，6:视频, 7：文件 8：富媒体contentFormat（header里面定义格式）根据contentType，有不同字段，下文详细说明struct MsgReq
{
0 require string sessionId; //会话Id
1 optional long seqId ; //由服务器端填写,客户端用来排序.
2 optional long timestamp ; //消息时间,由服务器端来填写.用来在客户端显示
3 require string from ; //消息发送者的名片Id或appid
4 require string to ; //消息接收者的名片Id或者群组Id
5 optional string pushInfo ; //推送信息IOS-Push用,此字段无值表示不需要push
6 optional int contentType ; //content 类型，文本，语音，图片等等
7 optional string content ; //内容可为:pb/json/text
8 optional int status ; //消息状态 0:正常,1:删除,2:撤销
};
PT_MSG_SINGLE_CHAT 单聊消息响应
报文类型：14flags ACK位: 1Payload：MsgAck
字段名称类型说明codeint返回值sessionIdstring会话Idseqidlong序列号，排序用，服务端产生timestamplong时间戳struct MsgAck
{
0 require int code;
1 require string sessionId;
2 require long seqId;
3 require long timestamp; //消息类型
};
PT_MSG_GROUP_CHAT 群聊消息
报文类型：15flags ACK位: 0Payload：MsgReq（同单聊）
字段名称类型说明seqidlong序列号，排序用，服务端产生timestamplong时间戳sessionidstring会话id，发送方根据约定规则填写，具体规则后文详述fromstring发送者tostring接收者：群地址statusint消息状态，0:正常，1:撤回，2:删除contentTypeint消息内容类型：1：文本， 2：语音，3：图片，5：位置，6:视频, 7：文件 8：富媒体contentFormat（header里面定义格式）根据contentType，有不同字段，下文详细说明PT_MSG_GROUP_CHAT 群聊消息响应
报文类型：15flags ACK位: 1Payload：MsgAck(同单聊）
字段名称类型说明seqidlong序列号，排序用，服务端产生timestamplong时间戳codeint返回值PT_MSG_BIZ_NOTIFY 业务通知消息请求
报文类型：16flags ACK位: 0Payload：MsgReq（同单聊）
注：此条指令仅仅通知客户端出发相应同步，不做数据传输。
PT_MSG_BIZ_NOTIFY 业务通知消息响应
报文类型：16flags ACK位: 1Payload：MsgAck(同单聊）
PT_SYNC_DATA_CMD
字段名称类型说明cmdlong同步业务指令PT_MSG_CTRL 消息控制（比如撤销，删除等）
报文类型：17flags ACK位: 0Payload：MsgControl
字段名称类型说明commandint1.撤销，2.删除sessionIdstring会话IdpackIdstring目标消息packIdstruct MsgControl
{
0 require int command ; //1.撤销，2.删除
1 require string sessionId ; //会话Id
2 require string packId ; //目标消息packId
3 require long seqId ; //目标消息seqId
};
PT_MSG_CTRL 消息控制响应
报文类型：17flags ACK位: 1Payload：CommonResp
字段名称类型说明codeint错误码descstring错误信息struct CommonResp
{
0 require int code ; //错误码
1 require string desc ; //错误信息
};
PT_MSG_READ 消息已读
报文类型：18flags ACK位: 0Payload:MsgReaded
字段名称类型说明sessionIdstring会话IdseqIdlong起始seqIdstruct MsgReaded
{
0 require string sessionId ; //会话Id
1 require long seqId ; //已读消息seqId
};
PT_MSG_READ 消息已读响应
报文类型：18flags ACK位: 1Payload:CommonResp
PT_HOTSESSION_SYNC 热会话同步请求
报文类型：19flags ACK位: 0Payload:HotSessionReq
字段名称类型说明timestamplong时间戳struct HotSessionReq
{
0 require long timestamp ; //单位微秒，本地拉取会话时间戳或者断点时间戳
};
PT_HOTSESSION_SYNC热会话同步响应
报文类型：19flags ACK位: 1Payload：HotSessionResp
字段名称类型说明codeint返回码timestamplong时间戳sessionsVector热会话列表HotSessionItem
字段名称类型说明sessionIdstring会话idreadSeqIdlong已读seqIdunreadCountInt未读数lastMsgsVector最新n条消息struct HotSessionItem
{
0 require string sessionId; // 会话Id
1 require long readSeqId; //会话已读游标
2 require int unreadCount = 0; //某会话未读数，默认值0
3 optional vector
4 optional string attribute; //会话属性集
};
struct HotSessionResp
{
0 require int code = 0; //返回码 类型
1 require long timestamp ;
2 require vector
};
PT_HIGH_PRIOR_MSG_SYNC 高优先级消息同步请求
报文类型：20flags ACK位: 0Payload: MsgHighPrioritySyncReq
字段名称类型说明seqIdlong当前最新seqIdcountint获取数量struct MsgHighPrioritySyncReq
{
0 require long seqId;
1 require int count = 200;//获取数量
};
PT_PRIOR_MSG_SYNC 高优先级消息同步响应
报文类型：20flags ACK位: 1Payload:MsgGetHighPriorityResp
字段名称类型说明codeint错误码descstring错误描述lastSeqIdlong最新seqIdmsgsvector消息struct MsgHighPrioritySyncResp
{
0 require int code; //服务请求的结果码
1 optional string desc; //服务请求的结果描述
2 require long lastSeqId;
3 optional vector
};
PT_HISTORY_MSG_PULL 历史消息请求
报文类型：21flags ACK位: 0Payload
字段名称类型说明sessionIdstring会话idseqIdlong起始seqidcountint消息数量struct HistoryMsgPullReq
{
0 optional string sessionId;
1 require long seqId; //起始seqId
2 require int count = 200;//获取数量
};
PT_HISTORY_MSG_PULL 历史消息响应
报文类型：21flags ACK位: 1Payload：HistoryMsgPullResp
字段名称类型说明errorCodeCommonErrorCode错误信息sessionIdstring会话idmsgsvector消息内容struct HistoryMsgPullResp
{
0 require CommonErrorCode errorCode;
1 require string sessionId; //起始sessionId
2 require vector
};
PT_SESSION_MONITOR_START 监控会话开始请求
报文类型：22flags ACK位: 0Payload:SessionMonitor
字段名称类型说明sessionIdstring会话idstruct SessionMonitor
{
0 require string sessionId;
};
PT_SESSION_MONITOR_START 监控会话开始响应
报文类型：22flags ACK位: 1Payload:CommonErrorCode
PT_SESSION_MONITOR_STOP 监控会话开始请求
报文类型：23flags ACK位: 0Payload:SessionMonitor
字段名称类型说明sessionIdstring会话idstruct SessionMonitor
{
0 require string sessionId;
};
PT_SESSION_MONITOR_STOP 监控会话开始响应
报文类型：23flags ACK位: 1Payload:CommonErrorCode
PT_SESSION_MONITOR_SYNC 监听会话同步请求
报文类型：24flags ACK位: 0Payload：无
PT_SESSION_MONITOR_SYNC 监听会话同步响应
报文类型：24flags ACK位: 1Payload：HotSessionResp
PT_SYNC_DATA_CMD 同步数据指令
报文类型：25flags ACK位: 1Payload:SyncDataReq
字段名称类型说明commandint业务类型 1,好友列表，2，会话，3，群聊contentstring业务数据struct SyncDataReq
{
0 require int command;
1 require string content;
};
PT_SYNC_DATA_CMD 同步数据指令响应
报文类型：25flags ACK位: 1Payload：CommonErrorCode
PT_GROUPCHAT_SYNC 群聊同步请求
报文类型：40flags ACK位: 0Payload:SyncGroupChatReq
字段名称类型说明timestamplong同步时间戳struct GroupChatSyncReq
{
0 require long timestamp;
};
PT_GROUPCHAT_SYNC 群聊同步响应
报文类型：40flags ACK位: 1Payload：GroupChatSyncResp
字段名称类型说明errorCodeCommonErrorCode错误信息timestamplong同步时间戳groupchatsvectorGroupChatInfo 群聊列表struct GroupChatInfo
{
0 require string groupId; // 班级群groupid由classid和classcode组合生成
1 require string name; // 群聊名字
2 optional string avatar; // 群聊头像
3 require string creatorId; // 群聊创建者，即群主userId
4 optional string desc; // 群聊描述
5 optional int memberLimit; // 最大成员数
6 optional long createTime; // 创建时间
7 optional long updateTime; // 更新时间
};
struct GroupChatSyncResp
{
0 require CommonErrorCode errorCode;
1 require long timestamp;
2 require vector
3 require vector
};
PT_GROUPCHAT_CREATE 群聊创建请求
报文类型：41flags ACK位: 0Payload:GroupChatCreateReq
struct GroupChatCreateReq
{
0 require GroupChatInfo groupInfo;
1 require vector
};
PT_GROUPCHAT_CREATE 群聊创建响应
报文类型：41flags ACK位: 1Payload:GroupChatCreateResp
字段名称类型说明errorCodeCommonErrorCodegroupIdstringstruct GroupChatCreateResp
{
0 require CommonErrorCode errorCode;
1 require string groupId;
};
PT_GROUPCHAT_JION 加入群聊请求
报文类型：42flags ACK位: 0Payload:GroupChatJoinReq
字段名称类型说明groupIdstringmemberIdsvectoruserId列表struct GroupChatJoinReq
{
0 require string groupId;
1 require vector
};
PT_GROUPCHAT_JION 加入群聊响应
报文类型：42flags ACK位: 1Payload:GroupChatJoinResp
字段名称类型说明errorCodeCommonErrorCodegroupIdstringstruct GroupChatJoinResp
{
0 require CommonErrorCode errorCode;
1 require string groupId;
};
PT_GROUPCHAT_QUIT 退出群聊请求
报文类型：43flags ACK位: 0Payload:GroupChatQuitReq
字段名称类型说明groupIdstringoperatorIdstring操作者userIdmemberIdsvector退出的userId列表struct GroupChatQuitReq
{
0 require string groupId;
1 require string operatorId;
2 require vector
};
PT_GROUPCHAT_QUIT 退出群聊响应
报文类型：43flags ACK位: 1Payload:CommonErrorCode
PT_GROUPCHAT_DISMISS 解散群聊请求
报文类型：44flags ACK位: 0Payload:GroupChatDismissReq
字段名称类型说明groupIdstringoperatorIdstring操纵者userIdmemberIdsvector退出的userId列表struct GroupChatDismissReq
{
0 require string groupId;
1 require string operatorId;
};
PT_GROUPCHAT_DISMISS 解散群聊响应
报文类型：44flags ACK位: 1Payload:CommonErrorCode
PT_GROUPCHAT_CREATOR_UPDATE 换群主请求
报文类型：45flags ACK位: 0Payload:GroupChatCreatorUpdateReq
字段名称类型说明groupIdstringoperatorIdstring操纵者userIdmemberIdsvector退出的userId列表struct GroupChatCreatorUpdateReq
{
0 require string groupId;
1 require string operatorId;
2 require string newCreatorId;
};
PT_GROUPCHAT_CREATOR_UPDATE 换群主响应
报文类型：45flags ACK位: 1Payload:CommonErrorCode
PT_GROUPCHAT_INFO_UPDATE 更新群资料请求
报文类型：46flags ACK位: 0Payload:GroupChatInfoUpdateReq
字段名称类型说明operatorIdstring操作者userIdgroupInfoGroupChatInfo群信息struct GroupChatInfoUpdateReq
{
0 require string operatorId;
1 require GroupChatInfo groupInfo;
};
PT_GROUPCHAT_INFO_UPDATE 更新群资料响应
报文类型：46flags ACK位: 1Payload:CommonErrorCode
PT_GROUPCHAT_MEMBER_GET 获取群成员请求
报文类型：47flags ACK位: 0Payload:GroupChatMemberGetReq
字段名称类型说明groupIdstring群Idstruct GroupChatMemberGetReq
{
0 require string groupId;
};
PT_GROUPCHAT_MEMBER_GET 获取群成员响应
报文类型：47flags ACK位: 1Payload:GroupChatMemberGetResp
字段名称类型说明errorCodeCommonErrorCodegroupIdstring群IdmemberIdsvector群成员userId列表struct GroupChatMemberGetResp
{
0 require CommonErrorCode errorCode;
1 require string groupId;
2 require vector
};
PT_FRIEND_ADD 添加好友请求
报文类型：51flags ACK位: 0Payload:FriendAddReq
字段名称类型说明friendsvector好友FriendInfo列表struct FriendInfo
{
0 require string userId;
1 require string friendId;
2 require string remark;//备注名
};
struct FriendAddReq
{
0 require vector
};
PT_FRIEND_ADD 添加好友响应
报文类型：51flags ACK位: 1Payload:CommonErrorCode
PT_FRIEND_DEL 删除好友请求
报文类型：52flags ACK位: 0Payload:FriendDelReq
字段名称类型说明friendsvector好友FriendInfo列表struct FriendDelReq
{
0 require vector
};
PT_FRIEND_DEL 删除好友响应
报文类型：52flags ACK位: 1Payload:CommonErrorCode
PT_FRIEND_SYNC 同步好友请求
报文类型：53flags ACK位: 0Payload:FriendDelReq
字段名称类型说明timestamplong增量时间戳struct FriendSyncReq
{
0 require long timestamp;
};
PT_FRIEND_SYNC 同步好友响应
报文类型：53flags ACK位: 1Payload:FriendSyncResp
struct FriendSyncResp
{
0 require CommonErrorCode errorCode;
1 require vector
};
PT_USERINFO_GET 获取用户资料请求
报文类型：54flags ACK位: 0Payload:UserInfoGetReq
字段名称类型说明userIdsvector用户id列表struct UserInfoGetReq
{
0 require vector
};
PT_USERINFO_GET 获取用户资料响应
报文类型：54flags ACK位: 1Payload:UserInfoGetResp
字段名称类型说明errorCodeCommonErrorCodeuserInfosvectorUserInfo 列表struct UserInfoGetResp
{
0 require CommonErrorCode errorCode;
1 require vector
};
struct UserInfo
{
0 require string userId;
1 require string name;
2 require string avator;
3 require string mobile;
4 require long birthday;//timestamp
};
PT_USERINFO_UPDATE 更新用户资料请求
报文类型：55flags ACK位: 0Payload:UserInfoUpdateReq
字段名称类型说明userInfoUserInfo用户资料struct UserInfoUpdateReq
{
0 require UserInfo userInfo;
};
PT_USERINFO_UPDATE 更新用户资料响应
报文类型：55flags ACK位: 1Payload:CommonErrorCode
PT_USERATTRIBUTE_SET 设置用户属性，比如昵称
报文类型：56flags ACK位: 0Payload:UserAttrSetReq
字段名称类型说明attributeUserAttribute属性UserAttributestruct UserAttribute
{
0 require string userId;
1 require string friendId;
2 require string attrName;
3 require string attrValue;
};
struct UserAttrSetReq
{
0 require UserAttribute attribute;
};
PT_USERATTRIBUTE_SET 设置用户属性响应
报文类型：56flags ACK位: 1Payload:CommonErrorCode
PT_USERATTRIBUTE_GET 获取用户属性请求
报文类型：57flags ACK位: 0Payload:无
PT_USERATTRIBUTE_GET 获取用户属性响应
报文类型：57flags ACK位: 1Payload:UserAttrGetResp
struct UserAttrGetResp
{
0 require CommonErrorCode errorCode;
1 require vector
};
PT_SESSIONATTRIBUTE_SET 设置会话属性，比如置顶，免打扰
报文类型：58flags ACK位: 0Payload:SessionAttrSetReq
字段名称类型说明userIdstringsessionIdstringattrNamestring属性名attrValuestring属性值struct SessionAttrSetReq
{
0 require string userId;
1 require string sessionId;
2 require string attrName;
3 require string attrValue;
};
PT_SESSIONATTRIBUTE_SET 更新会话属性响应
报文类型：58flags ACK位: 1Payload:CommonErrorCode