Öffentliche API Beta

Unterhaltungen mit Handlungsbedarf finden

Filtere nach awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority oder tagIds. awaitingReply ignoriert interne Notizen; unread bezieht sich auf das authentifizierte Teammitglied. unassigned bedeutet: keine einzelne zuständige Person, auch wenn ein Team zugewiesen ist. Labels passen, wenn eine der angegebenen IDs zutrifft.

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

Sortiere nach waitingSince, lastMessageAt, createdAt oder geschäftlicher Priorität mit der Richtung asc oder desc. Bei Gleichstand entscheidet die ID. Ohne Angabe gelten compact=false und snoozed=any. In REST akzeptiert tagIds kommagetrennte IDs; MCP akzeptiert auch ein Array. waitingSince beginnt mit der ersten eingehenden Nachricht nach der letzten Antwort; Nachfragen und interne Notizen setzen den Wert nicht zurück. Führe diesen Scan der Warteschlange regelmäßig aus, auch wenn kein Webhook eintrifft, damit alte Threads wieder auftauchen.

Aufholen, ohne den Posteingang neu zu lesen

Nutze GET /api/v1/sync mit conversations:read. Der dauerhafte Feed enthält Änderungen an Unterhaltungen, Labels, Nachrichten, Kontakteigenschaften, Gedächtnis-Einträgen sowie Löschvorgänge. Jede Payload braucht zusätzlich ihre eigene Lese-Berechtigung: Nachrichtentexte brauchen messages:read, Gedächtnis-Einträge contact-memory:read. Eingeschränkte Zugangsdaten erhalten nur erlaubte Kanäle.

1. Starte ohne Cursor, folge nextCursor, bis hasMore false ist, und speichere diesen Cursor.
2. Lies die aktuellen Unterhaltungs- und Kontaktlisten sowie den Verlauf, den du für deinen Ausgangszustand brauchst.
3. Spiele ab dem gespeicherten Cursor erneut ab, um Änderungen während dieses Lesens aufzufangen. Verarbeite jede Seite und speichere dann nextCursor.

Dedupliziere anhand der Ereignis-id: Die Wiedergabe erfolgt mindestens einmal, nachgelagerte Aktionen brauchen also einen eigenen Duplikatschutz. Eine Anfrage ohne Cursor deckt die letzte Stunde ab, keinen vollständigen Snapshot. Ereignisse werden 30 Tage aufbewahrt; HTTP 410 resync_required heißt: neu initialisieren. Initialisiere auch neu, nachdem du Berechtigungen oder Kanalzugriff erweitert hast. Verwende limit bis 100 und maxBodyChars bis 10.000 (Standard 500). Setze compact=true für die Nachrichtenfelder textPreview/textTruncated mit maximal 200 Zeichen statt body/bodyTruncated. Webhooks können einen Agent wecken; der Feed bleibt auch ohne Webhook-Abonnements oder bei einem Rückstau in der Webhook-Zustellung verfügbar.

Prüfungen einmal festhalten und das Ergebnis teilen

Bevor du eine Untersuchung wiederholst, lies list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Speichere ein Ergebnis mit record_conversation_check (PUT auf denselben Pfad) und gib key, result, checkedBy und optional eine reference für die Karten-ID oder URL an. Zum Beispiel: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny speichert die authentifizierte actorId und den Zeitstempel checkedAt. Wird ein key erneut verwendet, ersetzt das nur diese Prüfung; es ist der aktuelle Stand, kein Verlaufsprotokoll. Lesen braucht conversations:read, Schreiben conversations:write, beides beschränkt auf den Kanal der Unterhaltung. Diese Aufrufe senden keine Antwort und markieren die Anfrage nicht als beantwortet.

Arbeit im Stapel zuweisen und aktualisieren

Finde aktive, zuweisbare Teammitglieder und Teams mit GET /api/v1/members and /teams (members:read). Die Antworten enthalten Verfügbarkeit und tatsächlichen Kanalzugriff, aber keine E-Mail-Adressen. Mit conversations:write änderst du status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds oder removeTagIds.

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

Round-Robin wählt ein verfügbares Teammitglied, das Zugriff auf den Kanal der Unterhaltung hat. Gibt es kein passendes Mitglied, liefert eine einzelne Aktualisierung 409 und ein Stapel-Eintrag schlägt fehl. Jeder Stapel akzeptiert bis zu 100 eindeutige IDs und wendet pro Unterhaltung einen Patch atomar an. Prüfe jedes { id, ok, error? }-Ergebnis; einzelne Einträge können fehlschlagen. Stapel unterliegen dem normalen anfragebasierten Rate-Limit, ohne Gewichtung nach Anzahl der Einträge.

