Skip to content

Set User ID V2

Last updated at: 2026-01-10 Note: The next major update is scheduled for late January 2026.

Set User ID

AltaBots supports developers in setting unique identity IDs for Agent users across different channels (such as: website, APP, LiveChat). Through this user ID (UserId), user identity association can be achieved across different channels, enabling cross-channel user identity merging, business queries through Tools, maintenance of user attributes and chat records, etc. The specific application scenarios of user ID are as follows:

Tools: When the AI Agent calls Tools to initiate requests to the developer's business API, it will include the UserId in the Header for easy user identity recognition by developers.

User Attributes: After developers set the UserId, user attribute information will be attributed to that UserId.

Conversation Logs: After developers set the UserId, conversation log records between users and the Agent will be attributed to that UserId.

Event Callbacks: After developers set the UserId, event callbacks generated in iframe/widget and reported to GA4/webhook will carry this information.

⚠️ The user ID (UserId) should be the unique identity identifier of the user in the developer's business system. Through this UserId, business data information such as the user's VIP level, user tags, and user orders can be queried.

Set User ID

Supports developers in setting user IDs through anonymous ID + conversation type + source ID to achieve management of user identity information.

  • Bubble Widget Set User ID
  • Iframe Set User ID

Request Method

POST

Request URL

https://altatech.ai/v1/user/set-userid

Request

Request Example

curl -X POST 'https://altatech.ai/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 single user_id can bind up to 100 anonymous_ids. When the limit is exceeded, the binding with the earliest updateTime will be automatically deleted.

Developers can obtain the current user's anonymous ID by referencing the anonymous_id in global variables, and obtain the conversation type value through conversation_type.

Request Headers

Field Type Description
Authorization Bearer ${token} Use Authorization: Bearer ${token} for call verification. Please obtain the key as token from the API Keys page.
Content-Type application/json Data type, value is: application/json.

Request Body

Parameter Type Description Required
user_id string Developer-defined user ID true
anonymous_ids array List of anonymous IDs generated by the AltaBots platform, usually generated based on the unique identifier of third-party platforms. Can be obtained through the anonymous_id in Agent global variables true

Binding Logic Description:

  • The binding relationship is uniquely determined by the combination of anonymous_id + conversation_type + source_id
  • When this combination is already bound to the current user_id, only the binding time (updateTime) is updated
  • When this combination is not bound to any user_id, a new binding relationship is created
  • When this combination is already bound to another user_id, the old binding relationship is first removed, then bound to the current user_id
  • When 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"
            }
        ]
    }
}

Success Response

Field Type Description
user_id string User ID
anonymous_ids array All anonymous IDs and their conversation types currently bound to this user ID
anonymous_ids[].anonymous_id string Anonymous ID
anonymous_ids[].conversation_type string Conversation type enumeration value, equivalent to the platform in "Agent-Integration"
anonymous_ids[].source_id string Channel ID in the conversation source platform, for example: when integration is TELEGRAM and 2 TG Bots are added, each Bot will have its own Source ID

Error Response

Field Type Description
code int Error code
message string Error message

Status Codes

Status Code Description
200 Success
400 Parameter error
401 Unauthorized
403 Insufficient permissions
500 Server error