Add Agents

Add agents to an existing ticket session.

Request

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

Header Parameters

Parameter	Type	Required	Description
x-chat-signature	string	Yes	HMAC-SHA256 signature. Calculate hash_hmac('sha256', raw_body, app_secret) with the exact raw JSON body
Accept	string	No	Default: application/json
Content-Type	string	Yes	application/json

Body Parameters

Parameter	Type	Required	Description
appid	string	Yes	Application identifier from the console
timestamp	integer	Yes	Request timestamp. In production, expired timestamps may be rejected
ranstr	string	Yes	Random string
chat_id	integer	Yes	Ticket session ID. The session must belong to the appid site
kefu_ids	string or array[integer]	Yes	Agent IDs to add. A comma-separated string such as 10427,10428 is recommended. Integer arrays are also accepted for compatibility

Request Example

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"
}'

Compatible Array Example

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

Response

200 Success

Parameter	Type	Required	Description
code	integer	Yes	1 success, -1 failure
msg	string	Yes	Response message
data	string	Yes	Empty string on success

{
  "code": 1,
  "msg": "ok",
  "data": ""
}

Error Example

{
  "code": -1,
  "msg": "token验证失败!",
  "data": ""
}

{
  "code": -1,
  "msg": "会话不存在",
  "data": ""
}

{
  "code": -1,
  "msg": "当前状态不允许操作",
  "data": ""
}

Notes

• This API only applies to ticket sessions.
• The session must already have a responsible agent. The responsible agent is used as the operation user when the system adds participants.
• The new agents must belong to the same site and be in normal status.
• Existing session agents are ignored by the underlying service flow. If no valid new agent remains, the request fails.
• The signature must be calculated from the exact raw JSON body sent in the HTTP request.