IM 客服接口

验签、请求头、HMAC-SHA256 算法、多语言示例与通用开放对接一致，请先阅读 基础约定。

用户身份说明

三个接口均需识别当前操作用户（与运单综合查询同属「端用户 JWT」认证，但 IM 需保留子账号维度）：

1. 优先从请求中读取主站 JWT（X-Access-Token 请求头、Authorization: Bearer <token>，或 Query 参数 token），经 LoginUserUtil.resolveLoginUser 组装完整登录用户（保留子账号）。
2. 其次若 token 缺失或无效，可使用请求体中的 imAccount（已注册的 IM 账号 ID）反查主账号维度用户。
3. 最后若 token 和 imAccount 均无法识别，可使用请求体中的 workNo（会员号）查询对应主账号。

均未命中时返回 code=401，message 为「用户ID不能为空或未登录」。

提示

getAccountToken、isIm 的请求体为可选；无 body 时仅依赖 token。createTeam 无 body 时等价于 {}。

---

获取 IM 登录令牌

• 接口地址：/openapi/im/getAccountToken
• 请求方式：POST
• 说明：校验用户是否已开启 IM，必要时自动注册 IM 账号，并返回 IM SDK 登录所需令牌。对齐主站商家端 getAccountToken。

请求参数

字段	类型	必填	说明
imAccount	String	否	IM 账号 ID；token 缺失时用于解析用户，有 token 时可省略
workNo	String	否	会员号；token 和 imAccount 均无法识别时用于定位用户

请求示例

{}

token 不可用时：

{
  "imAccount": "acc_xxxxxxxx"
}

响应字段

result（ImAccountTokenVO）：

字段	类型	说明
accountId	String	IM 账号 ID
token	String	IM 登录令牌
userName	String	用户姓名（展示名）

响应示例

{
  "code": 200,
  "message": "success",
  "result": {
    "accountId": "acc_xxxxxxxx",
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "userName": "张三"
  },
  "traceId": "20260708143000-xxx"
}

业务说明

• 用户类型须为商家、物流或企业控制台（与主站 IM 用户类型一致）；不支持时返回业务错误。
• 商家默认视为已开启 IM；物流商须在公司维度已配置 IM 开关。
• 若用户尚未注册 IM 账号，本接口会先尝试注册再取令牌。

错误码

code	场景
200	成功
401	token、imAccount 与 workNo 均未解析到用户
500	未开启 IM、注册失败、取令牌失败等业务错误

---

是否可使用 IM

• 接口地址：/openapi/im/isIm
• 请求方式：POST
• 说明：查询当前用户是否已开启 IM 能力。对齐主站 isIm。

请求参数

字段	类型	必填	说明
imAccount	String	否	IM 账号 ID；token 缺失时用于解析用户，有 token 时可省略
workNo	String	否	会员号；token 和 imAccount 均无法识别时用于定位用户

请求示例

{}

响应字段

result：Boolean，true 表示可使用 IM，false 表示不可用。

响应示例

{
  "code": 200,
  "message": "success",
  "result": true,
  "traceId": "20260708143000-xxx"
}

业务说明

• 商家用户：恒为 true。
• 物流用户：取决于物流公司是否已开启 IM 开关。
• 企业控制台用户：恒为 true。
• 其它用户类型：返回 false。

错误码

code	场景
200	成功（result 可能为 false）
401	token、imAccount 与 workNo 均未解析到用户

---

创建企业控制台群聊

• 接口地址：/openapi/im/createTeam
• 请求方式：POST
• 说明：商家或物流商发起企业控制台客服咨询，自动匹配在线客服并创建 IM 群聊。对齐主站商家端 /createAdminTeam。

说明

仅商家或物流商主账号可发起；企业控制台客服作为群成员加入。无单咨询场景，无需传运单等业务参数。

请求参数

字段	类型	必填	说明
imAccount	String	否	IM 账号 ID；token 缺失时用于解析用户，有 token 时可省略
workNo	String	否	会员号；token 和 imAccount 均无法识别时用于定位用户

请求示例

{}

响应字段

result（ImTeamCreateVO）：

字段	类型	说明
teamId	String	群聊 ID
name	String	群名称
supplierTeamId	String	IM 供应商侧群 ID

响应示例

{
  "code": 200,
  "message": "success",
  "result": {
    "teamId": "team_xxxxxxxx",
    "name": "300061-某某物流",
    "supplierTeamId": "sup_team_xxxxxxxx"
  },
  "traceId": "20260708143000-xxx"
}

业务说明

• 群名称格式：会员号-发起方简称（商家取发货主体简称，物流取公司简称）。
• 匹配企业控制台全部已启用客服；若均未注册 IM 账号则创建失败。
• 发起人须已注册 IM 账号；商家发起时可能自动拉入商家 IM 机器人账号（若已配置）。
• 非商家/物流用户调用时返回业务错误。

错误码

code	场景
200	成功
401	token、imAccount 与 workNo 均未解析到用户
500	用户类型不符、未匹配客服、发起人未注册 IM、建群失败等业务错误