設定使用者識別碼

GPTBots 支援開發者為 Agent 使用者在不同渠道（例如網站、應用程式、即時聊天）設置唯一的身份識別碼（UserId）。此 UserId 可實現跨渠道的使用者身份整合，方便透過工具進行跨渠道的使用者身份整合、業務查詢，以及維護使用者屬性與聊天記錄。UserId 的具體應用場景包括：

工具：當 AI Agent 呼叫工具向開發者的業務 API 發出請求時，UserId 會包含在標頭中，方便開發者識別使用者。
使用者屬性：開發者設定 UserId 後，使用者屬性資訊將與此 UserId 關聯。
對話記錄：開發者設定 UserId 後，使用者與 Agent 的對話記錄將歸屬於此 UserId。
事件回調：開發者設定 UserId 後，iframe/widget 內產生的事件回調，並回報至 GA4/webhook 時，將攜帶此資訊。

⚠️ User ID（UserId）應為開發者業務系統內的使用者唯一識別碼。此 UserId 可用於查詢業務數據，例如使用者 VIP 等級、用戶標籤與訂單資訊。

設定使用者識別碼

此 API 允許開發者以「匿名 ID + 對話模式 + 來源 ID」的組合來管理使用者身份資訊。

請求方法

POST

端點

https://api.${endpoint}/v1/user/set-userid

請求

請求範例

curl -X POST 'https://api.${endpoint}/v1/user/set-userid' \ -H 'Authorization: Bearer ${token}' \ -H 'Content-Type: application/json' \ -d '{ "user_id": "67b58121035e5b152b0419ee", "anonymous_ids": [ { "anonymous_id": "6a0dnyvi3jc32flk7enw", "conversation_type": "SHARE" }, { "anonymous_id": "6a0dnyvi3jc32flk7enw", "conversation_type": "TELEGRAM", "source_id": "bot_029392" } ] }'

                      
                      curl -X POST 'https://api.${endpoint}/v1/user/set-userid' \
-H 'Authorization: Bearer ${token}' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "67b58121035e5b152b0419ee",
    "anonymous_ids": [
        {
            "anonymous_id": "6a0dnyvi3jc32flk7enw",
            "conversation_type": "SHARE"
        },
        {
            "anonymous_id": "6a0dnyvi3jc32flk7enw",
            "conversation_type": "TELEGRAM",
            "source_id": "bot_029392"
        }
    ]
}'

此代碼塊在浮窗中顯示

一個 user_id 最多可關聯 100 個 anonymous_id。若超過此限制，將自動移除關聯時間最早的紀錄（依 updateTime 排序）。
開發者可以透過全域變數中的 anonymous_id 來取得當前使用者的匿名 ID，並透過 conversation_type 取得對話模式。

請求標頭

欄位	類型	描述
Authorization	Bearer ${token}	使用 `Authorization: Bearer ${token}` 進行身份驗證。請從 API 金鑰頁面取得您的 token。
Content-Type	application/json	資料類型，值為：`application/json`。

請求主體

參數	類型	描述	必填
user_id	string	開發者定義的使用者識別碼。	是
anonymous_ids	array	GPTBots 平台產生的匿名 ID 列表，通常依據第三方平台的唯一標識符。可從 Agent 全域變數中的 `anonymous_id` 取得。	是
anonymous_ids[].anonymous_id	string	匿名 ID。	是
anonymous_ids[].conversation_type	string	匿名 ID 的來源平台，等同於「Agent-Integration」中的平台，例如 WHATSAPP、LINE 等。可從使用者概覽中的 `conversation_type` 取得。	是
anonymous_ids[].source_id	string	對話來源平台的渠道 ID。例如，若整合了 `TELEGRAM`，並新增了兩個 TG Bots，則每個 Bot 都會有其專屬的 Source ID。	否

關聯邏輯說明：

關聯關係由「anonymous_id + conversation_type + source_id」的組合唯一決定。

若此組合已關聯至當前 user_id，僅會更新關聯時間（updateTime）。

若此組合尚未關聯至任何 user_id，將建立新的關聯關係。

若此組合已關聯至其他 user_id，則會先解除舊的關聯，再關聯至當前 user_id。

若單一 user_id 的關聯數超過 100，將自動刪除關聯時間最早的紀錄。

回應

回應主體

{ "code": 0, "message": "OK", "data": { "user_id": "67b58121035e5b152b0419ee", "anonymous_ids": [ { "anonymous_id": "6a0dnyvi3jc32flk7enw", "conversation_type": "SHARE", "source_id": null }, { "anonymous_id": "6a0dnyvi3jc32flk7enw", "conversation_type": "TELEGRAM", "source_id": "bot_029392" } ] } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "user_id": "67b58121035e5b152b0419ee",
        "anonymous_ids": [
            {
                "anonymous_id": "6a0dnyvi3jc32flk7enw",
                "conversation_type": "SHARE",
                "source_id": null
            },
            {
                "anonymous_id": "6a0dnyvi3jc32flk7enw",
                "conversation_type": "TELEGRAM",
                "source_id": "bot_029392"
            }
        ]
    }
}

此代碼塊在浮窗中顯示

成功回應

欄位	類型	描述
user_id	string	使用者識別碼。
anonymous_ids	array	當前關聯至此使用者識別碼的所有匿名 ID 及其對話模式。
anonymous_ids[].anonymous_id	string	匿名 ID。
anonymous_ids[].conversation_type	string	對話模式的列舉值，等同於「Agent-Integration」中的平台。
anonymous_ids[].source_id	string	對話來源平台的渠道 ID。例如，若整合了 `TELEGRAM`，並新增了兩個 TG Bots，則每個 Bot 都有其專屬的 Source ID。

錯誤回應

欄位	類型	描述
code	int	錯誤代碼。
message	string	錯誤訊息。

狀態碼

狀態碼	描述
200	成功
400	參數無效
401	未授權
403	禁止訪問
500	伺服器發生錯誤