Abrufen der letzten Aktivität eines Agenten

Abrufen der Anzahl neuer Sitzungen und Benutzeranfragen eines oder mehrerer Agenten in den letzten N Minuten, geeignet für regelmäßige Aktivitätsprüfungen. Es können maximal 50 Agenten auf einmal abgefragt werden.

Anfrageart

GET

Aufrufadresse

https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity

Authentifizierung beim Aufruf

Verwenden Sie die Basic-Authentifizierung mit DevKey / DevSecret auf Kontoebene: Authorization: Basic ${BASIC_TOKEN}, wobei ${BASIC_TOKEN} die Base64-Codierung von DevKey:DevSecret ist.

Der aufrufende Account muss Mitglied der Organisation von org_id sein und über die Berechtigung „Usage anzeigen“ verfügen (Organisations-Owner und Administratoren haben diese standardmäßig), außerdem muss er Zugriff auf den Agenten haben: Agenten-Ersteller, Organisations-Owner oder Mitglieder, denen diese Agenten- (oder alle Agenten-) Berechtigung zugewiesen wurde.
Bitte verwenden Sie die Adresse des Rechenzentrums, in dem sich die Organisation befindet. ${endpoint} entnehmen Sie aus Organisationsliste abfragen zurückgegebene region (SG → sg, TH → th, JP → jp). Aufrufe anderer Rechenzentren führen zu „kein Mitglied dieser Organisation“.

Aufrufhäufigkeit

Mit jedem Entwickler-Schlüssel kann diese Schnittstelle höchstens 60 Mal pro Minute aufgerufen werden.
Jeder Aufruf wird gleichzeitig auf das Minutenkontingent der „Statistics-API“ des Organisationstarifs angerechnet und teilt sich dieses Kontingent mit Agent API Key-Aufrufen der Statistik-Schnittstellen.
Abfrageergebnisse werden 30 Sekunden zwischengespeichert. Es wird empfohlen, einmal pro Minute aufzurufen und mehrere Agenten in einer Anfrage zu kombinieren.

Anfrage

Anfragebeispiel

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

Dieser Codeblock im schwebenden Fenster

Anforderungsheader

Feld	Typ	Beschreibung
Authorization	Basic ${BASIC_TOKEN}	Verwendet Basic Token nach `DevKey:DevSecret` Base64.

Anforderungsparameter

Feld	Typ	Pflicht	Beschreibung
org_id	String	Ja	Organisations-ID.
agent_id	String	Ja	Agent-ID, mehrere mit englischem Komma getrennt, maximal 50, doppelte werden nur einmal gezählt. Workflow wird nicht unterstützt.
minutes	Integer	Nein	Statistik für die letzten wie viele Minuten, 1 bis 60, Standard ist 5.

Antwort

Antwortbeispiel

{ "code": 0, "message": "OK", "data": { "minutes": 5, "window_start": 1790664900000, "window_end": 1790665200000, "agents": [ { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "new_conversation_count": 3, "new_message_count": 27 } ] } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "minutes": 5,
        "window_start": 1790664900000,
        "window_end": 1790665200000,
        "agents": [
            {
                "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
                "new_conversation_count": 3,
                "new_message_count": 27
            }
        ]
    }
}

Dieser Codeblock im schwebenden Fenster

Erfolgreiche Antwort

Feld	Typ	Beschreibung
minutes	Integer	Länge des Statistikfensters (in Minuten).
window_start	Long	Startpunkt des Fensters (Millisekunden-Zeitstempel).
window_end	Long	Endpunkt des Fensters (Millisekunden-Zeitstempel, exklusiv).
agents[].agent_id	String	Agent-ID, Reihenfolge entspricht `agent_id` in der Anfrage.
agents[].new_conversation_count	Long	Anzahl der neuen, bereits geführten Unterhaltungen innerhalb des Fensters.
agents[].new_message_count	Long	Anzahl der vom Benutzer im Fenster gestellten Fragen, exkl. AI-Antworten.

Fehlgeschlagene Antwort

Feld	Typ	Beschreibung
code	Integer	Fehlercode.
message	String	Fehlerdetails.

Fehlercodes

HTTP-Statuscode entspricht den ersten drei Ziffern des Fehlercodes, z. B. 40000 entspricht 400, 40100 entspricht 401, 403132 entspricht 403.

Fehlercode	Beschreibung
40000	Parameterfehler, z. B. fehlende erforderliche Parameter oder ungültige Parameterwerte.
40001	Zu häufig aufgerufen: Dieser Entwicklerschlüssel hat das Minutenlimit dieses Endpunkts überschritten.
40008	Überschreitung des Minutenlimits des Organisationstarifs für „Statistik-APIs“.
40010	Schnittstelle vorübergehend geschlossen, bitte später erneut versuchen.
40100	Keine Berechtigung: Fehlende Nutzungsansichtserlaubnis oder keine Berechtigung zur Ansicht des Agents (einschließlich, dass der Agent nicht zur Organisation gehört).
40105	Kein Mitglied dieser Organisation oder Verwendung einer Adresse eines anderen Rechenzentrums.
40324	DevKey oder DevSecret ist falsch.
40378	Agent wurde gelöscht.
403132	Ungültiger Zeitbereich: Die Startzeit ist nicht früher als die Endzeit oder überschreitet den maximalen Abfragebereich.

Statistikumfang

Beide Zahlen müssen berücksichtigt werden: Sitzungen über Instant-Messaging-Kanäle verwenden denselben Chatverlauf bis zu 60 Minuten ohne neue Nachrichten. Auch aktive Kanal-Agenten können längere Zeit keine neuen Sitzungen haben, nur neue Sitzungen zu betrachten, würde fälschlicherweise als inaktiv gelten.
Statistikbereich: Nur Kanäle im Entwicklungsbereich werden gezählt, einschließlich API, Freigabeseiten, Webeinbettungen, Bubble-Komponenten, LiveDesk sowie alle Instant-Messaging- und Telefonkanäle; nicht eingeschlossen sind Debug-Vorschauen im Entwicklungsbereich und die Nutzung des Agenten im Workspace.
Aktualisierungsfrequenz: Echtzeitberechnung.