客户端 RESTful 相关接口

客户端 RESTful 接口提供拉取离线消息、获取消息服务器信息、文件上传下载、更新推送Token、设置免打扰等接口服务。

服务端 API 调用签名规则

客户端 REST 接口请求需要认证用的sessionID信息需要通过HTTP请求头传给服务端,请求头名称:client-session

客户端每次请求 API 接口时,均需要提供以下 HTTP Request Header,具体如下:

参数 解释 是否必须 例子
client-session: #{sessionID} 创建帐号时返回的用户SessionID client-session = 14f9e5a0bb14454bb32d5c1508be
app-id: #{appId} 应用的AppId app-id = 200013

拉取用户的离线消息

  • 请求URL : /api/user/message/msg_snap
  • 请求方式 : GET
  • 请求参数
    • last_message_id(必填): 最后拉取消息的ID 初次可以填0;第二次拉取时设置为前一次拉取的消息 ID 最大值;
    • length(可选): 读取条数 默认20条,最多100条;
  • 响应
{
    "error_code":401,
    "error": "账户未登陆"
}
{
   "messages": [
    {
        "id": 67,
        "content": "你好",
        "type": "TEXT",    //文本 图片 语音 系统
        "create_time": 1394617606389,
        "sender": "f9253f90a8e211e3882863fbf5d6fe5b",
        "receiver_type": "", //用户还是群组
        "conversation_id": "f9253f90a8e211e3882863fbf5d6fe5b",//会话ID
        "meta":{"entity_format":0,"cmsgid":"ffc820ab2ba24c1d9e257a6cebb0c7a30015"}
    },
    {
        "id": 67,
        "content": "你好",
        "type": "TEXT",    //文本 图片 语音 系统
        "create_time": 1394617606389,
        "sender": "f9253f90a8e211e3882863fbf5d6fe5b",
        "receiver_type": "", //用户还是群组
        "conversation_id": "f9253f90a8e211e3882863fbf5d6fe5b",//会话ID
        "meta":{"entity_format":0,"cmsgid":"ffc820ab2ba24c1d9e257a6cebb0c7a30016"}
    },
    {
        "id": 1015,
        "type": "SYSTEM_NOTIFY",
        "conversation_id": "88888888888888888888888888888888",
        "create_time": 1397184857620,
        "sender": "88888888888888888888888888888888",
        "receiver_type": 1,
        "receiver": "92ba8e90c12411e3a72763fbf5d6fe5b",
        "secret": 0,
        "content": "eyJ0eXBlIjoidXNlcl9yZWdpc3RlciIsImluZm8iOnsidXNlQ=="
        "meta":{"entity_format":0,"cmsgid":"ffc820ab2ba24c1d9e257a6cebb0c7a30017"}
    },
    {
        "id" : 5891460084483379200,
        "type" : "VIDEO_CALL",
        "conversation_id" : "e763ac40d03511e3bbf113abbfd80b2e",
        "create_time" : 1404633542178,
        "sender" : "e763ac40d03511e3bbf113abbfd80b2e",
        "receiver_type" : 1,
        "receiver" : "d663f1e0d04211e3a25f13abbfd80b2e",
        "secret" : 0,
        "content" : "",
        "room_id":"call_4627f67cfb33491b93d0e30a7624627f67cfb33491b93d0e30a762c2fb5"
    },
    {
        "id" : 5891880836961554432,
        "type" : "AUDIO_CALL",
        "conversation_id" : "0ddc4310d08a11e39bc3abf93b119073",
        "create_time" : 1404733857385,
        "sender" : "0ddc4310d08a11e39bc3abf93b119073",
        "receiver_type" : 1,
        "receiver" : "2cdfcdf0d11511e39bc3abf93b119073",
        "secret" : 0,
        "content" : "",
        "room_id":"call_4627f67cfb33491b93d0e30a7624627f67cfb334111193d0e30a762c2fb"
      }
    ]
}

meta字段对消息附加属性的说明 entity_format 0: 表示普通的消息 1:表示富媒体消息 cmsgid:表示客户端生成的消息唯一标示

获取可用的TCP服务器、文件服务器

  • 请求URL : /api/server/addr
  • 请求方式 : GET
  • 请求参数 : 无
  • 响应
{
    "error_code":401,
    "error": "账户未登陆"
}
{
    "tcp_server": [
        "192.168.1.232:7000",
        "192.168.1.233:7000"
    ],
    "file_server": [
        "https://api.chatgame.me",
        "https://apicn.chatgame.me"
    ]
}

