Webhook-Modus

Der GPTBots-Agent unterstützt aktuell drei Modi für Nachrichtenantworten: blocking, streaming und webhook. Wenn Entwickler:innen den webhook-Modus nutzen, um Antwortnachrichten zu empfangen, werden sowohl KI-Antworten als auch Menschliche Antworten an die angegebene Webhook-URL übermittelt.

Antwortmodus	Unterstützte Nachrichtentypen
blocking	KI-Antworten
streaming	KI-Antworten
webhook	Menschliche Antworten, KI-Antworten

Nachrichtenversand-API übermittelt Antwortnachrichten an den Webhook

Anfragemethode

POST

Endpoint

Bitte konfigurieren Sie Ihre Empfangsadresse für Nachrichten auf der Seite Agent – Integration – API – Webhook.

Authentifizierung

Es werden zwei Authentifizierungsmethoden unterstützt: Basic-Authentifizierung und Bearer-Authentifizierung. Entwickler:innen können die für ihre Situation passende Methode wählen und auf der Seite Agent – Integration – API – Webhook konfigurieren.

Wenn Entwickler:innen bei der Integration einer Webhook-Adresse nur den Webhook-Benutzernamen ausfüllen, verwendet GPTBots beim Senden von Anfragen an die Webhook-URL der Entwickler:innen standardmäßig die Bearer-Authentifizierung, wobei der Wert dem Webhook-Benutzernamen entspricht.
Wenn Entwickler:innen bei der Integration einer Webhook-Adresse sowohl den Webhook-Benutzernamen als auch das Webhook-Geheimnis ausfüllen, verwendet GPTBots beim Senden von Anfragen die Basic-Authentifizierung, wobei der Benutzername dem Webhook-Benutzernamen und das Passwort dem Webhook-Geheimnis entspricht.

Beispielanfrage

curl -X POST 'IHRE_API_URL' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "create_time": 1679587005, "user_id": "65a4ccfc7ce58e728d5897e0", "anonymous_id": "device_abcdef123456", "conversation_id": "657303a8a764d47094874bbe", "message_id": "65a4ccfC7ce58e728d5897e0", "output": [ { "from_component_branch": "1", "from_component_name": "Komponentenname", "content": { "text": "Hallo, kann ich Ihnen irgendwie helfen?", "audio": [ { "audio": "http://gptbots.ai/example.mp3", "transcript": "Der transkribierte Inhalt der Audiodatei" } ] } } ], "usage": { "tokens": { "total_tokens": 29, "prompt_tokens": 19, "prompt_tokens_details": { "audio_tokens": 0, "text_tokens":0 }, "completion_tokens": 10, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "text_tokens": 0 } }, "credits": { "total_credits":0.0, //prompt + completion "text_input_credits": 0.0, "text_output_credits": 0.0, "audio_input_credits": 0.0, "audio_output_credits": 0.0 } } }'

                      
                      curl -X POST 'IHRE_API_URL' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "create_time": 1679587005,
    "user_id": "65a4ccfc7ce58e728d5897e0",
    "anonymous_id": "device_abcdef123456",
    "conversation_id": "657303a8a764d47094874bbe",
    "message_id": "65a4ccfC7ce58e728d5897e0",
    "output": [
        {
            "from_component_branch": "1",
            "from_component_name": "Komponentenname",
            "content": {
                "text": "Hallo, kann ich Ihnen irgendwie helfen?",
                "audio": [
                    {
                        "audio": "http://gptbots.ai/example.mp3",
                        "transcript": "Der transkribierte Inhalt der Audiodatei"
                    }
                ]
            }
        }
    ],
    "usage": {
        "tokens": {
           "total_tokens": 29,
            "prompt_tokens": 19,
            "prompt_tokens_details": 
                {  
                    "audio_tokens": 0,
                    "text_tokens":0
                },
            "completion_tokens": 10,
            "completion_tokens_details": 
                {
                    "reasoning_tokens": 0,
                    "audio_tokens": 0,
                    "text_tokens": 0
                }
        },
        "credits": {
            "total_credits":0.0,  //prompt + completion
            "text_input_credits": 0.0,
            "text_output_credits": 0.0,
            "audio_input_credits": 0.0,
            "audio_output_credits": 0.0
        }
    }
}'

Dieser Codeblock im schwebenden Fenster

Anfrage-Body

