Kavchat by maxsave
Dokumentationsmenü

Server-API

Mit der Server-API kann Ihr Server Tickets lesen und schließen, Berichte abrufen, festlegen, wer den Bot sieht, und veröffentlichte Versionen anzeigen. Jeder Aufruf erfolgt mit Ihrem geheimen Schlüssel.

Die vollständige Spezifikation finden Sie in der Datei openapi.yaml (OpenAPI 3.1). Sie können sie in Postman oder Insomnia importieren oder daraus einen Client generieren. Die Server-SDKs decken alle Endpunkte auf dieser Seite ab.

Authentifizierung

Basis-URL: https://api.kavchat.com. Senden Sie den geheimen Schlüssel als Bearer-Token. Er bleibt auf Ihrem Server und wird niemals an den Browser oder die App gesendet. Sie können ihn auf der Seite Installation im Dashboard ersetzen.

curl
curl https://api.kavchat.com/v1/server/workspace \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Accept-Language: en"

Antworten und Fehler

Jede Antwort ist JSON mit einem Feld success. Fehler enthalten einen festen code, den Ihr Code prüfen kann, sowie eine message in der Sprache des Headers Accept-Language (he, en, ar, ru, es, fr, de, pt, it, tr).

JSON
// success
{ "success": true, "data": { ... } }

// error
{ "success": false, "code": "ticket_not_found", "message": "Request not found" }
StatusBeispielcodesBedeutung
400ticket_status_invalidEin Parameter oder ein Feld im Anfrage-Body ist ungültig.
401invalid_keyDer Schlüssel fehlt, ist falsch oder wurde ersetzt.
404ticket_not_foundDieses Ticket existiert nicht im Arbeitsbereich.

Endpunkte

Methode und PfadBeschreibung
GET /v1/server/workspaceDetails zum Arbeitsbereich und öffentlicher Schlüssel
GET /v1/server/ticketsTicketliste, neueste zuerst
GET /v1/server/tickets/{id}Einzelnes Ticket mit Gesprächsprotokoll
PUT /v1/server/tickets/{id}/statusTicket schließen oder erneut öffnen
GET /v1/server/reportsGespräche, Ergebnisse, Abbruchstellen und unbeantwortete Fragen
GET /v1/server/settingsBot-Einstellungen und Zielgruppe
PUT /v1/server/settingsZielgruppe des Bots ändern
GET /v1/server/releasesVeröffentlichte Versionen

Arbeitsbereich

GET /v1/server/workspace

Details zum Arbeitsbereich, der öffentliche Schlüssel und die letzten 4 Zeichen des geheimen Schlüssels (secretKeyHint). Eignet sich als erster Aufruf, um zu prüfen, ob der Schlüssel funktioniert.

curl
curl https://api.kavchat.com/v1/server/workspace \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Accept-Language: en"
Response
{
  "success": true,
  "data": {
    "id": "6718e9a1f0c2a4b5c6d7e8f9",
    "name": "Example Store",
    "locale": "en",
    "defaultCountry": "IL",
    "plan": "premium",
    "publicKey": "pk_live_Ab12Cd34Ef56Gh78Ij90Kl",
    "secretKeyHint": "a1b2",
    "webhookUrl": "https://example.com/kavchat/webhook"
  }
}

Ticketliste

GET /v1/server/tickets

Die über den Chat erstellten Tickets, neueste zuerst.

ParameterBeschreibung
statusopen oder closed. Ohne diesen Parameter werden beide zurückgegeben.
limitZwischen 1 und 200, Standard: 50.
beforeZum Blättern: der Wert number des letzten bereits abgerufenen Tickets.
curl
curl "https://api.kavchat.com/v1/server/tickets?status=open&limit=50" \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"

# next page: pass the number of the last ticket you received
curl "https://api.kavchat.com/v1/server/tickets?status=open&limit=50&before=120" \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": [
    {
      "id": "6718f0c2a4b5c6d7e8f90123",
      "number": 128,
      "status": "open",
      "name": "Dana",
      "email": "dana@example.com",
      "phone": "+972501234567",
      "userId": "user_123",
      "topicId": "billing",
      "topicName": "Billing",
      "scriptId": "returns",
      "sessionId": "k3J9xQ2mP7aB",
      "message": "My refund has not arrived yet.",
      "transcript": [
        { "from": "bot", "text": "Hi! How can I help?", "stepId": "start", "at": "2026-10-25T09:14:02.000Z" }
      ],
      "createdAt": "2026-10-25T09:15:40.000Z",
      "updatedAt": "2026-10-25T09:15:40.000Z"
    }
  ]
}

