API do servidor

A API do servidor permite que seu servidor consulte chamados, feche chamados, obtenha relatórios, defina quem vê o bot e consulte as versões publicadas. Todas as chamadas usam a chave secreta.

A especificação completa está no arquivo openapi.yaml (OpenAPI 3.1). Você pode importá-lo para o Postman ou o Insomnia, ou gerar um cliente a partir dele. Os SDKs para servidor oferecem acesso a todos os endpoints desta página.

Autenticação

URL base: https://api.kavchat.com. Envie a chave secreta como um bearer token. Ela fica no seu servidor e nunca é enviada ao navegador ou ao aplicativo. Você pode substituí-la na página Instalação do painel.

curl

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

Respostas e erros

Toda resposta é um JSON com o campo success. Os erros têm um code fixo que seu código pode verificar e uma message no idioma do cabeçalho 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" }

Status	Exemplos de códigos	Significado
400	`ticket_status_invalid`	Um parâmetro ou campo no corpo da requisição é inválido.
401	`invalid_key`	A chave não foi informada, está incorreta ou foi substituída.
404	`ticket_not_found`	Esse chamado não existe no espaço de trabalho.

Endpoints

Método e caminho	Descrição
`GET /v1/server/workspace`	Dados do espaço de trabalho e chave pública
`GET /v1/server/tickets`	Lista de chamados, do mais recente ao mais antigo
`GET /v1/server/tickets/{id}`	Um chamado com a transcrição
`PUT /v1/server/tickets/{id}/status`	Fechar ou reabrir um chamado
`GET /v1/server/reports`	Conversas, resultados, pontos de abandono e perguntas sem resposta
`GET /v1/server/settings`	Configurações do bot e público-alvo
`PUT /v1/server/settings`	Alterar o público-alvo do bot
`GET /v1/server/releases`	Versões publicadas

Espaço de trabalho

GET /v1/server/workspace

Dados do espaço de trabalho, chave pública e os últimos 4 caracteres da chave secreta (secretKeyHint). É uma boa primeira chamada para verificar se a chave 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 chamados

GET /v1/server/tickets

Chamados abertos pelo chat, do mais recente ao mais antigo.

Parâmetro	Descrição
`status`	`open` ou `closed`. Sem o parâmetro, retorna ambos.
`limit`	De 1 a 200. Padrão: 50.
`before`	Para paginação: o `number` do último chamado já recebido.

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 é o campo sub do token de identidade quando o usuário foi identificado. phone está no formato E.164.

Consultar um chamado

GET /v1/server/tickets/{id}

Um chamado com a transcrição completa, na mesma estrutura de um item da lista. Quando o identificador não existe, retorna o erro 404 com ticket_not_found.

curl

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

Fechar ou reabrir

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

Corpo da requisição: { "status": "closed" } ou { "status": "open" }. Retorna o chamado atualizado.

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

Relatórios

GET /v1/server/reports

As conversas e seus resultados (open, answered, contact, abandoned), um resumo por roteiro, as etapas em que os usuários saem e as perguntas para as quais o bot não encontrou resposta, agrupadas. from e to são data e hora no formato ISO 8601. Padrão: últimos 30 dias.

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

Configurações do bot

GET /v1/server/settings

O público-alvo, a lista de usuários de teste e a aparência do 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" }]
  }
}

Alterar o público-alvo

PUT /v1/server/settings

Aqui, só é possível alterar audience (off, testers ou all) e testerPhones (até 50 números). As demais configurações são editadas no painel. A resposta contém as configurações, como no 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" }'

Versões

GET /v1/server/releases

As últimas 50 versões publicadas, da mais recente à mais antiga. O campo restoredFrom aparece quando a versão restaurou uma versão 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" }]
    }
  ]
}

Com um SDK para servidor

As mesmas chamadas em cada SDK. Os erros são lançados como um erro de API com status, code, message e details. Quando nenhuma resposta é recebida (timeout ou network_error), o 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();

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 do cliente

O widget e os SDKs para dispositivos móveis usam uma interface pública adicional em /v1/client/{publicKey}: ela retorna a versão publicada, registra o andamento da conversa e abre chamados pelo formulário de contato. Ela também está aberta a visitantes e exige apenas a chave pública. Você não precisa chamá-la diretamente. Ela está descrita no arquivo openapi.yaml para completar a documentação.