# Analytics & Reports API Diese schreibgeschützten Endpunkte ermöglichen es Ihnen, die Aktivitäten Ihres Kontos in Ihre eigenen Dashboards und Berichte zu importieren: Nachrichten-Ereigniszahlen, Kreditverbrauch, KI-Ausgaben sowie dieselben Diagramme und Erkenntnisse, die das In-App-Dashboard anzeigt. Dieser Leitfaden behandelt: - **Zusammenfassung** — Zähler für das Nachrichtenvolumen (gesendet, zugestellt, gelesen, beantwortet, gebucht, erstellte Kontakte, Credits). - **Credits** — ein detailliertes, paginiertes Protokoll der Kreditnutzung mit Summen und Aufschlüsselungen. - **KI-Kosten** — eine tägliche Zusammenfassung der KI-Ausgaben. - **Metrik-Reihen** — eine für Diagramme geeignete Zeitreihe für eine oder mehrere Metriken, gruppiert nach Kampagne, Kanal, KI-Agent oder Nummer. - **Konversationsergebnisse** — wie Konversationen endeten, basierend auf dem von der KI zugewiesenen Ergebnis-Tag. - **Dashboard-Erkenntnisse** und **Dashboard-KI-Erkenntnisse** — die vollständigen Daten hinter dem In-App-Dashboard, einschließlich der von der KI verfassten Zusammenfassungen. - **Entitätsaktivität** — die Zeitleiste eines einzelnen Kontakts, Deals oder einer Aufgabe. - **Aggregierte Ereigniszahlen** — eine ältere, in camelCase gehaltene Form der Zusammenfassung, die für bestehende Integrationen beibehalten wurde. Jeder Endpunkt auf dieser Seite erfordert einen exakten Gültigkeitsbereich, nicht beide: Übergeben Sie maximal einen von `campaign_id` (veraltet) oder `agent_id`, sofern der Endpunkt dies akzeptiert. Das Senden beider führt zu `400`, und eine ID, die nicht zu Ihrem Konto gehört, gibt `404` statt `403` zurück, sodass die IDs anderer Konten nicht erraten werden können. Alle unten aufgeführten Pfade sind relativ zur API-Basis-URL: ``` https://api.youraiconnector.com/v1 ``` Jede Anfrage muss authentifiziert sein. Siehe [Authentifizierung](authentication.md) für die vier akzeptierten Methoden. Die Beispiele hier verwenden den `X-API-Key`-Header (und eine Abfrageparameter-Form für cURL). --- ## Datumsbereich Alle drei Endpunkte akzeptieren dieselben optionalen Datumsfilter: | Parameter | Beschreibung | |---|---| | `from` | Beginn des Bereichs, `YYYY-MM-DD`, inklusive. Standardmäßig vor 30 Tagen. | | `to` | Ende des Bereichs, `YYYY-MM-DD`, inklusive. Standardmäßig heute. | Daten werden in UTC interpretiert. Der Bereich ist standardmäßig auf die **letzten 30 Tage** eingestellt und auf **366 Tage** begrenzt — ein größerer Bereich gibt `400` zurück. `from` darf nicht nach `to` liegen. ### Das `truncated`-Flag Die Endpunkte **Zusammenfassung** und **Kredite** begrenzen die Anzahl der Datensätze, die eine einzelne Anfrage scannt. Wenn Ihr Bereich so umfangreich ist, dass dieses Limit erreicht wird, enthält die Antwort `"truncated": true`. Wenn Sie dies sehen, basieren die Zahlen auf einem teilweisen Scan — schränken Sie Ihren Datumsbereich ein (oder blättern Sie mit einem kleineren Fenster), um vollständige Zahlen zu erhalten. ::: note **Hinweis:** Kosten- und Token-Angaben sind nur für KI-Aufrufe enthalten, die über Ihre eigenen Anbieter-API-Schlüssel abgerechnet werden. Wenn Kostenangaben für Ihr Konto ausgeblendet sind, setzt die Antwort `"costs_redacted": true` und die Kostenfelder werden als null zurückgegeben. ::: --- ## Zusammenfassung des Nachrichtenvolumens Gibt aggregierte Zähler für Nachrichtenereignisse für Ihr Konto zurück, sowohl als Bereichssummen als auch als tägliche Reihe. Jeder Tag im Bereich erscheint in `by_date` — ruhige Tage werden mit Null aufgefüllt. Filtern Sie optional auf eine einzelne Kampagne mit `campaign_id`. `GET /analytics/summary` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `from` | Nein | Bereichsbeginn, `YYYY-MM-DD`. | | `to` | Nein | Bereichsende, `YYYY-MM-DD`. | | `campaign_id` | Nein | Nur Ereignisse zählen, die zu dieser Kampagne gehören. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/summary", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31"}, ) data = res.json() ``` **Antwort** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "totals": { "total": 1240, "sent": 800, "delivered": 760, "read": 540, "replied": 210, "booked": 35, "contact_created": 120, "credits_spent": 412.5, "credits_recharged": 500 }, "by_date": [ { "date": "2026-05-01", "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contact_created": 4, "credits_spent": 13.5, "credits_recharged": 0 } ], "truncated": false } ``` Jeder Eintrag in `by_date` verfügt über dieselben Zählerfelder wie `totals`, zuzüglich eines `date`. Wenn Sie eine `campaign_id` übergeben, die nicht zu Ihrem Konto gehört, lautet die Antwort `404` mit `{ "success": false, "error": "Campaign not found" }`. --- ## Kreditverbrauch Gibt den Kreditverbrauch über den Bereich zurück: eine paginierte Liste einzelner Datensätze sowie Bereichssummen und Aufschlüsselungen nach Grund und Kampagne. `GET /analytics/credits` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `from` | Nein | Bereichsbeginn, `YYYY-MM-DD`. | | `to` | Nein | Bereichsende, `YYYY-MM-DD`. | | `campaign_id` | Nein | Nur Nutzung einbeziehen, die dieser Kampagne zugerechnet wird. | | `limit` | Nein | Seitengröße für `records`, 1–100. Standardwert ist 50. | | `cursor` | Nein | Übergeben Sie den `next_cursor` der vorherigen Seite, um die nächste Seite abzurufen. | > **Anpassungen vs. Verbrauch:** Saldoänderungen wie Boni, Planverlängerungen und Korrekturen sind von `totals` und den Aufschlüsselungen **ausgeschlossen** – sie stellen keinen tatsächlichen Verbrauch dar. Sie erscheinen weiterhin in der `records`-Liste, markiert mit `"is_adjustment": true`. **Summen und Aufschlüsselungen erscheinen nur auf der ersten Seite** (wenn kein `cursor` angegeben ist). Auf späteren Seiten werden `totals`, `by_reason`, `by_reason_cost` und `by_campaign` als `null` zurückgegeben – nur das `records`-Array wird fortgesetzt. Dies vermeidet ein erneutes Scannen des gesamten Bereichs für jede Seite. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31", limit: "50", }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); // To page: pass data.next_cursor as ?cursor on the next request, until it is null. ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/credits", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50}, ) data = res.json() # To page: pass data["next_cursor"] as cursor on the next request, until it is None. ``` **Antwort** (erste Seite) ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "totals": { "credits_used": 412.5, "cost_usd": 1.284512, "records": 318 }, "by_reason": { "AI Message": 380.0, "Campaign Message": 32.5 }, "by_reason_cost": { "AI Message": 1.284512, "Campaign Message": 0 }, "by_campaign": { "Spring Promo": 250.0, "Reactivation": 162.5 }, "records": [ { "id": "rec_abc123", "amount": 1, "timestamp": "2026-05-31T14:02:11.000Z", "reason": "AI Message", "is_adjustment": false, "campaign_id": "campaign123", "campaign_name": "Spring Promo", "contact_id": "contact456", "contact_name": "Jane Smith", "credit_type": "ai", "custom_keys_used": false, "description": null, "cost_usd": 0, "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_creation_tokens": 0, "ai_model": null, "request_id": null, "is_test": false } ], "next_cursor": "rec_abc123", "costs_redacted": false, "truncated": false } ``` **Feldhinweise:** - `amount` — für den Datensatz berechnete Kredite. Null für Datensätze, die über Ihren eigenen Provider-API-Schlüssel abgerechnet werden. - `is_adjustment` — `true` für Saldoänderungen (von Summen/Aufschlüsselungen ausgeschlossen). - `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`, `ai_model`, `request_id` — nur ausgefüllt bei Datensätzen, die über Ihren eigenen Provider-API-Schlüssel abgerechnet werden; ansonsten null oder `null`. - `is_test` — `true` für Playground-/Testläufe, die niemals in Rechnung gestellt werden. - `next_cursor` — der Cursor für die nächste Seite oder `null`, wenn keine weiteren Datensätze vorhanden sind. --- ## KI-Kosten-Rollup Gibt das tägliche KI-Ausgaben-Rollup für Ihr Konto zurück. Dies liest voraggregierte Tagessummen, ist also auch über lange Zeiträume hinweg schnell. Jeder Tag im Bereich erscheint in `days` – ruhige Tage werden mit Null aufgefüllt. `GET /analytics/ai-cost` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `from` | Nein | Start des Bereichs, `YYYY-MM-DD`. | | `to` | Nein | Ende des Bereichs, `YYYY-MM-DD`. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/ai-cost", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31"}, ) data = res.json() ``` **Antwort** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "totals": { "total_usd": 12.4821, "byok_usd": 12.4821, "platform_usd": 0, "calls": 4210 }, "days": [ { "date": "2026-05-01", "total_usd": 0.4012, "byok_usd": 0.4012, "platform_usd": 0, "input_usd": 0.18, "output_usd": 0.19, "cache_creation_usd": 0.02, "cache_read_usd": 0.0112, "calls": 140, "by_provider": { "anthropic": 0.4012 } } ], "costs_redacted": false } ``` **Feldhinweise:** - `byok_usd` — Ausgaben, die über Ihre eigenen API-Schlüssel des Anbieters abgerechnet werden. - `platform_usd` — Der Teil der Ausgaben, der über die Plattform und nicht über Ihren eigenen Schlüssel abgewickelt wurde. - `input_usd`, `output_usd`, `cache_creation_usd`, `cache_read_usd` — Die Kostenkomponenten, aus denen sich `total_usd` zusammensetzt. - `by_provider` — Ausgaben in USD, sortiert nach dem Namen des KI-Anbieters. - USD-Beträge werden nur für Konten zurückgegeben, die ihren eigenen Anbieterschlüssel verwenden. Bei Konten, die mit Guthaben bezahlen, sind alle USD-Felder null und `costs_redacted` ist `true` (die Anzahl der Aufrufe bleibt sichtbar). --- ## Metrik-Reihen Gibt eine oder mehrere Metrik-Zeitreihen in einem Aufruf zurück, optional gruppiert nach bis zu zwei Dimensionen – der Endpunkt zur Anbindung eines Diagramms. Eine einzelne Anfrage kann "gesendet und beantwortet pro Tag, pro Kanal, für diese Kampagne" beantworten, ohne dass ein Aufruf pro Kampagne erforderlich ist. `GET /analytics/series` Jede Antwort enthält ein `labels`-Array (die Zeitachse, über den gesamten Bereich mit Nullen gefüllt) und einen Eintrag in `series` pro Gruppe, wobei jeder ein Array pro angeforderter Metrik enthält, das auf `labels` ausgerichtet ist. Reihen nach `limit` werden nicht verworfen – sie werden in `other_bucket` zusammengefasst, berechnet als Bereichssumme abzüglich der zurückgegebenen Reihen, sodass ein gerendertes Diagramm immer Ihre tatsächlichen Zahlen ergibt; `truncated` ist `true`, wann immer dies geschieht. Woher die Zahlen stammen: `sent`, `delivered`, `read` und `replied` stammen aus Nachrichtendatensätzen, die den Kanal und die sendende Nummer enthalten. `booked`, `contact_created` und `credits_spent` stammen aus dem Ereignisstrom, der keine sendende Nummer enthält, daher landen diese Metriken im `null`-Nummern-Bucket, wenn Sie nach `number` gruppieren. | Parameter | Erforderlich | Beschreibung | |---|---|---| | `from` | Nein | Bereichsbeginn, `YYYY-MM-DD`. Standardmäßig vor 30 Tagen. | | `to` | Nein | Bereichsende, `YYYY-MM-DD`. Standardmäßig heute. | | `metrics` | Nein | Durch Kommas getrennte Liste aus `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. Standardmäßig `sent,replied`. Eine unbekannte Metrik gibt `400` zurück. | | `group_by` | Nein | Durch Kommas getrennte Liste von bis zu zwei Dimensionen aus `date`, `campaign`, `channel`, `agent`, `number`. `date` wird akzeptiert, hat aber keine Auswirkung – jede Antwort enthält bereits die Zeitachse. Für eine einzelne kontoweite Reihe weglassen. | | `granularity` | Nein | `day` (Standard), `week` oder `month`. Wochen-Buckets beginnen am Montag, Monats-Buckets am 1. | | `limit` | Nein | Wie viele Reihen zurückgegeben werden sollen, bevor der Rest in `other_bucket` zusammengefasst wird, 1–50. Standardmäßig 12. | | `campaign_id` | Nein | Nur Aktivitäten zählen, die zu dieser Kampagne gehören. Veraltet; bevorzugen Sie `agent_id`. | | `agent_id` | Nein | Nur Aktivitäten zählen, die zu diesem KI-Agenten gehören. | | `channel` | Nein | Nur Aktivitäten auf diesem Kanal zählen, zum Beispiel `whatsapp`. | Der Datumsbereich dieses Endpunkts ist auf **92 Tage** begrenzt (enger als die 366-Tage-Begrenzung, die an anderer Stelle auf dieser Seite verwendet wird). **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31", metrics: "sent,replied,booked", group_by: "campaign,channel", limit: "10", }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/series", headers={"X-API-Key": "YOUR_API_KEY"}, params={ "from": "2026-05-01", "to": "2026-05-31", "metrics": "sent,replied,booked", "group_by": "campaign,channel", "limit": 10, }, ) data = res.json() ``` **Antwort** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "granularity": "day", "labels": ["2026-05-01", "2026-05-02"], "group_by": ["campaign", "channel"], "metrics": ["sent", "replied", "booked"], "series": [ { "key": { "campaign_id": "campaign123", "campaign_name": "Spring Promo", "channel": "whatsapp" }, "total": 812, "metrics": { "sent": [40, 35], "replied": [12, 9], "booked": [2, 1] } } ], "other_bucket": { "series_count": 6, "total": 340, "metrics": { "sent": [18, 20], "replied": [5, 6], "booked": [0, 1] } }, "truncated": true } ``` **Feldhinweise:** - `key` — die Identität einer Reihe. Nur die Schlüssel für die angeforderten `group_by`-Dimensionen sind vorhanden; eine Dimension, deren Wert für eine Zeile unbekannt ist (eine Nachricht ohne Kampagne, ein Ereignis ohne Kanal), wird als `null` zurückgegeben, anstatt verworfen zu werden, sodass die Reihen immer noch die Summen ergeben. - `other_bucket` — `null`, wenn nichts zusammengefasst wurde. - Dieser Endpunkt gibt `503` mit `"error_code": "analytics_unavailable"` zurück, wenn die Berichtsdatenbank für Ihr Konto nicht antworten kann, anstatt ein `200` voller Nullen – ein auf Null gesetztes Diagramm würde als Tatsache gelesen werden. --- ## Konversationsergebnisse Gibt zurück, wie Konversationen über einen Datumsbereich endeten: eine tägliche Anzahl für jedes von der KI zugewiesene Ergebnis-Tag sowie Bereichssummen für Antworten, Buchungen, Übergaben an einen Menschen und Konversationen, die die KI nie klassifiziert hat. `GET /analytics/outcomes` Übergeben Sie `group_by=tag`, um die Zeitachse zusammenzufassen und nur Bereichssummen pro Tag zu erhalten – in diesem Modus ist `labels` leer und das `counts`-Array jedes Tags ist leer, während `total` weiterhin gefüllt ist. | Parameter | Erforderlich | Beschreibung | |---|---|---| | `from` | Nein | Bereichsbeginn, `YYYY-MM-DD`. Standardmäßig vor 30 Tagen. | | `to` | Nein | Bereichsende, `YYYY-MM-DD`. Standardmäßig heute. | | `campaign_id` | Nein | Zählt nur Konversationen mit Kontakten, die sich aktuell in dieser Kampagne befinden. Veraltet; bevorzugen Sie `agent_id`. | | `agent_id` | Nein | Zählt nur Ergebnisse, die zu diesem KI-Agenten gehören. | | `group_by` | Nein | `date` (Standard) behält die täglichen Zählungen bei; `tag` fasst diese zu Bereichssummen zusammen. | Der Datumsbereich dieses Endpunkts ist auf **92 Tage** begrenzt. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/outcomes", headers={"X-API-Key": "YOUR_API_KEY"}, params={"from": "2026-05-01", "to": "2026-05-31"}, ) data = res.json() ``` **Antwort** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "group_by": "date", "labels": ["2026-05-01", "2026-05-02"], "by_tag": [ { "tag": "interested", "total": 84, "counts": [3, 5] }, { "tag": "not_interested", "total": 40, "counts": [1, 2] }, { "tag": null, "total": 12, "counts": [0, 1] } ], "totals": { "sessions": 260, "replied": 210, "booked": 35, "human_alerted": 18, "unresolved": 12 } } ``` **Feldhinweise:** - `by_tag[].tag` — `null` für Konversationen, denen die KI kein Ergebnis-Tag zugewiesen hat. - `totals.human_alerted` — Konversationen, die an einen Menschen übergeben wurden; dies wird bei jeder Übergabe protokolliert und wurde bisher von keinem Endpunkt bereitgestellt. - Gleiches `503`/`analytics_unavailable`-Verhalten wie bei der Metrik-Serie, wenn die Reporting-Datenbank keine Antwort geben kann. --- ## Dashboard-Einblicke Gibt die vollständige Dashboard-Nutzlast für einen Datumsbereich in einem Aufruf zurück: eine Heatmap der Antwortrate nach Wochentag und Uhrzeit, die Kampagnen-Bestenliste, das Volumen pro Kanal, exakte Summen pro Verbindung, tägliche Metrik-Aufschlüsselungen (kontoweit, pro Kanal und pro Nummer), Herkunft der Kontakte, Antwortzeit im Posteingang und einen Feed mit kürzlichen Aktivitäten. Dies ist die umfangreichste Reporting-Nutzlast der API — sie treibt das In-App-Dashboard direkt an. `GET /analytics/dashboard-insights` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `startDate` | Ja | Bereichsbeginn, `YYYY-MM-DD`. | | `endDate` | Ja | Bereichsende, `YYYY-MM-DD`. | | `campaignId` | Nein | Berücksichtigt nur Aktivitäten, die zu dieser Kampagne gehören (`campaign_id` ebenfalls akzeptiert). Veraltet; bevorzugen Sie `agent_id`. | | `agent_id` | Nein | Berücksichtigt nur Aktivitäten, die zu diesem KI-Agenten gehören (`agentId` ebenfalls akzeptiert). Innerhalb eines Agenten-Bereichs wird die Kampagnen-Bestenliste nur aus den Aktivitäten dieses Agenten erstellt. | Dieser Endpunkt verwendet `startDate`/`endDate` (nicht `from`/`to`), da er seine Implementierung mit dem In-App-Dashboard teilt. Der Bereich ist auf 92 Tage begrenzt und wird **gekürzt, nicht abgelehnt**, wenn er breiter ist. > **Null bedeutet nicht verfügbar, nicht null.** Mehrere Blöcke (`numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`) werden aus der Reporting-Datenbank berechnet und geben `null` zurück, wenn diese für Ihr Konto keine Antwort liefern kann. Rendern Sie einen `null`-Block nicht als leeres Diagramm. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/dashboard-insights", headers={"X-API-Key": "YOUR_API_KEY"}, params={"startDate": "2026-05-01", "endDate": "2026-05-31"}, ) data = res.json() ``` **Antwort** (gekürzt — diese Nutzlast ist groß; siehe die [API-Referenz](reference.md) für das vollständige Schema) ```json { "success": true, "data": { "heatmap": { "buckets": [ { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 } ] }, "topCampaigns": [ { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 } ], "channelVolume": [ { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" } ], "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 }, "activityFeed": [ { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" } ], "numberStats": null, "channelDailySeries": null, "metricDailyBreakdown": null, "contactsByCountry": null, "ai_human_split": null } } ``` **Feldhinweise:** - `heatmap.buckets[].weekday` — `0` ist Sonntag bis `6` ist Samstag. - `numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`, `ai_human_split` — jeder ist unabhängig `null`, wenn die Reporting-Datenbank für Ihr Konto nicht verfügbar ist; alle anderen Blöcke werden weiterhin zurückgegeben. --- ## KI-Dashboard-Einblicke Gibt drei kurze, von der KI verfasste Einblicke über die Nachrichtenübermittlung des Kontos über einen Datumsbereich zurück: ein Erfolg, ein Punkt zur Beobachtung und ein Tipp — Sätze, die Sie direkt in einen Bericht kopieren können, anstatt Zahlen, die Sie noch interpretieren müssen. Ausschließlich aus den eigenen Nachrichtenmetriken des Kontos generiert. `GET /analytics/dashboard-ai-insights` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `startDate` | Ja | Bereichsbeginn, `YYYY-MM-DD`. | | `endDate` | Ja | Bereichsende, `YYYY-MM-DD`. | Dieser Endpunkt ist kontoübergreifend – er erfordert keinen Kampagnen- oder Agenten-Geltungsbereich. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights", headers={"X-API-Key": "YOUR_API_KEY"}, params={"startDate": "2026-05-01", "endDate": "2026-05-31"}, ) data = res.json() ``` **Antwort** ```json { "success": true, "data": { "insights": [ { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." }, { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." }, { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." } ] } } ``` Fehlende `startDate` oder `endDate` führen zu `400`. --- ## Zeitstrahl der Entitätsaktivitäten Gibt die Aktivitäten eines einzelnen Kontakts, Deals oder einer Aufgabe als einen Zeitstrahl zurück, beginnend mit dem Neuesten: Was ist wann passiert, über Nachrichten, Termine, Notizen und Statusänderungen hinweg. Verwenden Sie dies, um die Frage „Was ist mit dieser Person passiert?“ zu beantworten, ohne mehrere Listen-Endpunkte zusammenführen zu müssen. `GET /analytics/entity-activity` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `entityType` | Ja | `contact`, `deal` oder `task`. | | `entityId` | Ja | ID des Datensatzes, dessen Zeitstrahl zurückgegeben werden soll. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" }); const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/analytics/entity-activity", headers={"X-API-Key": "YOUR_API_KEY"}, params={"entityType": "contact", "entityId": "contact456"}, ) data = res.json() ``` **Antwort** ```json { "success": true, "data": { "items": [ { "id": "evt_9", "kind": "appointment_booked", "at": "2026-05-31T14:02:11.000Z", "label": "Booked an appointment for June 3", "detail": "Consultation call, 30 minutes" }, { "id": "evt_8", "kind": "message_replied", "at": "2026-05-31T13:58:02.000Z", "label": "Replied: \"Yes, that time works\"" } ] } } ``` Ein fehlendes oder ungültiges `entityType`/`entityId` führt zu `400`. Eine Entität, die in Ihrem Konto nicht existiert, führt zu `404`, sodass die IDs anderer Konten nicht erraten werden können. --- ## Aggregierte Ereignisanzahlen (Legacy) Gibt dieselben aggregierten Ereignisanzahlen zurück wie die [Zusammenfassung des Nachrichtenvolumens](#message-volume-summary), jedoch im camelCase-Format (`contactCreated` statt `contact_created`, `byDate` statt `by_date`), für das einige ältere Integrationen entwickelt wurden. Bevorzugen Sie `/analytics/summary` für neue Integrationen – dieser Endpunkt existiert nur, damit das In-App-Dashboard und die API dieselbe Implementierung nutzen. `GET /analytics/aggregate` | Parameter | Erforderlich | Beschreibung | |---|---|---| | `startDate` | Nein | Bereichsbeginn, ISO-Datum oder Datum-Uhrzeit. Standardmäßig dasselbe Fenster, das `/analytics/summary` verwendet. | | `endDate` | Nein | Bereichsende, ISO-Datum oder Datum-Uhrzeit. | | `campaignId` | Nein | Zählt nur Ereignisse, die zu dieser Kampagne gehören (`campaign_id` ebenfalls akzeptiert). Legacy; bevorzugen Sie `agent_id`. | | `agent_id` | Nein | Zählt nur Ereignisse, die zu diesem KI-Agenten gehören (`agentId` ebenfalls akzeptiert). | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **Antwort** ```json { "success": true, "data": { "from": "2026-05-01", "to": "2026-05-31", "total": 1240, "byAnalyticType": { "total": 1240, "sent": 800, "delivered": 760, "read": 540, "replied": 210, "booked": 35, "contactCreated": 120, "creditsSpent": 412.5, "creditsRecharged": 500 }, "byDate": [ { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } } ] } } ``` --- ## Rollup für Agentur-Unterkonten --- ## Analytics-API-Fehler Analytics-Endpunkte geben das Standard-Fehler-Envelope zurück: ```json { "success": false, "error": "Date range too large. Maximum is 366 days." } ``` An einem Analyse-Endpunkt führen ein ungültiges Datumsformat oder ein Fenster außerhalb des zulässigen Bereichs zu `400`, und ein unbekanntes `campaign_id` oder `agent_id` führt zu `404`. Das Senden von sowohl `campaign_id` als auch `agent_id` an einen Endpunkt, der eines von beiden akzeptiert, ist ebenfalls ein `400` – übergeben Sie maximal eines. Die reinen PG-Reporting-Endpunkte (Metrik-Serien, Konversationsergebnisse, Agentur-Rollup) geben `503` mit `"error_code": "analytics_unavailable"` zurück, anstatt ein `200` voller Nullen, wenn die Reporting-Datenbank für Ihr Konto keine Antwort geben kann – versuchen Sie es in Kürze erneut. Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann – `401`, `403` (Ihr Plan beinhaltet keinen API-Zugriff oder bei einem Agentur-Rollup ist Ihr Konto kein Agentur-/Entwickler-Konto), `429` (Ratenbegrenzung) und `500` – sind mit Hinweisen zum erneuten Versuch unter [Fehler & Paginierung](errors-and-pagination.md) aufgeführt. --- ## Nächste Schritte - [Authentifizierung](authentication.md) — die vier Möglichkeiten zur Authentifizierung einer Anfrage. - [Fehler & Ratenbegrenzungen](errors-and-pagination.md) — Statuscodes und das Limit von 300 Anfragen/Min. - [Kampagnen-API](campaigns.md) — die Kampagnen, nach denen diese Zahlen gefiltert werden können.