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

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

Dieser Codeblock im schwebenden Fenster

Wichtige Hinweise:

Für die Inhaltstypen image, audio und document können Sie entweder Base64-kodierte Daten oder URL-Links verwenden – beide Formate werden unterstützt.

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: blocking: Warten, bis die Ausführung abgeschlossen ist, und Ergebnis zurückgeben (kann bei zu langer Ausführung abgebrochen werden). streaming: Antwort wird per SSE (Server-Sent Events) gestreamt. webhook: Nachrichten von Agent:in und menschlichem Kundenservice werden an die auf der API-Seite konfigurierte Webhook-URL gesendet.
messages	JSON Array	Ja	Nachrichteninhalt, unterstützt die Rollen `user` und `assistant` zur Kontextbildung. user message: Mindestens eine erforderlich, die neueste Nutzernachricht muss zuletzt stehen. assistant message: Entwickler:innen können Assistant-Nachrichten als Kontext einfügen.
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 } } }

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

Dieser Codeblock im schwebenden Fenster

Erfolgreiche Antwort (Blocking)

⚠️ Der menschliche Übergabeservice ist im blocking-Antwortmodus nicht verfügbar.

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`.
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)

⚠️ Der menschliche Übergabeservice ist im streaming-Antwortmodus nicht verfügbar.

Feld	Typ	Beschreibung
code	int	Nachrichtentyp-Code: 3-Text, 10-FlowAgent-Ausgabe, 0-Ende, 4-Nutzungsdaten, 39-Audionachricht.
message	string	Nachrichtentyp: Text, FlowOutput, End.
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}

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

Dieser Codeblock im schwebenden Fenster

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}

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

Dieser Codeblock im schwebenden Fenster

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.
webhook config
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 } } } }

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

Dieser Codeblock im schwebenden Fenster

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