Kavchat by maxsave
Menu delle guide

Server API

La Server API permette al tuo server di leggere e chiudere i ticket, recuperare i report, decidere chi vede il bot e consultare le versioni pubblicate. Ogni chiamata usa la chiave segreta.

La specifica completa è nel file openapi.yaml (OpenAPI 3.1). Puoi importarla in Postman o Insomnia, oppure usarla per generare un client. Gli SDK per server forniscono metodi per tutti gli endpoint di questa pagina.

Autenticazione

URL di base: https://api.kavchat.com. Invia la chiave segreta come bearer token. La chiave resta sul tuo server e non viene mai inviata al browser o all'app. Puoi sostituirla nella pagina Installazione della dashboard.

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

Risposte ed errori

Ogni risposta è in formato JSON e contiene un campo success. Gli errori hanno un code stabile che il tuo codice può verificare e un message nella lingua indicata dall'header 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" }
StatoCodici di esempioSignificato
400ticket_status_invalidUn parametro o un campo nel corpo della richiesta non è valido.
401invalid_keyLa chiave manca, è errata o è stata sostituita.
404ticket_not_foundIl ticket non esiste in questa area di lavoro.

Endpoint

Metodo e percorsoDescrizione
GET /v1/server/workspaceDettagli dell'area di lavoro e chiave pubblica
GET /v1/server/ticketsElenco dei ticket, dal più recente al meno recente
GET /v1/server/tickets/{id}Un ticket con la trascrizione
PUT /v1/server/tickets/{id}/statusChiusura o riapertura di un ticket
GET /v1/server/reportsConversazioni, esiti, punti di abbandono e domande senza risposta
GET /v1/server/settingsImpostazioni e pubblico del bot
PUT /v1/server/settingsModifica del pubblico del bot
GET /v1/server/releasesVersioni pubblicate

Area di lavoro

GET /v1/server/workspace

I dettagli dell'area di lavoro, la chiave pubblica e gli ultimi 4 caratteri della chiave segreta (secretKeyHint). Utile come prima chiamata per verificare che la chiave funzioni.

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

Elenco dei ticket

GET /v1/server/tickets

I ticket aperti dalla chat, dal più recente al meno recente.

ParametroDescrizione
statusopen o closed. Senza questo parametro vengono restituiti i ticket di entrambi gli stati.
limitDa 1 a 200, valore predefinito 50.
beforePer la paginazione: il number dell'ultimo ticket già ricevuto.
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 corrisponde al campo sub del token di identità quando l'utente è stato identificato. phone è in formato E.164.

Singolo ticket

GET /v1/server/tickets/{id}

Un ticket con la trascrizione completa, nella stessa struttura di un elemento dell'elenco. Se l'identificativo non esiste, viene restituito un errore 404 con ticket_not_found.

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

Chiusura o riapertura

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

Corpo della richiesta: { "status": "closed" } o { "status": "open" }. Restituisce il ticket aggiornato.

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

Report

GET /v1/server/reports

Le conversazioni e i relativi esiti (open, answered, contact, abandoned), un riepilogo per ogni script, i passaggi in cui gli utenti abbandonano la conversazione e le domande a cui il bot non ha trovato risposta, raggruppate. from e to sono data e ora in formato ISO 8601. L'intervallo predefinito è di 30 giorni, i più recenti.

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

Impostazioni del bot

GET /v1/server/settings

Il pubblico, l'elenco degli utenti di test e l'aspetto del 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" }]
  }
}

Modifica del pubblico

PUT /v1/server/settings

Qui puoi modificare solo audience (off, testers o all) e testerPhones (fino a 50 numeri). Le altre impostazioni si modificano nella dashboard. La risposta contiene le impostazioni, come per 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" }'

Versioni

GET /v1/server/releases

Le ultime 50 versioni pubblicate, dalla più recente alla meno recente. Il campo restoredFrom compare quando la versione ha ripristinato una versione precedente.

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

Con un SDK per server

Le stesse chiamate in ogni SDK. Gli errori vengono sollevati come errori API con status, code, message e details. Se non arriva una risposta (timeout o network_error), status è 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

Il widget e gli SDK per dispositivi mobili usano un'altra interfaccia pubblica, sotto /v1/client/{publicKey}: restituisce la versione pubblicata, registra il percorso della conversazione e apre ticket dal modulo di contatto. È accessibile anche agli ospiti e richiede solo la chiave pubblica. Non serve chiamarla direttamente; è descritta nel file openapi.yaml per completezza.