API serveur

L’API serveur permet à votre serveur de consulter les tickets, de les fermer, de récupérer des rapports, de définir qui voit le bot et de consulter les versions publiées. Chaque appel utilise votre clé secrète.

La spécification complète se trouve dans le fichier openapi.yaml (OpenAPI 3.1). Vous pouvez l’importer dans Postman ou Insomnia, ou l’utiliser pour générer un client. Les SDK serveur couvrent tous les points de terminaison de cette page.

Authentification

URL de base : https://api.kavchat.com. Envoyez la clé secrète sous forme de jeton Bearer. Elle reste sur votre serveur et n’est jamais envoyée au navigateur ni à l’application. Vous pouvez la remplacer sur la page Installation du tableau de bord.

curl

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

Réponses et erreurs

Chaque réponse est au format JSON et contient un champ success. Les erreurs comportent un code stable que votre code peut vérifier, ainsi qu’un message dans la langue indiquée par l’en-tête 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" }

Statut	Exemples de codes	Signification
400	`ticket_status_invalid`	Un paramètre ou un champ du corps de la requête est invalide.
401	`invalid_key`	La clé est absente, incorrecte ou a été remplacée.
404	`ticket_not_found`	Ce ticket n’existe pas dans cet espace de travail.

Points de terminaison

Méthode et chemin	Description
`GET /v1/server/workspace`	Informations sur l’espace de travail et clé publique
`GET /v1/server/tickets`	Liste des tickets, du plus récent au plus ancien
`GET /v1/server/tickets/{id}`	Un ticket avec sa transcription
`PUT /v1/server/tickets/{id}/status`	Fermeture ou réouverture d’un ticket
`GET /v1/server/reports`	Conversations, résultats, points d’abandon et questions sans réponse
`GET /v1/server/settings`	Paramètres du bot et public cible
`PUT /v1/server/settings`	Modification du public cible du bot
`GET /v1/server/releases`	Versions publiées

Espace de travail

GET /v1/server/workspace

Informations sur l’espace de travail, clé publique et 4 derniers caractères de la clé secrète (secretKeyHint). Un premier appel pratique pour vérifier que la clé fonctionne.

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

Liste des tickets

GET /v1/server/tickets

Les tickets ouverts depuis le chat, du plus récent au plus ancien.

Paramètre	Description
`status`	`open` ou `closed`. Sans ce paramètre, les tickets des deux statuts sont renvoyés.
`limit`	De 1 à 200, avec une valeur par défaut de 50.
`before`	Pour la pagination : le `number` du dernier ticket déjà reçu.

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 correspond au champ sub du jeton d’identité lorsque l’utilisateur a été identifié. phone est au format E.164.

Un ticket

GET /v1/server/tickets/{id}

Un ticket avec sa transcription complète, dans la même structure qu’un élément de la liste. Si l’identifiant n’existe pas, une erreur 404 est renvoyée avec ticket_not_found.

curl

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

Fermeture ou réouverture

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

Corps de la requête : { "status": "closed" } ou { "status": "open" }. Renvoie le ticket mis à jour.

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" }'

Rapports

GET /v1/server/reports

Les conversations et leurs résultats (open, answered, contact, abandoned), un récapitulatif par script, les étapes où les utilisateurs quittent la conversation et les questions auxquelles le bot n’a pas trouvé de réponse, regroupées. from et to sont des dates et heures au format ISO 8601. Par défaut : les 30 derniers jours.

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" }
    ]
  }
}

Paramètres du bot

GET /v1/server/settings

Le public cible, la liste des utilisateurs de test et l’apparence du bot.

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" }]
  }
}

Modification du public cible

PUT /v1/server/settings

Seuls audience (off, testers ou all) et testerPhones (jusqu’à 50 numéros) peuvent être modifiés ici. Les autres paramètres se modifient dans le tableau de bord. La réponse contient les paramètres, comme avec 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" }'

Versions

GET /v1/server/releases

Les 50 dernières versions publiées, de la plus récente à la plus ancienne. Le champ restoredFrom est présent lorsque la version résulte de la restauration d’une version antérieure.

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" }]
    }
  ]
}

Avec un SDK serveur

Les mêmes appels sont disponibles dans chaque SDK. Les erreurs sont levées sous forme d’erreurs API avec status, code, message et details. Lorsqu’aucune réponse n’a été reçue (timeout ou network_error), status vaut 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();

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

API client

Le widget et les SDK mobiles utilisent une autre interface publique, sous /v1/client/{publicKey} : elle renvoie la version publiée, enregistre le déroulement de la conversation et ouvre des tickets à partir du formulaire de contact. Elle est également accessible aux visiteurs non identifiés et ne nécessite que la clé publique. Vous n’avez pas besoin de l’appeler vous-même. Elle est décrite dans le fichier openapi.yaml pour compléter la documentation.