建立會話

建立一個會話。

請求

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

Header 參數

參數名	類型	必填	說明
x-chat-signature	string	是	HMAC-SHA256 簽名。使用實際發送的原始 JSON body 計算 hash_hmac('sha256', raw_body, app_secret)
Accept	string	否	預設：application/json
Content-Type	string	是	application/json

Body 參數

參數	類型	必填	說明
appid	string	是	控制台中的應用標識
timestamp	integer	是	請求時間戳，生產環境中過期時間戳可能被拒絕
ranstr	string	是	隨機字串
sbs	string	是	客戶唯一標識，1 到 64 個字元。客戶不存在時自動建立
ip	string	是	客戶 IP 地址
sbs_mc	string	是	客戶姓名，1 到 30 個字元
content	string	是	初始訊息，1 到 2000 個字元。該訊息以負責人客服身份發送
title	string	否	會話標題，1 到 120 個字元。傳入後作為訪客和客服備註標題
kefu_id	array[integer]	是	客服 ID 列表，允許多個客服
fzr_uid	integer	是	負責人客服 ID，必須包含在 kefu_id 中

請求範例

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,
    "ip": "127.0.0.1",
    "sbs_mc": "客戶姓名",
    "content": "初始訊息",
    "title": "訂單諮詢"
}'

返回響應

200 成功

參數	類型	必填	說明
code	integer	是	1 成功，-1 失敗
msg	string	是	響應提示
data.chat_id	integer	是	建立成功的會話 ID

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

失敗範例

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

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

注意事項

• content 必填，並以 fzr_uid 對應負責人客服身份發送。
• title 非必填，傳入後保存為訪客和客服備註標題，自動總結標題仍按正常邏輯生成。
• fzr_uid 必須屬於 kefu_id 集合。
• 除 fzr_uid 外的客服會作為會話參與人加入。
• 簽名必須基於實際發送的原始 JSON body 計算，欄位順序、空格和換行都需要保持一致。