0x00 名词解释:

{}里的表示变量
xnest表示一个聊天室
xnest_id表示该聊天室的id.(用户可以自己取, 最好不超过32个字符)
连接地址:
ws://meet.xpro.im:8080/xgate/websocket/{$xnest_id}?nickname={$nickname}&is_store_history={true}

$xnest_id: 代表聊天室的唯一标识 $nickname: 进入聊天室的昵称(进入一次后, 服务器会把该昵称写入到cookie, 下次不带昵称会默认是用cookie里的, 如果cookie和参数都没有, 服务器会默认使用一个随机的昵称) isstorehistory: 是否存储历史聊天记录, 取值true(存, 默认值) 或者false(不存)


0x01 客户端(如js)连接:

客户端通过websocket连接服务器
连接成功后:服务器会推送一些该聊天室的数据过来
格式为json文本,如下:

{  
    "from":"{$sender_id}",  
    "xnest":"{$xnest_id}",  
    "type":"{$type}",  
    "payload":"{$payload}",  
    "send_time":"{$time}"  
}

服务按如下次序推送消息过来:

1.接收自己在该聊天室的唯一id

类型为:self, 有效内容为自己的id.
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",  
    "type":"self",  
    "payload":"<0.31891.2>",  
    "send_time":"2015-4-8 14:2:6"  
}

2.接收该聊天室的成员数量

类型为:member_count,有效内容为1, 及表示当前成员数量为1
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"member_count",
    "payload":1,
    "send_time":"2015-4-8 14:2:6"
}

3.接收成员列表

类型为:members, 内容为json数组, 包含当前所有聊天室成员的pid和nickname
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"members",
    "payload":[{"pid":"<0.31891.2>","nickname":"小明"}],
    "send_time":"2015-4-8 14:2:6"
}

4.接收该聊天室的历史记录, 目前只会保留一定数量的记录

类型为:history,有效内容为第一层的payload, 格式是个列表, 每条记录包含发送者id, 内容和时间 , 还有该条消息的类型 例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"history",
    "payload":[
        {"from":"<0.1897.0>","payload":" 12121435131197391", "type":"text", "send_time":"2015-06-24"},
        {"from":"<0.1897.0>","payload":" http://meet.xpro.im/123242112312", "type":"audio", "send_time":"2015-06-24"}, 
        {"from":"<0.1897.0>","payload":" 大大的1435131192974", "type":"text", "send_time":"2015-06-24"}, 
        {"from":"<0.1897.0>","payload":"爱上对方1435131191173", "type":"text", "send_time":"2015-06-24"}],
    "send_time":"2015-4-8 14:2:6"
}

0x02 连接建立成功后

连接保持期间, 如果有新加入的成员进来, 老成员离开 , 消息接收, 服务端都会推送一条消息给客户端,如下:

1.接收新近成员消息(当有新成员加入聊天室时)

类型为:join, payload为该加入成员的昵称, 加入成员的id在from字段里.
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"join",
    "payload":"黑旋风李逵",
    "send_time":"2015-4-8 14:2:6"
}

2. 接收离开成员消息(当有其他成员离开聊天室时候)

类型为:leave,payload为固定的leave. 离开成员的id在from字段里.
例子:

{
    "from":"<0.31916.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"leave",
    "payload":"leave",
    "send_time":"2015-4-8 14:23:28"
}

3. 普通消息的发送(这里就直接发送消息体就可以了, 没有格式.)

比如我发送了: 大家好!
js客户端可能是如下代码:

ws.send("大家好");

4. 普通消息接收(及其他成员发送的消息)

类型为:normal, payload就是成员发送的消息.如上例,payload里就是大家好.from就是发送者的id.
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"normal",
    "payload":"大家好",
    "send_time":
    "2015-4-8 14:25:30"
}

5. 私聊消息的发送与接收

在一个聊天室里如果想单独发送信息给某位成员可以通过指令

@to:$pid|$msg  

的格式发送 比如:

@to:<0.31891.2>|今天你吃饭了吗?

对应的pid(<0.31891.2>)用户就会收到一条如下的private类型的消息:
类型为: private

{
    "from":"<0.31890.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"private",
    "payload":"今天你吃饭了吗?",
    "send_time":"2015-4-8 14:2:6"
}

6. 语音消息的发送与接收

语音消息是通过二进制的方式发送的, 在发送语音内容之前, 需要先发送一个字节(8位)的数字1,在紧接着发送语音

二进制的语音消息被服务端接收后会转换成文本类消息, 同时类型会变成audio类型 有效的消息payload为一个url地址, 客户端可通过点击url等手段去播放语音消息

{
    "from":"<0.31890.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"audio",
    "payload":"http://meet.xpro.im:8080/14009e12d791e664fc0175aecb31d833/1452482123561863",
    "send_time":"2015-4-8 14:2:6"
}

7. 图片消息的发送与接收

图片消息也是通过二进制的方式发送的, 在发送图片内容之前, 需要先发送一个字节(8位)的数字2,在紧接着发送图片

二进制的图片消息被服务端接收后会转换成文本类消息, 同时类型会变成picture类型 有效的消息payload为一个url地址, 客户端可通过再次发起一个http请求来显示图片

{
    "from":"<0.31890.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"picture",
    "payload":"http://meet.xpro.im:8080/14009e12d791e664fc0175aecb31d833/1452482123561863",
    "send_time":"2015-4-8 14:2:6"
}

8. 用户昵称改变昵称

用户可发送 @changename:新昵称 来修改自己的昵称.发送后服务器会广播消息到所有用户 类型为:changename, payload成员修改后的昵称, 该成员的id在from字段里.
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"changename",
    "payload":"黑旋风李逵",
    "send_time":"2015-4-8 14:2:6"
}

9. 用户获取更多历史聊天记录

用户可发送 @history:$cursor 来获取聊天记录, 服务器收到后会以消息方式回应客户端以history为type的信息.
ps: $cursor为数字,从0开始, 比如发送: @history:0 即表示获取最近的聊天记录(通常游标cursor偏移量为50条);
在继续获取后面的记录, 可以发送 @history:1, 以此类推 @history:2
类型为:history, payload为这次获取的聊天记录, 该成员的id在from字段里.
例子:

{
    "from":"<0.31891.2>",
    "xnest":"f45c6d7720375d90f660a7b7e3ae11bf",
    "type":"history",
    "payload":[
        {"from":"<0.1897.0>","payload":" 12121435131197391","send_time":"2015-06-24"},
        {"from":"<0.1897.0>","payload":" 1111435131194487","send_time":"2015-06-24"}, 
        {"from":"<0.1897.0>","payload":" 大大的1435131192974","send_time":"2015-06-24"}, 
        {"from":"<0.1897.0>","payload":"爱上对方1435131191173","send_time":"2015-06-24"}],
    "send_time":"2015-4-8 14:2:6"
}

0x03 js示例

js样例


0x04 ChangeLog