userId entspricht dem Feld sub aus dem Identitätstoken, wenn der Nutzer identifiziert wurde. phone hat das Format E.164.

Einzelnes Ticket

GET /v1/server/tickets/{id}

Ein einzelnes Ticket mit vollständigem Gesprächsprotokoll, im selben Format wie ein Listeneintrag. Wenn die ID nicht existiert, wird der Fehler 404 mit ticket_not_found zurückgegeben.

curl
curl https://api.kavchat.com/v1/server/tickets/6718f0c2a4b5c6d7e8f90123 \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"

Schließen oder erneut öffnen

PUT /v1/server/tickets/{id}/status

Anfrage-Body: { "status": "closed" } oder { "status": "open" }. Gibt das aktualisierte Ticket zurück.

curl
curl -X PUT https://api.kavchat.com/v1/server/tickets/6718f0c2a4b5c6d7e8f90123/status \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "closed" }'

Berichte

GET /v1/server/reports

Gespräche und ihre Ergebnisse (open, answered, contact, abandoned), eine Zusammenfassung pro Skript, die Schritte, bei denen Nutzer aussteigen, sowie gruppierte Fragen, auf die der Bot keine Antwort gefunden hat. from und to enthalten Datum und Uhrzeit im Format ISO 8601. Standard: die letzten 30 Tage.

curl
curl "https://api.kavchat.com/v1/server/reports?from=2026-10-01T00:00:00Z&to=2026-10-25T00:00:00Z" \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": {
    "from": "2026-10-01T00:00:00.000Z",
    "to": "2026-10-25T00:00:00.000Z",
    "totals": { "sessions": 940, "open": 12, "answered": 801, "contact": 64, "abandoned": 63 },
    "byScript": [
      { "scriptId": "returns", "name": "Returns", "sessions": 310, "open": 3, "answered": 270, "contact": 22, "abandoned": 15 }
    ],
    "dropOff": [
      { "scriptId": "returns", "scriptName": "Returns", "stepId": "label", "stepText": "Print the return label from...", "count": 9 }
    ],
    "unmatched": [
      { "groupKey": "gift card balance", "sample": "how do I check my gift card balance", "count": 17, "lastAt": "2026-10-24T18:02:11.000Z" }
    ]
  }
}

Bot-Einstellungen

GET /v1/server/settings

Die Zielgruppe, die Liste der Testnutzer und das Erscheinungsbild des Bots.

curl
curl https://api.kavchat.com/v1/server/settings \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": {
    "enabled": true,
    "audience": "testers",
    "testerPhones": ["+972501234567"],
    "botName": "Support",
    "avatarText": "S",
    "avatarImageUrl": null,
    "subtitle": "Replies instantly",
    "primaryColor": "#2563eb",
    "position": "end",
    "contactTopics": [{ "id": "billing", "name": "Billing" }]
  }
}

Zielgruppe ändern

PUT /v1/server/settings

Hier können Sie nur audience (off, testers oder all) und testerPhones (bis zu 50 Telefonnummern) ändern. Alle anderen Einstellungen bearbeiten Sie im Dashboard. Die Antwort enthält die Einstellungen, wie bei GET.

curl
curl -X PUT https://api.kavchat.com/v1/server/settings \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience": "testers", "testerPhones": ["+972501234567"] }'

# open the bot to everyone
curl -X PUT https://api.kavchat.com/v1/server/settings \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience": "all" }'

Versionen

GET /v1/server/releases

Die letzten 50 veröffentlichten Versionen, neueste zuerst. Das Feld restoredFrom ist enthalten, wenn mit der Version eine frühere Version wiederhergestellt wurde.

curl
curl https://api.kavchat.com/v1/server/releases \
  -H "Authorization: Bearer $KAVCHAT_SECRET_KEY"
Response
{
  "success": true,
  "data": [
    {
      "version": 7,
      "note": "New returns flow",
      "publishedAt": "2026-10-20T11:30:00.000Z",
      "scripts": [
        { "id": "opening", "kind": "opening", "name": "Welcome" },
        { "id": "returns", "kind": "topic", "name": "Returns" }
      ]
    },
    {
      "version": 6,
      "note": "Restore",
      "restoredFrom": 4,
      "publishedAt": "2026-10-12T08:05:00.000Z",
      "scripts": [{ "id": "opening", "kind": "opening", "name": "Welcome" }]
    }
  ]
}

