Benutzer-ID festlegen

GPTBots ermöglicht Entwickler:innen, eine eindeutige Benutzer-ID (UserId) für Agent-Nutzer:innen kanalübergreifend festzulegen – etwa auf Websites, in Apps oder im LiveChat. Diese UserId erleichtert die kanalübergreifende Zuordnung und Zusammenführung von Nutzeridentitäten, Geschäftsanfragen über Tools sowie die Pflege von Nutzerattributen und Chatprotokollen. Typische Anwendungsszenarien für die UserId sind:

• Tools: Ruft der KI-Agent Tools auf, um Anfragen an die Business-API der Entwickler:innen zu stellen, wird die UserId im Header mitgesendet, sodass die Nutzeridentifikation möglich ist.
• Nutzerattribute: Nach dem Festlegen der UserId werden Nutzerattribut-Informationen mit dieser UserId verknüpft.
• Konversationsprotokolle: Nach dem Festlegen der UserId werden die Chatprotokolle mit dem Agent dieser UserId zugeordnet.
• Event-Callbacks: Nach dem Festlegen der UserId enthalten Event-Callbacks, die innerhalb von iframes/Widgets generiert und an GA4/Webhooks gemeldet werden, diese Information.

⚠️ Die Benutzer-ID (UserId) sollte der eindeutige Identifikator einer:s Nutzer:in im Geschäftssystem der Entwickler:innen sein. Mit dieser UserId können Geschäftsdaten wie VIP-Level, Nutzer-Tags und Bestellinformationen abgefragt werden.

Benutzer-ID festlegen

Mit dieser API können Entwickler:innen die Benutzer-ID mithilfe einer Kombination aus anonymous ID + conversation type + source ID setzen, um Identitätsinformationen zu verwalten.

• Benutzer-ID im Bubble Widget festlegen
• Benutzer-ID im Iframe festlegen
• Benutzer-ID in LiveChat festlegen

Anfragemethode

POST

Endpoint

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

Anfrage

Beispielanfrage

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

                    

Eine user_id kann mit maximal 100 anonymous_ids verknüpft werden. Wird dieses Limit überschritten, wird die Bindung mit der frühesten updateTime automatisch entfernt.
Entwickler:innen können die aktuelle anonyme ID des:der Nutzer:in über die globale Variable anonymous_id und den Konversationstyp über conversation_type abrufen.

Anfrage-Header

Anfrage-Body

Beschreibung der Bindungslogik:

1. Die Bindungsbeziehung wird eindeutig durch die Kombination aus anonymous_id + conversation_type + source_id bestimmt.
2. Ist diese Kombination bereits mit der aktuellen user_id verknüpft, wird lediglich die Bindungszeit (updateTime) aktualisiert.
3. Ist diese Kombination mit keiner user_id verknüpft, wird eine neue Bindung erstellt.
4. Ist diese Kombination bereits mit einer anderen user_id verknüpft, wird die alte Bindung zuerst gelöst und dann an die aktuelle user_id gebunden.
5. Überschreitet die Anzahl der Bindungen einer einzelnen user_id 100, wird der Datensatz mit der frühesten updateTime automatisch entfernt.

Antwort

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

                    

Erfolgreiche Antwort

Fehlerantwort

Statuscodes