CSAT- und Sitzungsexporte - Chatarmin CX Docs

Mit der Public API von Chatarmin CX prüfst du einzelne Umfrageergebnisse oder übernimmst erfasste Agenten-Login-Intervalle in dein Berichtssystem.

Zugriff und Limits

Erstelle unter Einstellungen → API einen API-Schlüssel mit zugewiesenem Support-Agenten. Sende ihn im Header cx-api-key. Beide schreibgeschützten Endpoints brauchen analytics:read und organisationsweiten Dashboard-Zugriff. Sie bieten keinen eingeschränkten Ersatzexport nur für dich oder dein Team.

Endpoint	Erforderliche Berechtigungen des zugewiesenen Agenten	Zusätzlicher API-Scope
`GET /public/v1/csat-surveys`	`dashboard.org_metrics` und `dashboard.ticket_csat`	`tickets:read` nur beim Anfordern von Kommentaren
`GET /public/v1/agent-sessions`	`dashboard.org_metrics` und `dashboard.other_agents_metrics`	Keiner zusätzlich zu `analytics:read`

Ein Filter auf deine eigene Agenten-ID hebt diese Anforderungen nicht auf. Beide Endpoints nutzen das Analytics-Limit von 10 Requests/Minute. Sie liefern JSON, kein CSV/Excel, und verändern weder Tickets noch Sitzungen oder versenden Umfragen. Für aggregierte Bewertungen, Antwortquoten und Online-Zeit nutze Berichte und Metriken.

CSAT-Umfragen exportieren

Wähle einen Datumsbezug: im Zeitraum eingereichte oder versendete Umfragen, einschließlich noch unbeantworteter. Berücksichtigt werden nur Umfragen auf vorhandenen, nicht gelöschten, nicht importierten Haupttickets im Workspace, keine Side Conversations.

Query-Parameter	Verhalten
`submitted_from`, `submitted_before`	Vollständiges Datumspaar für Einreichungen, alternativ das Versanddatumspaar.
`sent_from`, `sent_before`	Vollständiges Versanddatumspaar. Nicht mit Einreichungsparametern kombinieren.
`credited_agent_id`	Optionale exakte gespeicherte Agenten-ID der Umfrage. IDs sind undurchsichtige Strings, keine UUIDs oder Namen.
`score_lte`	Optionale ganze Zahl von 1 bis 5, einschließlich. Unbewertete Umfragen passen nicht zu diesem Filter.
`include_comments`	Exakt `true` oder `false`, standardmäßig `false`. `true` braucht zusätzlich `tickets:read`.
`limit`	Ganze Zahl von 1 bis 100, standardmäßig 50.
`cursor`	Optionales Fortsetzungstoken aus `pagination.next_cursor`.

Sende genau ein vollständiges Datumspaar als ISO-8601-Zeitpunkte mit Z oder explizitem Offset. Die Untergrenze ist inklusive, die Obergrenze exklusiv: [from, before). Die Obergrenze muss später und höchstens 90 × 24 Stunden nach der Untergrenze liegen. Anders als UNTIL in Berichtsabfragen ist before kein inklusiver Kalendertag. Unbekannte Query-Parameter werden abgelehnt. Starte mit einem kleinen Export nach Versanddatum ohne Kommentare:

curl --get 'https://api.armin.cx/public/v1/csat-surveys' \
  -H "cx-api-key: $CX_API_KEY" \
  --data-urlencode 'sent_from=2026-08-01T00:00:00Z' \
  --data-urlencode 'sent_before=2026-08-08T00:00:00Z' \
  --data-urlencode 'limit=100'

Für niedrige Bewertungen eines zugeordneten Agenten nutze Einreichungsdaten. Ersetze agent_example durch die Agenten-ID deines Workspaces. Fordere Kommentare nur an, wenn deine Integration Kundentext braucht und der Schlüssel den zusätzlichen Scope hat:

curl --get 'https://api.armin.cx/public/v1/csat-surveys' \
  -H "cx-api-key: $CX_API_KEY" \
  --data-urlencode 'submitted_from=2026-08-01T00:00:00Z' \
  --data-urlencode 'submitted_before=2026-08-08T00:00:00Z' \
  --data-urlencode 'credited_agent_id=agent_example' \
  --data-urlencode 'score_lte=3' \
  --data-urlencode 'include_comments=true' \
  --data-urlencode 'limit=100'

Umfrageergebnisse lesen

