提示

时信魔方目前已支持与第三方即时通讯工具(例如:微信、飞书、钉钉等)的消息和数据互通,详情请参看 Cube Hub 服务。

如果您需要专业团队为您和您的企业订制全网互通的协作工具可以通过 cube#spap.com 或者 xujiangwei#spap.com (将“#”替换为“@”)邮箱联系我们。

Hub RESTful API


通道管理

启用通道

GET /hub/open/(channel_code)

启用指定通道码的通道。启用 Hub 通道时将登录指定的产品账号。

Parameters
  • channel_code (string) – 您申请的通道码。

Response Headers
Response JSON Object
  • product (string) – 产品名。

  • name (string) – 通道开启操作,例如 LoginQRCode

  • fileLabel (object) – 产品需要的登录二维码文件,参看 File Label

Status Codes

关闭通道

GET /hub/close/(channel_code)

关闭指定的通道。通道关闭时对应的账号将退出登录。

Parameters
  • channel_code (string) – 您申请的通道码。

Response Headers
Response JSON Object
  • product (string) – 产品名。

  • name (string) – 通道的关闭操作,例如 Logout

  • account (object) – 退出登录的账号信息,参看 Contact

Status Codes

下载文件数据

GET /hub/file/(channel_code)/(file_code)

下载指定文件码的文件数据。

Parameters
  • channel_code (string) – 您申请的通道码。

  • file_code (string) – 文件的文件码。

Response Headers
Status Codes
  • 403 Forbidden – 指定的文件码无效。

  • 404 Not Found – 服务器未能成功读取到指定文件码对应的文件数据。


上传文件数据

POST /hub/file/(channel_code)

上传文件数据到服务器,客户端需要按照 multipart/form-data 的 MIME 类型封装表单数据。 应答数据为 JSON 结构,参看 File Label

Parameters
  • channel_code (string) – 您申请的通道码。

Form Parameters
  • file – 文件名和文件数据。

Request Headers
Response Headers
Response JSON Object
  • fileCode (string) – 文件码。

  • fileName (string) – 文件名。

  • fileSize (string) – 文件大小。

Status Codes

账号数据操作

获取通道的账号信息

GET /hub/account/(channel_code)

获取指定通道已经登录的产品账号信息。应答数据格式参看 Account

Parameters
  • channel_code (string) – 您申请的通道码。

Response Headers
Response JSON Object
  • account (object) –

    账号数据,参看 Contact


获取通讯录数据

GET /hub/book/(channel_code)

获取指定通道账号的通讯录。应答数据格式参看 Contact Zone Event

Parameters
  • channel_code (string) – 您申请的通道码。

Query Parameters
  • begin – 查询数据的起始索引。默认值:0 。

  • end – 查询数据的结束索引。默认值:9 。

Response Headers
Response JSON Object
  • zone (object) – 携带通讯录数据的分区数据结构,参看 Contact Zone

  • begin (int) – 数据的起始索引。

  • end (int) – 数据的结束索引。

  • total (int) – 数据的总数。


获取群组信息

GET /hub/group/(channel_code)

获取指定群组的数据。应答数据格式参看 Group Data

Parameters
  • channel_code (string) – 您申请的通道码。

Query Parameters
  • name – 群组名称,必须使用 URL 编码形式。

Response Headers
Response JSON Object
  • group (object) – 群组数据,参看 Group


申请添加朋友

POST /hub/friend/add/(channel_code)

通过检索指定关键字申请添加联系人为朋友。

Parameters
  • channel_code (string) – 您申请的通道码。

Request Headers
Request JSON Object
  • keyword (string) – 指定联系人的外部 ID 或者手机号码。

  • postscript (string) – 指定申请附言, 可选参数

  • remarkName (string) – 指定添加的朋友备注名, 可选参数

Response Headers
Response JSON Object
  • code – 通道码。


消息会话操作

获取最近的消息会话列表

GET /hub/conversations/(channel_code)

获取指定通道的账号最近消息会话列表。应答数据格式参看 Conversations

Parameters
  • channel_code (string) – 您申请的通道码。

Query Parameters
  • nc – 查询会话的数量。默认值:8 。

  • nm – 查询的每个会话的最近消息数量。默认值:5 。

Response Headers
Response JSON Object
  • conversations (array) – 按照时间倒序存储的最近会话数组。


获取指定消息列表

GET /hub/messages/(channel_code)

获取指定会话的消息列表。应答数据格式参看 Messages

Parameters
  • channel_code (string) – 您申请的通道码。

Query Parameters
  • cid – 查询的联系人的外部 ID 。(与 gn 参数二选一)。

  • gn – 查询的群组名称 。(与 cid 参数二选一)。

  • begin – 查询列表的起始索引。默认值:0 。

  • end – 查询列表的结束索引。默认值:9 。

Response Headers
Response JSON Object
  • messages (array) – 按照时间序存储的消息列表。消息数据结构参看 Message


轮询最近消息列表

警告

  1. 该方法仅供采用 HTTP 协议的客户端使用。

  2. 该方法仅对最新的消息队列数据进行查询,不对会话的消息列表进行操作。

  3. 更短的轮询间隔并不能提高消息更新频率,消息更新频率由通道规则控制。

GET /hub/polling/(channel_code)

实时获取指定会话的最近消息。可以定时调用该接口获取最近的消息列表,最小调用间隔 200 ms

Parameters
  • channel_code (string) – 您申请的通道码。

Query Parameters
  • type – 指定会话类型,数值参考 Conversationtype 会话类型 字段。

  • name – 指定会话名称,群组会话则设置为群组名称,联系人会话则设置为联系人名称。

  • num – 指定查询的最大数量。默认值:5 。

Response Headers
Response JSON Object
  • conversationType (int) – 会话类型。

  • conversationName (string) – 会话名称。

  • messageList (array) –

    消息列表。消息数据结构参看 Message


发送消息

POST /hub/message/(channel_code)

发送消息数据到指定会话。

Parameters
  • channel_code (string) – 您申请的通道码。

Request Headers
Request JSON Object
  • groupName (string) – 指定消息发送的目标群组名。与 partnerId 参数二选一。

  • partnerId (string) – 指定消息发送的目标伙伴/好友的外部 ID 。与 groupName 参数二选一。

  • text (string) – 指定消息的文本内容,文本内容必须为 Base64 编码形式。

  • fileCode (string) – 指定文件消息的文件码。

Response Headers
Response JSON Object
  • code – 通道码。

请求示例

POST /hub/message/xdUrpSczEgWbSiDKmjhOWIOXZjQFOcmh HTTP/1.1
HOST: api.shixincube.com
Accept: application/json

{
    "partnerId": "heit9077_cube",
    "text": "5LuK5aSp5pivMjAyMuW5tDTmnIgxNeaXpQ=="
}