Feld	Typ	Beschreibung
user_id	string	Die vom Entwickler gebundene Nutzer:innen-ID; null, wenn kein:e Nutzer:in gebunden ist.
anonymous_id	string	Anonyme Nutzer:innen-ID (Geräte-ID).
conversation_id	string	Eindeutige Kennung der Konversation.
message_id	string	Eindeutige Kennung einer bestimmten Nachricht innerhalb einer Konversation.
create_time	long	Zeitstempel, zu dem die Nachricht generiert wurde.
output	JSON-Array	Antwortinhalt des KI-Agenten.
from_component_branch	string	FlowAgent-Branch.
from_component_name	string	Name der vorgelagerten Komponente im FlowAgent.
content	object	Antwortnachricht des KI-Agenten; aktuell werden die Nachrichtentypen „Text“ und „Audio“ unterstützt.
usage	object	Verbrauchsdaten.
tokens	JSON-Array	Gesamtzahl der vom Agent in dieser Konversation verbrauchten Tokens.
total_tokens	integer	Gesamtzahl der verbrauchten Tokens für Eingabe + Ausgabe in dieser Konversation.
prompt_tokens	integer	Gesamtzahl der für die Eingabe verbrauchten Tokens in dieser Konversation.
completion_tokens	integer	Gesamtzahl der für die Ausgabe verbrauchten Tokens in dieser Konversation.
prompt_tokens_details	object	Details zum Tokenverbrauch für die Eingabe in dieser Konversation.
completion_tokens_details	object	Details zum Tokenverbrauch für die Ausgabe in dieser Konversation.
credits	object	Insgesamt vom Agent in dieser Konversation verbrauchte Credits.
text_input_credits	double	Verwendete Credits für Texteingaben in dieser Konversation.
text_output_credits	double	Verwendete Credits für Textausgaben in dieser Konversation.
audio_input_credits	double	Verwendete Credits für Audioeingaben in dieser Konversation.
audio_output_credits	double	Verwendete Credits für Audioausgaben in dieser Konversation.

Antwortspezifikation

Nachdem der Webhook-Service der Entwickler:innen die Nachricht erfolgreich empfangen hat, muss er den HTTP-Statuscode 200 und im Response-Body einen JSON-Erfolgsindikator zurückgeben.

{ "code": 200, "msg": "success" }

                      
                      {
  "code": 200,
  "msg": "success"
}

Dieser Codeblock im schwebenden Fenster

GPTBots Webhook-Servicestatus-Erkennung

GPTBots stellt eine Health-Check-Schnittstelle zur Erkennung seines eigenen Webhook-Dienstes bereit. Entwickler:innen können sie aufrufen, um zu prüfen, ob der Webhook-Dienst von GPTBots verfügbar ist. Wenn die Schnittstelle den HTTP-Statuscode 200 zurückgibt und der Response-Body der Klartext-Indikator für einen normalen Service ist (z. B. service is normal), ist der Webhook-Dienst von GPTBots verfügbar. Diese Schnittstelle erfordert keine Authentifizierung und gibt Klartext zurück.

Anfrage-Methode

GET

Endpoint

https://api.gptbots.ai/v1/webhook/service/health

Beispielanfrage

curl -X GET 'https://api.gptbots.ai/v1/webhook/service/health'

                      
                      curl -X GET 'https://api.gptbots.ai/v1/webhook/service/health'

Dieser Codeblock im schwebenden Fenster

Antwort

Wenn der GPTBots-Service verfügbar ist, gibt er den HTTP-Statuscode 200 und im Response-Body einen Klartext-Indikator für einen normalen Service zurück.

service is normal

                      
                      service is normal

Dieser Codeblock im schwebenden Fenster

Empfehlung zur Verfügbarkeitsbewertung

Der Aufrufer muss lediglich den HTTP-Statuscode als Kriterium verwenden:

Situation	Entscheidung
Gibt `200` zurück und der Body lautet `service is normal`	GPTBots-Service ist verfügbar
Gibt nicht `200` zurück (z. B. 5xx) / Anfrage-Timeout / Verbindungsfehler	GPTBots-Service ist nicht verfügbar

Es wird empfohlen, ein angemessenes Anfrage-Timeout festzulegen (z. B. 3–5 Sekunden) und mit einer festen Frequenz abzufragen (QPM:3). Diese Schnittstelle erfordert keine Authentifizierung; es ist kein API-Key erforderlich.