Das folgende erfundene Beispiel zeigt die Standardantwort ohne Kommentare. Ergebnisse sind aufsteigend nach dem gewählten Datumsfeld und dann der Umfrage-ID sortiert. score und submitted_at können null sein; auch ticket_number, credited_agent_id und credited_agent_name erlauben null.

{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "ticket_id": "22222222-2222-4222-8222-222222222222",
      "ticket_number": 1234,
      "credited_agent_id": "agent_example",
      "credited_agent_name": "Alex Example",
      "attribution_source": "survey_agent_id",
      "score": 3,
      "sent_at": "2026-08-01T09:00:00.000000Z",
      "submitted_at": "2026-08-02T10:00:00.000000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null },
  "meta": {
    "attribution": "Stored survey agent_id only; no read-time resolver fallback or historical reattribution. Missing credit remains unattributed.",
    "comments_included": false,
    "privacy": "Comments are customer-entered text and may contain personal data. They are opt-in and require tickets:read in addition to analytics:read."
  }
}

credited_agent_id ist die gespeicherte agent_id der Umfrage, keine beim Lesen abgeleitete Zuordnung zum Lösungsagenten oder Bearbeiter. Fehlende Zuordnung bleibt null mit attribution_source: "unattributed". Ein Name kann auch bei gespeicherter ID fehlen. Alte Umfragezuordnungen werden nicht umgeschrieben; historische Zuordnung beweist also nicht, wer das Ticket gelöst hat. Bei neuen Umfragen ohne explizit angegebene Zuordnung übernimmt die Standardzuordnung den erfassten solved_by des Tickets nur, wenn dessen aktueller Status resolved ist und dieser Lösungsagent im selben Workspace zulässig ist. Es gibt keinen Ersatz durch Bearbeiter oder Nachrichtenautor. Der alte Marker AI und aus der Analytics-Abrechnung ausgeschlossene KI-Agenten erhalten keine Standardzuordnung, auch nach dem Löschen eines ausgeschlossenen Agenten. Spätere Wiedereröffnung oder Neuzuweisung berechnet diesen Snapshot nicht neu. Die Standardzuordnung kann einen zulässigen KI-Lösungsagenten berücksichtigen; sie garantiert keine rein menschliche Zuordnung. Mit include_comments=true enthält jedes Element zusätzlich comment als String oder null, und meta.comments_included ist true. Sonst fehlt das Feld vollständig. Kommentare können personenbezogene Daten enthalten: Begrenze nachgelagerte Zugriffe und kopiere sie nicht in Logs. Der Export enthält keine Kundenkontaktdaten, Umfragetokens oder -links und keine Ticketinhalte.

Agentensitzungen exportieren

Prüfe Beginn, Ende und letzte Aktivität erfasster Login-Intervalle. Das sind die bestehenden veränderlichen Login-Sitzungen, kein neuer Speicher für Anwesenheitsereignisse. Der Export enthält keine gespeicherte Pausen- oder Ereignishistorie.

Query-Parameter	Verhalten
`from`, `before`	Erforderliche ISO-Zeitpunkte mit Offset, `[from, before)`, mit positiver Dauer von höchstens 90 × 24 Stunden.
`agent_id`	Optionale exakte Agenten-ID als undurchsichtiger String statt UUID oder Name.
`limit`	Ganze Zahl von 1 bis 100, standardmäßig 50.
`cursor`	Optionales Fortsetzungstoken.

curl --get 'https://api.armin.cx/public/v1/agent-sessions' \
  -H "cx-api-key: $CX_API_KEY" \
  --data-urlencode 'from=2026-08-01T00:00:00Z' \
  --data-urlencode 'before=2026-08-08T00:00:00Z' \
  --data-urlencode 'agent_id=agent_example' \
  --data-urlencode 'limit=100'

Der Endpoint wählt überlappende erfasste Intervalle, nicht nur im Zeitraum gestartete Sitzungen: session_start < before und entweder session_end > from oder session_end ist null. Eine Sitzung mit Ende genau bei from oder Beginn genau bei before wird ausgeschlossen. Eine vor dem Zeitraum gestartete Sitzung kann enthalten sein. Ursprüngliche Zeitpunkte bleiben ungekürzt; überlappende Datensätze werden nicht vereinigt. Diese erfundene Antwort enthält bewusst einen veralteten offenen Datensatz:

