Nachricht senden
Mit dieser API können Sie Nachrichten an eine bestimmte conversation_id senden und Antworten erhalten, die von dem/der Agent:in generiert wurden. Die API unterstützt verschiedene Nachrichtentypen wie Text, Bilder, Audio und Dokumente.
Anfragemethode
POST
Endpunkt
https://api-${endpoint}.gptbots.ai/v2/conversation/message
Authentifizierung
Siehe API-Übersicht für Authentifizierungsanweisungen.
Anfrage
Beispielanfrage
curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"conversation_id": "686e2646cb8ee942d9a62d79",
"response_mode": "blocking",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Ich habe 2 Bilddateien hochgeladen, bitte OCR durchführen und 2 JSON-Datensätze zurückgeben."
},
{
"type": "image",
"image": [
{
"base64_content": "<complete_base64_string>",
"format": "jpeg",
"name": "TAXI1"
},
{
"url": "https://gptbots.ai/example.png",
"format": "png",
"name": "TAXI2"
}
]
},
{
"type": "audio",
"audio": [
{
"url": "https://gptbots.ai/example.mp3",
"format": "mp3",
"name": "example1 audio"
}
]
},
{
"type": "document",
"document": [
{
"base64_content": "<complete_base64_string>",
"format": "pdf",
"name": "example pdf"
}
]
}
]
}
],
"conversation_config": {
"long_term_memory": false,
"short_term_memory": false,
"knowledge": {
"data_ids": [
"58c70da0403cc812641b9356",
"59c70da0403cc812641df35a"
],
"group_ids": [
"67c70da0403cc812641b93je",
"69c70da0403cc812641df35f"
]
},
"custom_variables": {
"var_current_url": "https://gptbots.ai/example",
"var_session_id": "abcdef"
}
}
}'
Wichtige Hinweise:
- Für die Inhaltstypen
image,audiounddocumentkönnen Sie entweder Base64-kodierte Daten oder URL-Links verwenden – beide Formate werden unterstützt. - Im Modus eigenes Helpdesk-System (Custom Helpdesk) werden Nachrichten von Kundenservice-Mitarbeiter:innen und während der menschlichen Übernahme empfangene Nutzernachrichten mit
ai_response=falseoderrole=human_agentübermittelt; sie werden nur archiviert und lösen keine KI-Antwort aus. Beispiel:{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "blocking", "ai_response": false, "human_agent_info": { "name": "Alice", "email": "alice@example.com", "image_url": "https://gptbots.ai/avatar.png" }, "messages": [ { "role": "human_agent", "content": "Hallo, hier ist der menschliche Kundenservice. Womit kann ich Ihnen helfen?" } ] }{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "blocking", "ai_response": false, "human_agent_info": { "name": "Alice", "email": "alice@example.com", "image_url": "https://gptbots.ai/avatar.png" }, "messages": [ { "role": "human_agent", "content": "Hallo, hier ist der menschliche Kundenservice. Womit kann ich Ihnen helfen?" } ] }Dieser Codeblock im schwebenden Fenster - Entwickler:innen müssen nur die jeweils letzte Nutzernachricht senden, da GPTBots Kurzzeit- und Langzeitgedächtnis standardmäßig verwaltet. Falls Sie den Kurzzeit-Kontext individuell anpassen möchten, siehe folgendes Beispiel:"messages": [ { "role": "user", "content": "Hallo" //Eigener Kurzzeit-Kontext }, { "role": "assistant", "content": "Hallo! Wie kann ich Ihnen helfen?" //Eigener Kurzzeit-Kontext }, { "role": "user", "content": "Hallo" //Neueste Nutzernachricht }]
"messages": [ { "role": "user", "content": "Hallo" //Eigener Kurzzeit-Kontext }, { "role": "assistant", "content": "Hallo! Wie kann ich Ihnen helfen?" //Eigener Kurzzeit-Kontext }, { "role": "user", "content": "Hallo" //Neueste Nutzernachricht }]Dieser Codeblock im schwebenden Fenster
Anfrage-Header
| Feld | Typ | Beschreibung |
|---|---|---|
| Authorization | Bearer ${API Key} | Verwenden Sie Authorization: Bearer ${API Key} zur Authentifizierung. Den API Key erhalten Sie auf der API-Key-Seite. |
| Content-Type | application/json | Datentyp, muss application/json sein. |
Anfrageparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| conversation_id | string | Ja | Eindeutige Kennung der Konversation. Muss angegeben werden, um die Konversation fortzusetzen. |
| response_mode | string | Ja | Antwortmodus des/der Agent:in: |
| messages | JSON Array | Ja | Nachrichteninhalt, unterstützt die 3 Rollen user, assistant und human_agent zur Bildung des Konversationskontexts.ai_response unabhängig. |
| ai_response | boolean | Nein | Ob die KI auf diese Nachricht antwortet. Standardwert ist true – wird das Feld weggelassen, verhält sich der Aufruf exakt wie bei bestehenden Aufrufen.false: Die Nachricht wird nur archiviert; die KI antwortet nicht, es werden weder Tokens noch Credits verbraucht, und die Antwort ist eine leichtgewichtige Empfangsbestätigung.true: Die KI antwortet normal; im Modus eigenes Helpdesk-System (Custom Helpdesk) wird durch explizites Übergeben von true außerdem die Konversation aus der menschlichen Übernahme an die KI zurückgegeben.false; andernfalls entspricht es true. |
| human_agent_info | object | Nein | Identitätsinformationen der Kundenservice-Mitarbeiter:in; nur relevant, wenn messages role=human_agent enthält (Feld auf oberster Ebene, eine Anfrage entspricht einer Kundenservice-Mitarbeiter:in). |
| name | string | Nein | Name der Kundenservice-Mitarbeiter:in. |
| string | Nein | E-Mail-Adresse der Kundenservice-Mitarbeiter:in. | |
| image_url | string | Nein | Avatar-URL der Kundenservice-Mitarbeiter:in. |
| conversation_config | object | Nein | Ermöglicht es Entwickler:innen, den Funktionsumfang des/der Agent:in für diese Konversation temporär anzupassen. |
| short_term_memory | boolean | Nein | Kurzzeitgedächtnis-Schalter. Aktiviert oder deaktiviert das Kurzzeitgedächtnis nur für diese Konversation. |
| long_term_memory | boolean | Nein | Langzeitgedächtnis-Schalter. Aktiviert oder deaktiviert das Langzeitgedächtnis nur für diese Konversation. |
| knowledge | object | Nein | Wissensabrufbereich. Ermöglicht die individuelle Anpassung des Wissensabrufs für diese Konversation. Wenn sowohl group_ids als auch data_ids angegeben sind, erfolgt der Abruf innerhalb der Vereinigungsmenge der Wissensdatenbanken. Sind beide Arrays leer, wird kein Wissen abgerufen. Wird der Parameter knowledge weggelassen, gilt die Standardkonfiguration des/der Agent:in.group_ids: Wissensdatenbank-IDs, die mehrere Wissensdokumente enthalten können.data_ids: Wissensdokument-IDs innerhalb der Wissensdatenbank. |
| custom_variables | object | Nein | Benutzerdefinierte Variablen. Ermöglicht es Entwickler:innen, die Werte benutzerdefinierter Variablen im/bei Agent:in für diese Konversation temporär anzupassen. |
Hinweis:
Die Eingabe- und Ausgabekonfigurationsseiten für Agent:innen unterstützen unterschiedliche Erkennungsschemata für verschiedene Nachrichtentypen. Unterstützte Dateitypen und -größen variieren. Passen Sie die API-Daten entsprechend an. Maximal unterstützte Nachrichtenformate:
- Textnachricht: string
- Audionachricht: .mp3, .wav, .acc
- Bildnachricht: .jpg, .jpeg, .png, .gif, .webp
- Dokumentnachricht: .pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml usw.
Antwort
Beispielantwort
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Komponentenname",
"content": {
"text": "Hallo, kann ich Ihnen irgendwie weiterhelfen?",
"audio": [
{
"audio": "http://gptbots.ai/example.mp3",
"transcript": "Transkribierter Audioinhalt"
}
]
}
}
],
"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,
"text_input_credits": 0.0,
"text_output_credits": 0.0,
"audio_input_credits": 0.0,
"audio_output_credits": 0.0
}
},
"human_trigger": true
}
Antwortbeispiel bei ausgelöster Übergabe an den menschlichen Kundenservice
Im Modus eigenes Helpdesk-System (Custom Helpdesk) ist human_trigger gleich true, wenn die aktuelle Antwort eine Übergabe an den menschlichen Kundenservice auslöst; existiert zugleich eine Übergabenotiz, wird zusätzlich ein handoff-Objekt zurückgegeben (bei fehlender Notiz erscheint dieses Feld nicht).
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": null,
"from_component_name": "AI Model-1",
"content": {
"text": "Sie werden mit einem menschlichen Kundenservice verbunden. Bitte warten Sie einen Moment.",
"audio": null
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 19
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 10
}
},
"credits": {
"total_credits": 0.0,
"text_input_credits": 0.0,
"text_output_credits": 0.0,
"audio_input_credits": 0.0,
"audio_output_credits": 0.0
}
},
"human_trigger": true,
"handoff": {
"note": "Übergabegrund: Der/die Nutzer:in äußerte zweimal in Folge Unzufriedenheit mit dem Erstattungsprozess und forderte eine Bearbeitung durch den menschlichen Kundenservice.\nGesprächszusammenfassung: Der/die Nutzer:in gab am 2. März eine Bestellung auf, erhielt nach dem Erstattungsantrag keine Erstattungsbenachrichtigung und hat die Bestellnummer 20260302-8891 bestätigt."
}
}
Erfolgreiche Antwort (Blocking)
⚠️ Im blocking-Antwortmodus ist die menschliche Übernahme nicht verfügbar, wenn Drittanbieter-Kundenservicesysteme wie LiveChat oder Intercom angebunden sind (Nachrichten der Kundenservice-Mitarbeiter:innen werden asynchron gesendet und müssen im webhook-Modus empfangen werden).
Bei Verwendung des eigenen Helpdesk-Systems (Custom Helpdesk) gilt diese Einschränkung nicht: Das Übergabesignal wird überhuman_trigger/handoffim Antworttext zurückgegeben, und die Nachrichten der Kundenservice-Mitarbeiter:innen werden von den Entwickler:innen selbst über diese Schnittstelle mitrole=human_agentgeschrieben.
| 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 | Ja |
| message_id | string | Eindeutige Kennung einer Nachricht innerhalb der Konversation. |
| create_time | long | Zeitstempel, zu dem diese Antwortnachricht generiert wurde. |
| output | JSON Array | Antwortinhalt des/der Agent:in. |
| from_component_branch | string | FlowAgent-Branch. |
| from_component_name | string | Name der vorgelagerten Komponente im FlowAgent. |
| content | object | Vom/von der KI-Agent:in beantworteter Nachrichteninhalt, derzeit text und audio. |
| human_trigger | boolean | Ob diese Antwort eine Übergabe an den menschlichen Kundenservice ausgelöst hat. false, wenn nicht ausgelöst. |
| handoff | object | Übergabeinformationen; nur vorhanden, wenn human_trigger gleich true ist und eine Übergabenotiz existiert. |
| note | string | Übergabenotiz (Übergabegrund + Gesprächszusammenfassung), maximal 2000 Zeichen. |
| ai_response | boolean | Wird in der Empfangsbestätigung reiner Archivierungsanfragen (ai_response=false oder mit role=human_agent) zurückgespiegelt, um zu bestätigen, dass die Nachricht als „nur archivieren“ erkannt wurde. |
| sender_role | string | Wird in der Empfangsbestätigung reiner Archivierungsanfragen zurückgespiegelt; Wert ist human_agent oder user, um die Rolle der archivierten Nachricht zu bestätigen. |
| usage | object | Details zum Ressourcenverbrauch. |
| tokens | JSON Array | Gesamtanzahl der in dieser Konversation verbrauchten Tokens. |
| total_tokens | integer | Gesamtzahl der für Ein- und Ausgabe verbrauchten Tokens in dieser Konversation. |
| prompt_tokens | integer | Für die Eingabe verbrauchte Tokens. |
| completion_tokens | integer | Für die Ausgabe verbrauchte Tokens. |
| prompt_tokens_details | object | Detaillierte Aufschlüsselung der für die Eingabe verbrauchten Tokens. |
| completion_tokens_details | object | Detaillierte Aufschlüsselung der für die Ausgabe verbrauchten Tokens. |
| credits | object | Gesamtverbrauchte Credits in dieser Konversation. |
| text_input_credits | double | Für Texteingaben verbrauchte Credits. |
| text_output_credits | double | Für Textausgaben verbrauchte Credits. |
| audio_input_credits | double | Für Audioeingaben verbrauchte Credits. |
| audio_output_credits | double | Für Audioausgaben verbrauchte Credits. |
Erfolgreiche Antwort (Streaming)
⚠️ Im streaming-Antwortmodus ist die menschliche Übernahme nicht verfügbar, wenn Drittanbieter-Kundenservicesysteme wie LiveChat oder Intercom angebunden sind (Nachrichten der Kundenservice-Mitarbeiter:innen werden asynchron gesendet und müssen im webhook-Modus empfangen werden).
Bei Verwendung des eigenen Helpdesk-Systems (Custom Helpdesk) gilt diese Einschränkung nicht: Der Übergabe-Trigger wird alscode:36 HumanTrigger-Frame gesendet, und die Übergabenotiz folgt unmittelbar danach alscode:107 HumanHandoffNote-Frame.
| Feld | Typ | Beschreibung |
|---|---|---|
| code | int | Nachrichtentyp-Code: 3-Text, 10-FlowAgent-Ausgabe, 0-Ende, 4-Nutzungsdaten, 39-Audionachricht, 36-Übergabe an den menschlichen Kundenservice, 107-Übergabenotiz. |
| message | string | Nachrichtentyp: Text, FlowOutput, End, HumanTrigger, HumanHandoffNote. |
| data | object | Antwortinhalt. |
- Beispiel für Textnachrichten-Streaming:
{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"Wie "}
{"code":3,"message":"Text","data":"kann "}
{"code":3,"message":"Text","data":"ich "}
{"code":3,"message":"Text","data":"helfen "}
{"code":3,"message":"Text","data":"Ihnen?"}
{"code":0,"message":"End","data":null}
- Beispiel für Audionachrichten-Streaming:
{"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"Hallo"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}
- Wird im Modus eigenes Helpdesk-System (Custom Helpdesk) eine Übergabe an den menschlichen Kundenservice ausgelöst, werden vor dem
End-Frame nacheinander der Übergabe-Trigger-Frame und der Übergabenotiz-Frame gesendet:
{"code":3,"message":"Text","data":"Sie werden mit einem menschlichen Kundenservice verbunden. Bitte warten Sie einen Moment."}
{"code":36,"message":"HumanTrigger","data":"HumanTrigger"}
{"code":107,"message":"HumanHandoffNote","data":{"note":"Übergabegrund: Der/die Nutzer:in äußerte zweimal in Folge Unzufriedenheit mit dem Erstattungsprozess und forderte eine Bearbeitung durch den menschlichen Kundenservice.\nGesprächszusammenfassung: Der/die Nutzer:in gab am 2. März eine Bestellung auf, erhielt nach dem Erstattungsantrag keine Erstattungsbenachrichtigung und hat die Bestellnummer 20260302-8891 bestätigt."}}
{"code":0,"message":"End","data":null}
Hinweis:
code: 36, message: "HumanTrigger"bedeutet, dass die aktuelle Antwort eine Übergabe an den menschlichen Kundenservice ausgelöst hat;dataist eine feste Kennungszeichenfolge.code: 107, message: "HumanHandoffNote"steht für die Übergabenotiz; ihredata-Struktur entspricht demhandoff-Feld in der blockierenden Antwort ({"note": "..."}).- Der
HumanHandoffNote-Frame wird nur gesendet, wenn eine Übergabenotiz existiert; ohne Notiz gibt es nur denHumanTrigger-Frame – ein leerer107-Frame tritt nicht auf. - Beide Frames werden stets vor dem
End-Frame (code: 0) gesendet.
Erfolgreiche Antwort (Webhook)
Nachdem Sie die Webhook-Adresse im Bereich „Integration-API“ konfiguriert haben, sendet das GPTBots-System die Nachrichten „Agent-Antwort“ und „Antwort des menschlichen Kundenservice“ an die Webhook-Adresse.
Für detaillierte Informationen zu Webhook-Nachrichten siehe Webhook-Nachrichtenempfang und menschlicher Übergabeservice.
⚠️ Im API-Modus müssen Sie den webhook-Antwortmodus verwenden, wenn der menschliche Übernahme-Service aktiviert ist, um die Antwortnachrichten des menschlichen Kundenservice zu empfangen.
Fehlerantwort
| Feld | Typ | Beschreibung |
|---|---|---|
| code | int | Fehlercode. |
| message | string | Fehlerdetails. |
Fehlerbeispiel
{
"code": 40000,
"message": "Ungültige Parameter",
"errors": [
{
"error_code": 40000,
"error_message": "Message user role type must have file or content."
}
],
"data": {
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "Basierend auf den erkennbaren Inhalten wurde Ihre Frage beantwortet……",
"audio": null
}
}
],
"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,
"text_input_credits": 0,
"text_output_credits": 0,
"audio_input_credits": 0,
"audio_output_credits": 0
}
}
}
}
Fehlercodes
| Code | Nachricht |
|---|---|
| 40000 | Ungültige Parameter |
| 40127 | Entwickler:innen-Authentifizierung fehlgeschlagen |
| 40356 | Konversation existiert nicht |
| 40358 | conversation_id stimmt nicht überein |
| 40364 | Agent:in unterstützt keinen Bildmodus |
| 50000 | Interner Systemfehler |
| 20040 | Frage-Längenlimit überschritten |
| 20022 | Unzureichende Credits |
| 20055 | API-Nutzung verboten, bitte prüfen Sie, ob der API-Schalter aktiviert ist |
