Je eerste API-integratie

Voorbereiden

Maak in Instellingen → API-keys een key met conversations:read. Kopieer het organisatie-ID dat daar wordt getoond. Bewaar de key als SUPPORTWHALE_API_KEY in een secretmanager op je server. Vervang de organisatieplaceholder hieronder door het echte ID. De productie-URL is https://api.supportwhale.com/v1; lokaal gebruik je normaal http://localhost:3000/v1.

Lezen en pagineren

Het antwoord is een JSON-array, oplopend gesorteerd op id. De after-cursor is exclusief: gebruik het laatste id van de vorige pagina. Een lege of korte pagina beëindigt paginering. Deze voorbeelden lezen alleen gesprekken en versturen geen berichten.

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;
}

Een bericht versturen

Gebruik de POST-actie voor gespreksberichten in de referentie met conversations:write. Geef body en een unieke clientMessageId mee. Herhalen met hetzelfde ID, dezelfde key en hetzelfde gesprek geeft het oorspronkelijke bericht terug. Zet internal op true voor een privénotitie voor je team. Berichttekst is maximaal 5000 tekens; dit endpoint ondersteunt geen bijlagen. Voor lezen is een aparte lees-scope nodig. Interne notities zijn vertrouwelijk en mogen niet naar bezoekers worden doorgestuurd.

Fouten afhandelen

Log nooit Authorization-headers. Bij 401 moet je de key corrigeren of vervangen; controleer bij 403 de organisatie en scopes. Wacht bij 429 het aantal seconden in retryAfter in het JSON-antwoord (momenteel 60). Gebruik oplopende wachttijden bij tijdelijke serverfouten. De voorbeelden stoppen bewust bij een fout, zodat deze niet op een leeg zoekresultaat lijkt.