{
  "success": true,
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "agent_id": "agent_example",
      "session_start": "2026-07-31T23:00:00.000000Z",
      "session_end": null,
      "last_activity": "2026-08-01T00:15:00.000000Z",
      "updated_at": "2026-08-01T00:15:00.000000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null },
  "meta": {
    "date_filter": "recorded_interval_overlap",
    "order_by": "session_start,id",
    "stale_open_records_included": true,
    "mutable": true,
    "break_history_stored": false,
    "description": "Recorded intervals overlapping the requested range, with original timestamps retained. Stale open records are included; no end is inferred from last_activity. Null session_end is not proof of current availability. These are mutable login sessions, not presence or break events. Replica reads are eventually consistent; pagination is not a snapshot."
  }
}

session_end: null ist kein Beweis aktueller Verfügbarkeit. Prüfe last_activity separat; dieser Export leitet daraus nie ein Ende ab. Sitzungszeilen enthalten nur id, agent_id, session_start, session_end, last_activity und updated_at, niemals IP-Adressen, Browserdetails oder User-Agents. Für deduplizierte, auf den Zeitraum begrenzte Online-Sekunden je Zeitabschnitt frage agent_online_time über Berichte und Metriken ab, statt rohe Dauern zu summieren.

Export fortsetzen

Wenn pagination.has_more den Wert true hat, nutze pagination.next_cursor als cursor des nächsten Requests. Stoppe bei has_more: false. Behalte Schlüssel, Workspace, zugewiesenen Agenten, Scopes und alle Filter bei, auch limit und Kommentaroption. Änderungen machen den Cursor ungültig. Behandle Zeitstempel und Cursor als unveränderte Strings; ein aus einem Zeitstempel nachgebauter Cursor kann Präzision verlieren. Setze für die Abfrage niedriger Bewertungen oben NEXT_CURSOR auf das zurückgegebene Token und wiederhole dieselben Parameter:

curl --get 'https://api.armin.cx/public/v1/csat-surveys' \
  -H "cx-api-key: $CX_API_KEY" \
  --data-urlencode 'submitted_from=2026-08-01T00:00:00Z' \
  --data-urlencode 'submitted_before=2026-08-08T00:00:00Z' \
  --data-urlencode 'credited_agent_id=agent_example' \
  --data-urlencode 'score_lte=3' \
  --data-urlencode 'include_comments=true' \
  --data-urlencode 'limit=100' \
  --data-urlencode "cursor=$NEXT_CURSOR"

Sitzungen werden genauso paginiert, aufsteigend nach session_start und dann id. Keiner der Exporte ist ein eingefrorener Snapshot: Replikatlesevorgänge sind zeitverzögert konsistent, Umfrageantworten können später eintreffen und Sitzungsenden oder Aktivitätszeitpunkte sich während der Pagination ändern. Für laufende Importe lies begrenzte überlappende Zeitfenster erneut und aktualisiere nachgelagerte Zeilen über id; dies ist kein Änderungsereignis-Feed. Bei direkt angrenzenden Zeitfenstern wird das bisherige before zum nächsten from.

Fehlerbehebung

Antwort oder Symptom	Was du prüfen solltest
`401`	Sende einen gültigen API-Schlüssel.
`403 FORBIDDEN_SCOPE`	Prüfe zugewiesenen Agenten, `analytics:read`, beide nötigen Dashboard-Berechtigungen und `tickets:read` für Kommentare. Ein engerer Agentenfilter umgeht den organisationsweiten Zugriffsschutz nicht.
`400 VALIDATION_ERROR`	Nutze nur unterstützte Parameter und genau ein vollständiges Datumspaar, gültige Offsets, steigende Grenzen innerhalb von 90 Tagen und `limit` höchstens 100. Behalte Cursor-Parameter unverändert bei.
`429`	Warte auf `Retry-After`; siehe Rate Limits.
Export und Bericht ergeben unterschiedliche Summen	Prüfe Versand- gegen Einreichungsdatum, gespeicherte Zuordnung, aktuelle Ticketzulässigkeit, Replikataktualität und Abdeckung der Berichtsprojektion. Es sind keine austauschbaren Audit-Snapshots.

Scheitert ein kleiner gültiger Request weiterhin, kontaktiere den Support mit der request_id, dem Endpoint und bereinigten Filtern. Teile weder API-Schlüssel noch Kundenkommentare in Diagnose-Logs.

​Zugriff und Limits

​CSAT-Umfragen exportieren

​Umfrageergebnisse lesen

​Agentensitzungen exportieren

​Export fortsetzen

​Fehlerbehebung