用户体系集成


数据结构

作为一个聊天通道,只需要提供谛听 ID 和密码就够了。

名称 字段名 数据类型 描述
谛听ID username String ID是用户的唯一标识,在APPKey范围内有效
用户密码 password String 用户登录使用的密码

名词解释


谛听ID规则

当 APP 和谛听集成的时候,需要把 APP 系统内的已有用户和新注册的用户和谛听集成,为每个已有用户创建一个谛听的账号(谛听 ID),并且 APP 有新用户注册的时候,需要同步的在谛听中注册。

在注册谛听账户的时候,需要注意谛听 ID 的规则:

  • 使用英文字母和(或)数字的组合
  • 不能使用中文
  • 不能使用 email 地址
  • 不能使用 UUID
  • 用户ID的长度在230字节以内
  • 中间不能有空格或者井号(#)等特殊字符
  • 允许的用户名正则 “[a-zA-Z0-9_-.]*”(a~z大小写字母/数字/下划线/横线/英文句号),其他都不允许 如果是大写字母会自动转成小写
  • 不区分大小写。系统忽略大小写,认为 AA、Aa、aa、aA 都是一样的。如果系统已经存在了环信 ID 为 AA 的用户,再试图使用 aa 作为谛听 ID 注册新用户,系统返回用户名重复,以此类推。但是请注意:谛听 ID 在数据上的表现形式还是用户最初注册的形式,注册时候使用的大写就保存大写,是小写就保存小写。即:使用 AA 注册,谛听保存的 ID 就是 AA;使用 Aa 注册,谛听保存的 ID 就是 Aa,以此类推。谛听用户名”两个术语,但是请注意,这里两个的意思是一样的。

获取APP管理员Token

谛听提供的 REST API 需要权限才能访问,权限通过发送 HTTP 请求时携带 token 来体现,下面描述获取 token 的方式。说明:API 描述的时候使用到的 {APP 的 client_id} 之类的这种参数需要替换成具体的值。

重要提醒:获取 token 时服务器会返回 token 有效期,具体值参考接口返回的 expires_in 字段值。由于网络延迟等原因,系统不保证 token 在此值表示的有效期内绝对有效,如果发现 token 使用异常请重新获取新的 token,比如 http response code 返回 401。另外,请不要频繁向服务器发送获取 token 的请求,同一账号发送此请求超过一定频率会被服务器封号,切记,切记!! 使用 APP 的 client_id 和 client_secret 获取授权管理员 token

client_id 和 client_secret 可以在谛听管理后台的 APP 详情页面看到。

  • Path: /token/{client_id}/{client_secret}
  • 方式: GET
  • 作用:api接口认证
  • 请求参数描述
参数名 IN 类型 必填 描述
client_id path String 唯一标识
client_secret path**** String 密钥
  • 响应参数说明
参数名 IN 类型 描述
success body ture 成功或失败
Code body int 状态码
Msg body String 异常信息
datas body String 返回数据
token body String Token
expiration body String Token有效截止时间
extraInfo body String 扩展信息
  • 成功示例
{
    "success": true,
    "code": 200,
    "msg": null,
    "datas": {
        "token": "bearer 0f74bdc8-59e7-49ca-8d36-69bdb62f4e3b",
        "expiration": "2018-09-28 02:55:51"
    },
    "extraInfo": null
}
  • 失败示例
{
    "success": false,
    "code": 10013,
    "msg": "clientId 或clientSecret无效",
    "datas": null,
    "extraInfo": null
}

IM用户管理


注册IM用户[单个]

  • Path: /api/v1/users/create
  • 方式: POST
  • 作用:单个注册
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
password body String 密码
name body String 昵称
  • 响应参数说明

外层参数

Name IN Type Description
success body String true/false
code body int 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

datas内部参数

Name IN Type Description
username body String 用户名
nickname body int 昵称
creationDate body String 创建时间
modificationDate body String 更新时间
activated body Boolean 账号状态
status body String 请求状态
  • 成功示例
{
  "success": true,
  "code": 200,
  "msg": null,
  "datas":{
           "createUserVO":
             {
               "username":"1234",
                "nicakname":"1234",
                "creationDate":"1537252561286",
                "modificationDate":"1537252561286",
                "activated":true
              },
          "status":"success",
          "username":"1234"
          }
}

注册IM用户[批量]

  • Path: /api/v1/users/creates
  • 方式: POST
  • 作用:批量注册
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
password body String 密码
  • 请求参数示例
[
  {
    "username": "1234",
    "password": "123"
  },
  {
    "username": "12347",
    "password": "123"
  }
]

  • 响应参数说明

外层参数

Name IN Type Description
success body String true/false
code body int 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

datas内部参数

Name IN Type Description
username body String 用户名
nickname body int 昵称
creationDate body String 创建时间
modificationDate body String 更新时间
activated body Boolean 账号状态
status body String 请求状态(success/error)
  • 成功示例
{
  "success": true,
  "code": 200,
  "msg": null,
  "datas":[
          {
            "createUserVO":
                {
                   "username":"1234",
                   "nicakname":"1234",
                   "creationDate":"1537252561286",
                   "modificationDate":"1537252561286",
                   "activated":true
                 },
            "status":"success",
            "username":"1234"
          },
          {
            "createUserVO":
                {
                  "username":"12347",
                  "nicakname":"12347",
                  "creationDate":"1537252561540",
                  "modificationDate":"1537252561540",
                  "activated":true
                },
           "status":"success",
           "username":"12347"
         }
         ]
}

获取IM用户信息

  • Path: /api/v1/users/{username}
  • 方式: GET
  • 作用:获取用户资料
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
  • 响应参数说明
参数名 IN 类型 必填 描述
username body String 用户名
nickname body String 昵称
creationDate body String 创建时间
modificationDate body String 更新时间

删除IM用户[单个]

  • Path:/api/v1/users/delete/{username}
  • 方式: DELETE
  • 作用:删除用户
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
  • 响应参数说明

外层参数

Name IN Type Description
success body String true/false
code body String 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

datas内部参数

Name IN Type Description
username body String 用户名
nickname body int 昵称
creationDate body String 创建时间
modificationDate body String 更新时间
activated body Boolean 账号状态
status body String 请求状态(success/error)
  • 成功示例
{
  "success": true,
  "code": 200,
  "msg": null,
  "datas":{
          "deleteUserVO":
                {
                   "username":"1234",
                   "nicakname":"1234",
                   "creationDate":"1537252561286",
                   "modificationDate":"1537252561286",
                   "activated":true
                },
           "status":"success",
           "username":"1234"
           }
}

删除IM用户[批量]

  • Path:/api/v1/users/deletes
  • 方式: DELETE
  • 作用:批量删除用户
  • 请求参数描述
参数名 IN 类型 必填 描述
username body List 用户名
  • 请求参数示例
[“111”,“222”]
  • 响应参数说明

外层参数

Name IN Type Description
success body String true/false
code body String 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

datas内部参数

Name IN Type Description
username body String 用户名
nickname body int 昵称
creationDate body String 创建时间
modificationDate body String 更新时间
activated body Boolean 账号状态
status body String 请求状态(success/error)
  • 成功示例
{
  "success": true,
  "code": 200,
  "msg": null,
  "datas":[
          {
             "deleteUserVO":
                 {
                   "username":"111",
                   "nicakname":"1234",
                   "creationDate":"1537252561286",
                   "modificationDate":"1537252561286",
                   "activated":true
                  },
             "status":"success",
             "username":"111"
          },
          {
             "deleteUserVO":
                 {
                    "username":"222",
                    "nicakname":"12347",
                    "creationDate":"1537252561540",
                    "modificationDate":"1537252561540",
                    "activated":true
                  },
             "status":"success",
             "username":"222"
          }
          ]
}


重置IM用户密码

  • Path:/api/v1/users/deletes
  • 方式: POST
  • 作用:修改用户密码
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
password body String 密码
  • 响应参数说明
Name IN Type Description
success body String true/false
code body String 状态码
message body String 消息
datas body Object 数据体
extraInfo body String
  • 成功示例
 {
  "success": true,
  "code": 200,
  "msg": null,
  "datas":{
    "username": "1234",
    "password": "123"
          }
}

好友与黑名单


给IM用户添加好友

  • Path:/api/v1/rosters/
  • 方式: POST
  • 作用:添加好友
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
friendName body String 好友名
  • 回应参数描述
Name IN Type Description
true body Boolean 添加成功
false body Boolean 添加失败

解除IM用户的好友关系

获取IM用户的好友列表

  • Path:/api/v1/rosters/{username}
  • 方式: GET
  • 作用:获取好友列表
  • 请求参数描述
参数名 IN 类型 必填 描述
username path String 用户名
  • 回应参数描述

外层参数

Name IN Type Description
rosterID body Int 好友ID
jid body String 好友jid
username body String 好友用户名
name body String 好友昵称

获取IM用户的黑名单

往IM用户的黑名单中加人

从IM用户的黑名单中减人

在线与离线


查看用户的在线状态

  • Path:/api/v1/users/is_online
  • 方式: GET
  • 作用:获取用户在线状态
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
  • 回应参数描述

外层参数

Name IN Type Description
success body String true/false
code body String 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

datas内部参数

Name IN Type Description
key body String 用户名
value body String 在线状态
code body String 状态码
  • 成功示例
{
  "success": true,
  "code": 200,
  "msg": null,
  "datas":{
           "code":"200",
           "sk":"offline"
          }
}

查询离线消息

查询某条离线消息状态

账号禁用与解禁


用户账号禁用

  • Path:/api/v1/users/forbid/{username}
  • 方式: POST
  • 作用:禁用用户
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
  • 回应参数描述

外层参数

Name IN Type Description
success body String true/false
code body String 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

datas内部参数

Name IN Type Description
username body String 用户名
nickname body int 昵称
creationDate body String 创建时间
modificationDate body String 更新时间
  • 成功示例
{
  "success": true,
  "code": 200,
  "msg": null,
  "datas":{
           "username":"diting_ceshi09",
           "nickname":"diting_ceshi09",
           "creationDate":"001536892719224",
           "modificationDate":"001536892719224"
          }
}

用户账号解禁

  • Path:/api/v1/users/un_forbid/{username}
  • 方式: POST
  • 作用:解禁用户
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 用户名
  • 回应参数描述
Name IN Type Description
success body String true/false
code body String 状态码
message body String 消息
datas body Object 数据体
extraInfo body String

强制用户下线


  • Path:/api/v1/users/ lockout/{username}
  • 方式: PUT
  • 作用:用户下线
  • 请求参数描述
参数名 IN 类型 必填 描述
username body String 登录用户
  • 回应参数描述
Name IN Type Description
true body Boolean 成功
false body Boolean 失败