WebSocket接口

本接口主要用来接收和推送用户消息，消息格式均为JSON

地址为

ws://api.bandoristation.com 或 wss://api.bandoristation.com

WebSocket API需要客户端发送心跳包维持连接，心跳包内容可以是Heartbeat Action或者其他任意数据，心跳包发送间隔为30秒。Heartbeat Action格式如下

{
  "action":"heartbeat",
  "data":{
    "client":""  //此处填写客户端名
  }
}

一个命令为一个Action，一次请求可以包含多个Action，每个Action依次执行。请求消息结构如下

// 单个Action请求
{
  "action":"actionName",
  "data":{
    "key":"value"
  }
}

// 多个Action请求
[
  {
    "action":"action1",
    "data":{
      "key":"value"
    }
  },
  {
    "action":"action2",
    "data":{
      "key":"value"
    }
  }
]

由于WebSocket的特性，请求和响应并不像HTTP那样一一对应的，所以在返回数据中也带有action字段，结构如下

{
  "status":"success/failure",
  "action":"actionName",
  "response":{}
}

当“status”字段为“failure”时，返回数据为提示消息

字段名	数据类型	说明
status	string	failure
action	string	sendNotice
response	string	消息内容

以下说明中的返回数据“status”字段值均为“success”，“failure”情况不再另行说明

目录

• 推送消息
• 设置客户端
• 获取服务器时间
• 获取房间号列表
• 设置访问权限
• 发送房间号
• 初始化聊天室
• 发送聊天消息
• 加载聊天记录

推送消息

※必须在设置客户端之后服务端才会推送消息，设置方法见设置客户端

房间号消息

字段名	数据类型	说明
status	string	success
action	string	sendRoomNumberList
response	array	内部数据格式请参阅《API接口》中“查询房间数据”相关说明

聊天消息

字段名	数据类型	说明
status	string	success
action	string	sendChat
response	array

response中的单条数据

字段名	数据类型	说明
timestamp	number	消息发送时间，13位时间戳
content	string	消息内容
user_info	object	用户信息

user_info

字段名	数据类型	说明
user_id	number	用户ID
username	string	用户名
avatar	string	用户头像文件名，头像文件可以从地址 https://assets.bandoristation.com/images/user-avatar/{avatar} 获取

设置客户端

不同于第一版的WS接口，新版WS接口必须设置客户端之后服务端才会推送数据

参数

字段名	数据类型	填入值	说明
action	string	setClient
data	object

data

字段名	数据类型	填入值	说明
client	string	客户端名称	选填
send_room_number	boolean		设置是否推送房间号消息
send_chat	boolean		设置是否推送聊天消息

返回数据

无

获取服务器时间

用来计算服务器时间和本地时间偏差值，WebSocket连接成功时会自动发送一次服务器时间

参数

字段名	数据类型	填入值	说明
action	string	getServerTime
data	null	null

返回数据

字段名	数据类型	说明
status	string	success
action	string	sendServerTime
response	object

response

字段名	数据类型	说明
time	number	13位时间戳

获取房间号列表

参数

字段名	数据类型	填入值	说明
action	string	getRoomNumberList
data	null	null

返回数据

字段名	数据类型	说明
status	string	success
action	string	sendRoomNumberList
response	array	内部数据格式请参阅《API接口》中“查询房间数据”相关说明

设置访问权限

设置WebSocket接口访问权限

参数

字段名	数据类型	填入值	说明
action	string	setAccessPermission
data	object

data

字段名	数据类型	填入值	说明
token	string	用户访问Token	在Server接口登陆后获取

返回数据

无

发送房间号

※需要先设置访问权限

参数

字段名	数据类型	填入值	说明
action	string	sendRoomNumber
data	object

data

字段名	数据类型	填入值	说明
room_number	string	房间号
description	string	房间号描述

返回数据

无

初始化聊天室

※需要先设置访问权限

参数

字段名	数据类型	填入值	说明
action	string	sendRoomNumber
data	null	null

返回数据

字段名	数据类型	说明
status	string	success
action	string	initializeChatRoom
response	object

response

字段名	数据类型	说明
message_list	array	消息数组，格式与推送消息中的聊天消息一致
self_id	number	当前访问接口的用户ID
is_end	boolean	消息列表是否加载完全*

*一次只会加载40条消息（缓存中的消息会被完全加载，消息可能会大于40条），剩余的消息将会分段加载。“is_end”为false表明还有聊天记录没被加载

发送聊天消息

※需要先设置访问权限

参数

字段名	数据类型	填入值	说明
action	string	sendChat
data	object

data

字段名	数据类型	填入值	说明
message	string	聊天消息

返回数据

无

加载聊天记录

※需要先设置访问权限

参数

字段名	数据类型	填入值	说明
action	string	loadChatLog
data	object

data

字段名	数据类型	填入值	说明
timestamp	number	已加载的最早一条消息的发送时间，13为时间戳

返回数据

字段名	数据类型	说明
status	string	success
action	string	loadChatLog
response	object

response

字段名	数据类型	说明
message_list	array	消息数组，格式与推送消息中的聊天消息一致
is_end	boolean	消息列表是否加载完全