Kundenkontext mit Sonny AI teilen

Liste, speichere und entferne Gedächtnis-Einträge zu Kontakten mit contact-memory:read/write. Gib sowohl contactId als auch eine zugängliche sourceId an; der Kontakt muss auf dieser Quelle eine Unterhaltung haben. Gespeicherte Fakten durchlaufen dieselbe Validierung, Duplikatbehandlung und dieselben Limits wie in der App und werden als manuelle Gedächtnis-Einträge gespeichert.

Lies Eigenschaftsdefinitionen unter /api/v1/properties und lies oder setze Werte unter /api/v1/contacts/{contactId}/properties. MCP stellt list_properties, get_contact_properties und set_contact_property bereit. Dafür sind contacts:read/write und Zugriff auf alle Kanäle nötig. Gib genau eine propertyId oder einen propertyName an, mit einem String-Wert oder null zum Leeren. Text-, Zahlen-, URL-, Datums- und Auswahlwerte werden gegen die Felddefinition geprüft.

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

Eigenschaftsfilter vergleichen exakt gespeicherte Strings; mehrere Eigenschaften müssen alle zutreffen. Per API geschriebene Werte sind im Co-Pilot und im Autoresponder als API-Daten gekennzeichnet. Bestehende Regeln für verifizierte Kunden und Quellen gelten weiterhin. Normale, manuell gepflegte interne Feldwerte bleiben aus diesem KI-Kontext ausgeschlossen.

Dieselben Berichte lesen wie dein Team

Rufe mit reporting:read GET /api/v1/reporting/{kind} auf. Verfügbare Arten sind overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads und online-hours. overview kombiniert Anzahlen, Antwortzeiten und CSAT. Filter sind period (1–365 Tage, Standard 30), from/to als Paar (to ist exklusiv), granularity (day/month), source, assigneeId und tagId. source akzeptiert all, all-chat, all-email, website:{id} oder email:{id}.

Berichte nutzen dieselben Abfragen wie das Dashboard und die aktuellen Zugriffsprüfungen. knowledge berücksichtigt Datum und erlaubte Kanäle, unabhängig von gewählter Quelle, zuständiger Person oder Label. online-hours misst die Anwesenheit zugänglicher Teammitglieder im Arbeitsbereich; die Anzahl der Unterhaltungen bleibt auf Kanäle beschränkt. Die bestehenden /csat-Endpunkte behalten ihre eigene Berechtigung csat:read und können eine andere Grundgesamtheit beschreiben.

Dateien mit Antworten oder internen Notizen senden

Erteile attachments:write und lade für eine Unterhaltung eine Datei bis 25 MB hoch. POST /api/v1/attachments erwartet die Multipart-Felder file und conversationId. Die Antwort enthält eine id und expiresAt. Übergib innerhalb einer Stunde bis zu 10 attachmentIds an eine Antwort oder Notiz. Jeder Upload ist an deinen Benutzer und die Unterhaltung gebunden und kann nur einmal verwendet werden. Ungenutzte Uploads werden nach Ablauf entfernt.

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

Antworten erfordern messages:send; interne Notizen erfordern messages:write und erreichen niemals Kunden. Nachrichten nur mit Anhängen werden unterstützt. E-Mail-Antworten enthalten Dateien bis zur E-Mail-Größengrenze und Download-Links für den Rest; Offline-Chat-E-Mails enthalten Datei-Links. Links in E-Mails bleiben nutzbar, solange der Anhang existiert, sodass Empfänger sie auch später öffnen können. Wer die E-Mail weiterleitet, teilt den Zugriff auf diese Dateien. Prüfe emailDeliveryStatus auf Zustellfehler.

Autorisierte Nachrichten-Abrufe enthalten downloadUrl, downloadExpiresAt, aiStatus, aiDescription und aiExtractedText sowie videoTranscripts für verlinkte Videos (Loom, Vimeo und andere). Download-Links gelten 15 Minuten; lies die Nachricht erneut für frische Links. Neue Uploads über API/MCP werden privat gespeichert. Ältere Anhänge bleiben öffentlich und sind mit access=legacy_public gekennzeichnet: Ihre ursprüngliche URL läuft nicht ab. Das Lesen einer Nachricht startet die Bildauswertung, wenn der Arbeitsbereich Sonny AI hat. Bildauswertungen und Video-Transkripte sind kurz nach Eingang einer Nachricht fertig: Solange noch welche laufen, beginnt die Antwort mit readsInProgress, dessen nextStep den genauen nächsten Aufruf angibt. Übergib waitSeconds (bis 30), um in einer einzigen Anfrage darauf zu warten. Kundenseitige Widget- und Echtzeit-Nachrichten enthalten nie Extraktionen oder Transkripte.