Kavchat by maxsave
Menú de guías

API de servidor

La API de servidor permite a tu servidor consultar tickets, cerrarlos, obtener informes, definir quién ve el bot y consultar las versiones publicadas. Cada llamada utiliza la clave secreta.

La especificación completa está en el archivo openapi.yaml (OpenAPI 3.1). Puedes importarlo en Postman o Insomnia, o generar un cliente a partir de él. Los SDK de servidor incluyen métodos para todos los endpoints de esta página.

Autenticación

URL base: https://api.kavchat.com. Envía la clave secreta como token bearer. La clave permanece en tu servidor y nunca se envía al navegador ni a la aplicación. Puedes reemplazarla en la página Instalación del panel de control.

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

Respuestas y errores

Cada respuesta es un JSON con un campo success. Los errores incluyen un code fijo que tu código puede comprobar y un message en el idioma de la cabecera 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" }
EstadoCódigos de ejemploSignificado
400ticket_status_invalidUn parámetro o campo del cuerpo de la solicitud no es válido.
401invalid_keyLa clave falta, es incorrecta o se ha reemplazado.
404ticket_not_foundEse ticket no existe en el espacio de trabajo.

Endpoints

Método y rutaDescripción
GET /v1/server/workspaceDatos del espacio de trabajo y clave pública
GET /v1/server/ticketsLista de tickets, del más reciente al más antiguo
GET /v1/server/tickets/{id}Un ticket con su transcripción
PUT /v1/server/tickets/{id}/statusCerrar o reabrir un ticket
GET /v1/server/reportsConversaciones, resultados, puntos de abandono y preguntas sin respuesta
GET /v1/server/settingsConfiguración del bot y público
PUT /v1/server/settingsCambiar quién ve el bot
GET /v1/server/releasesVersiones publicadas

Espacio de trabajo

GET /v1/server/workspace

Los datos del espacio de trabajo, la clave pública y los últimos 4 caracteres de la clave secreta (secretKeyHint). Una primera llamada útil para comprobar que la clave funciona.

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

Lista de tickets

GET /v1/server/tickets

Los tickets abiertos desde el chat, del más reciente al más antiguo.

ParámetroDescripción
statusopen o closed. Si se omite, se devuelven los de ambos estados.
limitEntre 1 y 200; por defecto, 50.
beforePara la paginación: el number del último ticket que ya recibiste.
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 es el campo sub del token de identidad cuando se ha identificado al usuario. phone está en formato E.164.

Consultar un ticket

GET /v1/server/tickets/{id}

Un ticket con la transcripción completa, con la misma estructura que un elemento de la lista. Si el identificador no existe, se devuelve un error 404 con ticket_not_found.

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

Cerrar o reabrir

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

Cuerpo de la solicitud: { "status": "closed" } o { "status": "open" }. Devuelve el ticket actualizado.

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

Informes

GET /v1/server/reports

Las conversaciones y sus resultados (open, answered, contact, abandoned), un resumen por guion, los pasos en los que los usuarios abandonan la conversación y las preguntas agrupadas para las que el bot no encontró respuesta. from y to son fechas y horas en formato ISO 8601. Por defecto: los últimos 30 días.

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

Configuración del bot

GET /v1/server/settings

El público, la lista de usuarios de prueba y la apariencia 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" }]
  }
}

Cambiar quién ve el bot

PUT /v1/server/settings

Aquí solo puedes cambiar audience (off, testers o all) y testerPhones (hasta 50 números). El resto de la configuración se edita en el panel de control. Devuelve la configuración, igual que 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" }'

Versiones

GET /v1/server/releases

Las últimas 50 versiones publicadas, de la más reciente a la más antigua. El campo restoredFrom aparece cuando la versión se creó al restaurar una versión anterior.

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 de servidor

Las mismas llamadas en cada SDK. Los errores se lanzan como errores de API con status, code, message y details. Si no se recibe una respuesta (timeout o network_error), status es 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

API de cliente

El widget y los SDK para móviles utilizan otra interfaz pública, bajo /v1/client/{publicKey}: devuelve la versión publicada, registra el recorrido de la conversación y abre tickets desde el formulario de contacto. También está abierta a invitados y solo requiere la clave pública. No necesitas llamarla directamente; se describe en el archivo openapi.yaml para completar la documentación.