Set User ID

GPTBots supports developers in setting a unique identity ID (UserId) for Agent users across different channels (e.g., websites, apps, LiveChat). This UserId enables user identity association across channels, facilitating cross-channel user identity merging, business queries via Tools, and maintenance of user attributes and chat records. Specific application scenarios for UserId include:

• Tools: When the AI Agent calls Tools to make requests to the developer's business API, the UserId will be included in the header, allowing developers to identify the user.
• User Attributes: After the developer sets the UserId, user attribute information will be associated with this UserId.
• Conversation Logs: After the developer sets the UserId, the user's conversation log records with the Agent will be attributed to this UserId.
• Event Callbacks: After the developer sets the UserId, event callbacks generated within iframes/widgets and reported to GA4/webhooks will carry this information.

⚠️ The User ID (UserId) should be the unique identifier for a user within the developer's business system. This UserId can be used to query business data such as the user's VIP level, user tags, and order information.

Set User ID

This API allows developers to set the User ID using a combination of anonymous ID + conversation type + source ID to manage user identity information.

• Set User ID in Bubble Widget
• Set User ID in Iframe
• Set User ID in LiveChat

Request Method

POST

Endpoint

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

Request

Request Example

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

                    

A user_id can be bound to a maximum of 100 anonymous_ids. If this limit is exceeded, the binding with the earliest updateTime will be automatically removed.
Developers can obtain the current user's anonymous ID by referencing anonymous_id in global variables, and the conversation type via conversation_type.

Request Headers

Request Body

Binding Logic Description:

1. The binding relationship is uniquely determined by the combination of anonymous_id + conversation_type + source_id.
2. If this combination is already bound to the current user_id, only the binding time (updateTime) will be updated.
3. If this combination is not bound to any user_id, a new binding relationship will be created.
4. If this combination is already bound to another user_id, the old binding relationship will be unbound first, and then bound to the current user_id.
5. If the number of bindings for a single user_id exceeds 100, the binding record with the earliest updateTime will be automatically deleted.

Response

Response Body

                      
                      {
    "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"
            }
        ]
    }
}

                    

Successful Response

Error Response

Status Codes