Chat API-referentie

Authenticatie

Elke aanvraag wordt geauthenticeerd met de API-sleutel van je werkruimte, verzonden in de X-API-Key-header (of als api_key-parameter). Sleutels zien eruit als ck_live_.... Behandel de sleutel als een wachtwoord - iedereen die hem heeft, kan berichten versturen die aan je werkruimte worden gefactureerd. Roteer hem op elk moment via Instellingen -> API-toegang; de vorige sleutel werkt onmiddellijk niet meer.

Een bericht versturen

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Parameters:

• message (string) - het bezoekersbericht. Verplicht tenzij er files zijn bijgevoegd.
• ticket_id (string, optioneel) - zet een bestaand gesprek voort. Laat weg om een nieuw gesprek te starten.
• visitor_email / visitor_name (string, optioneel) - voeg contactgegevens toe aan het ticket.
• files (multipart, optioneel) - bijlagen van de bezoeker. Vereist een abonnement met bestandsuploads.

Antwoord

De aanroep geeft 202 Accepted terug zodra het bericht is opgeslagen; het AI-antwoord wordt asynchroon gegenereerd.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Geef data.ticket_id mee als ticket_id bij de volgende aanroep om het gesprek voort te zetten. Om het AI-antwoord te ontvangen, abonneer je via WebSocket (ActionCable) op het kanaal met sleutel data.id - dezelfde bezoekershash die de ingesloten widget gebruikt.

Gesprekken lezen

Haal tickets en hun berichten op met dezelfde X-API-Key. Elk lees-endpoint is beperkt tot je workspace en beschikbaar in het Business-abonnement.

• GET /api/v1/chat/tickets - toont tickets, nieuwste eerst. Queryparameters: status, limit (max. 100), offset. Retourneert tickets en pagination.
• GET /api/v1/chat/tickets/:id - een enkel ticket.
• GET /api/v1/chat/tickets/:id/messages - de berichten van een ticket op volgorde, elk met role, content en attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Ratelimieten en quota

Aanvragen worden beperkt tot ongeveer 20 per minuut per sleutel (en per IP). Elk gegenereerd antwoord put ook uit het maandelijkse berichtentegoed van je abonnement; zodra dit op is, geeft het endpoint een 200 terug met data.limit_reached: true in plaats van een antwoord te genereren.

Fouten

• 401 - geen API-sleutel opgegeven.
• 404 - de sleutel komt met geen enkele werkruimte overeen (bijv. na rotatie).
• 403 plan_upgrade_required - de werkruimte heeft geen Business-abonnement.
• 403 - het abonnement is inactief, of de aanvraag kwam van een domein dat niet is toegestaan door de instellingen van de widget.
• 422 - het bericht ontbreekt (en er zijn geen bestanden bijgevoegd).