Mit einem Server-SDK

In jedem SDK stehen dieselben Aufrufe zur Verfügung. Fehler werden als API-Fehler mit status, code, message und details ausgelöst. Wenn keine Antwort eingegangen ist (timeout oder network_error), ist status gleich 0.

Node.js
await kavchat.getWorkspace();
await kavchat.listTickets({ status: 'open', limit: 50, before: 120 });
await kavchat.getTicket(id);
await kavchat.setTicketStatus(id, 'closed');
await kavchat.getReports({ from: new Date('2026-01-01'), to: new Date() });
await kavchat.getSettings();
await kavchat.updateSettings({ audience: 'testers', testerPhones: ['+972501234567'] });
await kavchat.listReleases();
Python
kavchat.get_workspace()
kavchat.list_tickets(status="open", limit=50, before=120)
kavchat.get_ticket(ticket_id)
kavchat.set_ticket_status(ticket_id, "closed")
kavchat.get_reports(from_=datetime(2026, 1, 1, tzinfo=timezone.utc), to=datetime.now(timezone.utc))
kavchat.get_settings()
kavchat.update_settings(audience="testers", tester_phones=["+972501234567"])
kavchat.list_releases()
PHP
$kavchat->getWorkspace();
$kavchat->listTickets(status: 'open', limit: 50, before: 120);
$kavchat->getTicket($id);
$kavchat->setTicketStatus($id, 'closed');
$kavchat->getReports(new DateTimeImmutable('2026-01-01'), new DateTimeImmutable());
$kavchat->getSettings();
$kavchat->updateSettings(audience: 'testers', testerPhones: ['+972501234567']);
$kavchat->listReleases();
Java
kavchat.getWorkspace();
kavchat.listTickets(ListTicketsParams.create().status(TicketStatus.OPEN).limit(50).before(120));
kavchat.getTicket(id);
kavchat.setTicketStatus(id, TicketStatus.CLOSED);
kavchat.getReports(Instant.parse("2026-01-01T00:00:00Z"), Instant.now());
kavchat.getSettings();
kavchat.updateSettings(UpdateSettingsParams.create().audience(Audience.TESTERS).testerPhones(List.of("+972501234567")));
kavchat.listReleases();
.NET
await kavchat.GetWorkspaceAsync();
await kavchat.ListTicketsAsync(new ListTicketsOptions { Status = TicketStatus.Open, Limit = 50, Before = 120 });
await kavchat.GetTicketAsync(id);
await kavchat.SetTicketStatusAsync(id, TicketStatus.Closed);
await kavchat.GetReportsAsync(DateTimeOffset.UtcNow.AddDays(-7), DateTimeOffset.UtcNow);
await kavchat.GetSettingsAsync();
await kavchat.UpdateSettingsAsync(new UpdateSettingsRequest { Audience = Audience.Testers, TesterPhones = ["+972501234567"] });
await kavchat.ListReleasesAsync();
Go
client.GetWorkspace(ctx)
client.ListTickets(ctx, kavchat.ListTicketsParams{Status: kavchat.TicketOpen, Limit: 50, Before: 120})
client.GetTicket(ctx, id)
client.SetTicketStatus(ctx, id, kavchat.TicketClosed)
client.GetReports(ctx, kavchat.ReportParams{From: time.Now().AddDate(0, 0, -7)})
client.GetSettings(ctx)
client.UpdateSettings(ctx, kavchat.UpdateSettingsParams{Audience: kavchat.AudienceTesters, TesterPhones: []string{"+972501234567"}})
client.ListReleases(ctx)
Ruby
kavchat.get_workspace
kavchat.list_tickets(status: "open", limit: 50, before: 120)
kavchat.get_ticket(id)
kavchat.set_ticket_status(id, "closed")
kavchat.get_reports(from: Time.now - 7 * 86_400, to: Time.now)
kavchat.get_settings
kavchat.update_settings(audience: "testers", tester_phones: ["+972501234567"])
kavchat.list_releases

Client-API

Das Widget und die mobilen SDKs nutzen eine zusätzliche öffentliche Schnittstelle unter /v1/client/{publicKey}: Sie gibt die veröffentlichte Version zurück, protokolliert den Gesprächsverlauf und erstellt Tickets aus dem Kontaktformular. Sie ist auch für Gäste zugänglich und benötigt nur den öffentlichen Schlüssel. Sie müssen sie nicht selbst aufrufen. Der Vollständigkeit halber ist sie in der Datei openapi.yaml beschrieben.