设置用户ID

GPTBots 支持开发者在不同渠道（如：网站、APP 、LiveChat ）为 Agent 用户设置唯一身份ID，通过该用户ID(UserId) 可以在不同渠道之间进行用户身份关联，实现跨渠道用户身份合并、通过 Tools 实现业务业务查询、维护用户属性和聊天记录等。用户ID的具体应用场景如下：

Tools： AI Agent 在调用 Tools 向开发者业务 API 发起请求时，会将 UserId 放在 Header 中，便于开发者识别用户身份。
用户属性：开发者设置 UserId 后，用户属性信息将被归属于该 UserId。
对话日志：开发者设置 UserId 后，用户与 Agent 的对话日志记录将被归属于该 UserId。
对话日志：开发者设置 UserId 后，用户与 Agent 的对话日志记录将被归属于该 UserId。
事件回调：开发者设置 UserId 后，在 iframe/widget 中所产生的事件回调上报至GA4/webhook 时会携带该信息。

⚠️用户ID(UserId) 应是用户在开发者业务系统内的唯一身份标识。通过该 UserId 可以查询到该用户的 VIP 等级、用户标签、用户订单等业务数据信息。

设置用户ID

支持开发者通过匿名ID+对话类型+来源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。

请求体

参数	类型	说明	required
user_id	string	开发者自定义的用户ID	true
anonymous_ids	array	GPTBots 平台生成的匿名 ID 列表，通常会根据三方平台的用户唯一标识符生成。可通过 Agent 全局变量中的 `anonymous_id` 获取	true
anonymous_id	string	匿名 ID	true
conversation_type	string	匿名 ID 的来源平台，等同于「Agent-集成」中的平台，例如 WHATSAPP、LINE 等。可在用户概述中的 `conversation_type` 中获取	true
source_id	string	对话来源平台中的来源ID。如：集成为 `TELEGRAM` 且添加 2 个 TG Bot 时，每个 Bot 会有自己的 Source ID	false

绑定逻辑说明：

绑定关系由 anonymous_id + conversation_type + source_id 的组合唯一确定

当该组合已与当前 user_id 绑定时，仅更新绑定时间（updateTime）

当该组合未绑定到任何 user_id 时，创建新的绑定关系

当该组合已与其他 user_id 绑定时，先解除旧的绑定关系，再绑定到当前的 user_id

当单个 user_id 的绑定数量超过100个时，会自动删除 updateTime 最早的绑定记录

响应

响应体

{ "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	用户 ID
anonymous_ids	array	该用户 ID 当前绑定的所有匿名 ID 及其对话类型
anonymous_ids[].anonymous_id	string	匿名 ID
anonymous_ids[].conversation_type	string	对话类型枚举值，等同于「Agent-集成」中的平台
anonymous_ids[].source_id	string	对话来源平台中的渠道 ID，如：集成为 `TELEGRAM` 且添加 2 个 TG Bot 时，每个 Bot 会有自己的 Source ID

失败响应

字段	类型	描述
code	int	错误码
message	string	错误信息

状态码

状态码	说明
200	成功
400	参数错误
401	未授权
403	权限不足
500	服务器错误