跳至主要内容

添加客服

向已有工单会话添加客服参与人。

请求​

POST https://apichat.twt.com/openapi/chat/add_kf

Header 参数​

参数名类型必填说明
x-chat-signaturestring是HMAC-SHA256 签名。使用实际发送的原始 JSON body 计算 hash_hmac('sha256', raw_body, app_secret)
Acceptstring否默认：application/json
Content-Typestring是application/json

Body 参数​

参数类型必填说明
appidstring是控制台中的应用标识
timestampinteger是请求时间戳，生产环境中过期时间戳可能被拒绝
ranstrstring是随机字符串
chat_idinteger是工单会话 ID。会话必须属于 appid 对应站点
kefu_idsstring 或 array[integer]是要添加的客服 ID。推荐使用英文逗号拼接字符串，例如 10427,10428；也兼容整数数组

请求示例​

curl --location --request POST 'https://apichat.twt.com/openapi/chat/add_kf' \
--header 'x-chat-signature: 0bf19198ab2dd65a407ca8d57fbb3f6ebca71d22709a1f5d53c685e9e25abdbc' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appid": "42d7c13c16e7ed0479f2418eb8894310",
    "timestamp": 1781683144,
    "ranstr": "codex1033048655",
    "chat_id": 900220,
    "kefu_ids": "10427,10428"
}'

兼容数组示例​

{
    "appid": "42d7c13c16e7ed0479f2418eb8894310",
    "timestamp": 1781683144,
    "ranstr": "codex1033048655",
    "chat_id": 900220,
    "kefu_ids": [
        10427,
        10428
    ]
}

返回响应​

200 成功​

参数类型必填说明
codeinteger是1 成功，-1 失败
msgstring是响应提示
datastring是成功时为空字符串
{
  "code": 1,
  "msg": "ok",
  "data": ""
}

失败示例​

{
  "code": -1,
  "msg": "token验证失败!",
  "data": ""
}
{
  "code": -1,
  "msg": "会话不存在",
  "data": ""
}
{
  "code": -1,
  "msg": "当前状态不允许操作",
  "data": ""
}

注意事项​

  • 该接口仅适用于工单会话。
  • 会话必须已有负责人客服。系统添加参与人时，会使用当前负责人客服作为操作人。
  • 新增客服必须属于同一站点，并且处于正常状态。
  • 已在服务中的客服会由底层服务流程忽略。如果没有剩余有效新客服，本次请求会失败。
  • 签名必须基于实际发送的原始 JSON body 计算。