根据用户ip获取地理位置

  • 请求URL : /api/user/location
  • 请求方式 : GET
  • 请求参数 : 无
  • 响应
{
    "error_code":4001,
    "error": "非法参数"
}
{
    "error_code":4031,
    "error": "获取不到地理位置"
}
{
    "lat": 123.456,
    "lon": -123.456
}

设置免打扰

  • 请求URL : /api/user/disturb
  • 请求方式 : POST
  • 请求参数
    • disable(必填): 是否禁止打扰。yes 禁止打扰 no 不启动免打扰功能
    • time(可选):免打扰的时间端,例如10:00-02:20。如果不携带此参数,以服务器的设置时间段为准。
  • 响应
{
    "error_code":401,
    "error": "账户未登陆"
}
{
    "error_code": 2000
}

上传本地未读消息数量

  • 请求URL : /api/user/message/unread
  • 请求方式 : POST
  • 请求参数
    • unread(必填) 表示客户端本地所有的未读消息,整数,例如10。
  • 响应
{
    "error_code":401,
    "error": "账户未登陆"
}
{
    "error_code":4001,
    "error": "参数错误"
}
{
    "error_code": 2000
}

上传文件、语音

  • 请求URL : /api/file/upload
  • 请求方式 : POST
  • 请求参数
    • file(必填): 文件。
    • uploadType(可选): 所选择的桶,取值包括:avatar(适用于头像)或default(适用于一般图片、语音、视频等文件),默认default。
  • 响应
{
    "error_code":4022
    "error": "文件为空"
}
{
    "error_code":4023
    "error": "上传失败"
}
{
    "file_id":"xxxxxxxx-xxx-xx"
    "file_url":"http://cnd/xxxxxxxx-xxx-xx"
}

判断上传文件是否已存在

  • 请求URL : /api/file/exist
  • 请求方式 : GET
  • 请求参数
    • md5(必填): 文件内容MD5值,例如“BDF3BF1DA3405725BE763540D6601144”。
  • 响应
{
    "error_code":4001,
    "error": "缺少参数"
}
{
    "is_exist": 1,
    "file_url": "http://xxxxxxxx-xxx-xx",
    "error_code":2000
}
{
    "is_exist": 0,
    "error_code":2000
}

分片上传文件

  • 请求URL : /api/file/multipart/upload
  • 请求方式 : POST
  • 请求参数
    • number(必填): 文件片的顺序标识,从1开始的正整数,由客户端生成。服务端最后组装文件时,按照number的顺序,从小到大进行组装。
    • upload_id(第一个文件片不填,其他必填):文件上传事务唯一标识,由服务器生成,在第一个文件片上传后,返回给客户端。上传该文件的其他分片时需要携带。
    • chunks(最后一个文件片必填,其他不填):文件分片的总数,由客户端生成,服务器收到chunks数目后,即认为所有文件分片都已上传成功,并尝试组装。
  • 响应
{
    "upload_id":"VXBsb2FkIElEIGZvciA2aWWpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA",
    "file_url":"http://cn.file.chatgame.me/api/file/download/2015/11/3/11/e7d3b28f-dfa2-4575-85fb-a11aadc2bf6a"
}
{
    "error_code":4210,
    "error":"upload_id不存在"
}
{
    "error_code":4211,
    "error":"文件块不存在" 
}

注意:分片上传需要在HTTP头部中指定x-transaction-id字段,同一个文件的x-transaction-id的值需要保证一致。服务端根据该字段值,将文件分片发送给同一个节点进行处理。

更新推送Token

  • 请求URL : /api/device/token
  • 请求方式 : POST
  • 请求参数
    • app_id(必填): 应用ID。
    • device_type(必填): 1为iPhone,2为android。
    • device_token(必填): 推送Token。
    • provider(必填): 服务提供商, 1:google,2:个推(安卓必选),3:iPhone private,4:iPhone enterprise,5:iPhone AppStore,6:华为,7:小米。
  • 响应
{
    "error_code":401,
    "error": "账户未登陆"
}
{
    "error_code":4001,
    "error": "缺少参数"
}
{
    "error_code": 2000
}