Create Session

Create one session.

Request

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

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
sbs	string/number	Yes	Unique customer identifier, 1 to 64 characters. The customer is created when it does not exist
ip	string	Yes	Customer IP address
sbs_mc	string	Yes	Customer name, 1 to 30 characters
content	string	Yes	Initial message, 1 to 2000 characters. The sender is determined by sender_type
title	string	No	Session title, 1 to 120 characters. When provided, it is used as the visitor and agent remark title
kefu_id	array[integer]	Yes	Agent ID list. Multiple agents are allowed
fzr_uid	integer	Yes	Responsible agent ID. It must be included in kefu_id
sender_type	integer	No	Initial message sender. 1: visitor; 2: responsible agent specified by fzr_uid; 3: system-generated agent message. Default: 2

Request Example

curl --location --request POST 'https://apichat.twt.com/openapi/chat/create_gd' \
--header 'x-chat-signature: 0bf19198ab2dd65a407ca8d57fbb3f6ebca71d22709a1f5d53c685e9e25abdbc' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appid": "...",
    "timestamp": 1781683144,
    "ranstr": "codex1033048655",
    "sbs": "customer_001",
    "kefu_id": [
        10411,
        10427
    ],
    "fzr_uid": 10411,
    "sender_type": 2,
    "ip": "127.0.0.1",
    "sbs_mc": "Customer Name",
    "content": "Initial message",
    "title": "Order Consultation"
}'

Response

200 Success

Parameter	Type	Required	Description
code	integer	Yes	1 success, -1 failure
msg	string	Yes	Response message
data.chat_id	integer	Yes	Created session ID

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

Error Example

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

{
  "code": -1,
  "msg": "参数错误",
  "data": ""
}

Notes

• The content field is required. sender_type=1 sends it as the visitor and leaves the session waiting for a reply.
• sender_type=2 sends it as the responsible agent specified by fzr_uid and leaves the session replied. sender_type=3 sends system-generated content as an agent message (uid=0) and does not change the session status.
• Omitting sender_type is equivalent to sender_type=2 for backward compatibility. Values other than 1, 2, or 3 are rejected.
• The title field is optional. When provided, it is saved as the visitor and agent remark title, while automatic title summarization continues as usual.
• fzr_uid must be one of the agent IDs in kefu_id.
• Agents other than fzr_uid are added as session participants.
• The signature must be calculated from the exact raw JSON body sent in the HTTP request.