Deine erste API-Integration

Vorbereiten

Erstelle unter Einstellungen → API-Schlüssel einen Schlüssel mit conversations:read. Kopiere die dort angezeigte Organisationskennung. Speichere den Schlüssel als SUPPORTWHALE_API_KEY in einem Secret-Manager auf deinem Server. Ersetze den Organisationsplatzhalter durch die echte Kennung. Die Produktionsbasis ist https://api.supportwhale.com/v1; lokal normalerweise http://localhost:3000/v1.

Lesen und paginieren

Die Antwort ist ein JSON-Array, aufsteigend nach id sortiert. Der after-Cursor ist exklusiv: Verwende die letzte id der vorherigen Seite. Eine leere oder kurze Seite beendet die Paginierung. Diese Beispiele lesen nur Gespräche und senden keine Nachrichten.

export SUPPORTWHALE_API_BASE="https://api.supportwhale.com/v1"
export SUPPORTWHALE_ORG_ID="your-organization-id"
# Load SUPPORTWHALE_API_KEY from your server's secret manager.
curl --fail-with-body \
  -H "Authorization: Bearer $SUPPORTWHALE_API_KEY" \
  "$SUPPORTWHALE_API_BASE/integrations/orgs/$SUPPORTWHALE_ORG_ID/conversations?limit=50"

// Server-side TypeScript; never ship the secret to a browser.
const base = process.env.SUPPORTWHALE_API_BASE!;
const org = process.env.SUPPORTWHALE_ORG_ID!;
const key = process.env.SUPPORTWHALE_API_KEY!;
let after = '';
for (;;) {
  const query = new URLSearchParams({ limit: '50' });
  if (after) query.set('after', after);
  const response = await fetch(
    `${base}/integrations/orgs/${encodeURIComponent(org)}/conversations?${query}`,
    { headers: { Authorization: `Bearer ${key}` }, redirect: 'error' },
  );
  if (!response.ok) throw new Error(`SupportWhale HTTP ${response.status}`);
  const page: { id: string; status: string; contactId: string }[] = await response.json();
  // Process this page in your trusted server application.
  if (page.length < 50) break;
  after = page[page.length - 1]!.id;
}

Nachricht senden

Verwende die POST-Aktion für Gesprächsnachrichten in der Referenz mit conversations:write. Übergib body und eine eindeutige clientMessageId. Wiederholungen mit derselben ID, demselben Schlüssel und Gespräch liefern die ursprüngliche Nachricht zurück. Setze internal auf true für eine private Teamnotiz. Nachrichtentext ist auf 5000 Zeichen begrenzt; Anhänge werden nicht unterstützt. Zum Lesen ist ein separater Lese-Scope nötig. Interne Notizen sind vertraulich und dürfen nicht an Besucher weitergegeben werden.

Fehler behandeln

Protokolliere niemals Authorization-Header. Bei 401 korrigiere oder ersetze den Schlüssel; bei 403 prüfe Organisation und Scopes. Warte bei 429 die im JSON-Feld retryAfter angegebenen Sekunden (derzeit 60). Verwende bei vorübergehenden Serverfehlern steigende Wartezeiten. Die Beispiele brechen bei Fehlern ausdrücklich ab, damit diese nicht wie leere Ergebnisse erscheinen.