Kavchat by maxsave
Меню руководств

Серверный API

Серверный API позволяет вашему серверу читать и закрывать обращения, получать отчёты, определять, кому доступен бот, и просматривать опубликованные версии. Каждый вызов выполняется с секретным ключом.

Полная спецификация доступна в файле openapi.yaml (OpenAPI 3.1). Его можно импортировать в Postman или Insomnia или сгенерировать на его основе клиент. Серверные SDK предоставляют методы для всех эндпоинтов на этой странице.

Аутентификация

Базовый URL: https://api.kavchat.com. Передавайте секретный ключ как Bearer-токен. Он остаётся на вашем сервере и никогда не передаётся в браузер или приложение. Заменить его можно на странице Установка в панели управления.

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

Ответы и ошибки

Каждый ответ возвращается в формате JSON с полем success. У ошибок есть постоянный code для проверки в вашем коде и message на языке, указанном в заголовке 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" }
СтатусПримеры кодовЗначение
400ticket_status_invalidНекорректный параметр или поле в теле запроса.
401invalid_keyКлюч отсутствует, неверен или был заменён.
404ticket_not_foundВ рабочем пространстве нет такого обращения.

Эндпоинты

Метод и путьОписание
GET /v1/server/workspaceДанные рабочего пространства и публичный ключ
GET /v1/server/ticketsСписок обращений, от новых к старым
GET /v1/server/tickets/{id}Одно обращение с историей переписки
PUT /v1/server/tickets/{id}/statusЗакрытие или повторное открытие обращения
GET /v1/server/reportsДиалоги, результаты, точки ухода и вопросы без ответа
GET /v1/server/settingsНастройки и аудитория бота
PUT /v1/server/settingsИзменение аудитории бота
GET /v1/server/releasesОпубликованные версии

Рабочее пространство

GET /v1/server/workspace

Данные рабочего пространства, публичный ключ и последние 4 символа секретного ключа (secretKeyHint). Удобный первый вызов, чтобы проверить, работает ли ключ.

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

Список обращений

GET /v1/server/tickets

Обращения, созданные в чате, от новых к старым.

ПараметрОписание
statusopen или closed. Без параметра возвращаются обращения с обоими статусами.
limitОт 1 до 200, по умолчанию 50.
beforeДля постраничной загрузки: number последнего полученного обращения.
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 содержит значение поля sub из токена идентификации, если пользователь идентифицирован. phone передаётся в формате E.164.

Одно обращение

GET /v1/server/tickets/{id}

Одно обращение с полной историей переписки, в той же структуре, что и элемент списка. Если идентификатор не существует, возвращается ошибка 404 с кодом ticket_not_found.

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

Закрытие или повторное открытие

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

Тело запроса: { "status": "closed" } или { "status": "open" }. Возвращает обновлённое обращение.

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

Отчёты

GET /v1/server/reports

Диалоги и их результаты (open, answered, contact, abandoned), сводка по каждому сценарию, шаги, на которых пользователи уходят, и сгруппированные вопросы, на которые бот не нашёл ответа. from и to задают дату и время в формате ISO 8601. По умолчанию: последние 30 дней.

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

Настройки бота

GET /v1/server/settings

Аудитория, список тестовых пользователей и внешний вид бота.

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

Изменение аудитории

PUT /v1/server/settings

Здесь можно изменить только audience (off, testers или all) и testerPhones (до 50 номеров). Остальные настройки редактируются в панели управления. В ответе возвращаются настройки, как при 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" }'

Версии

GET /v1/server/releases

Последние 50 опубликованных версий, от новых к старым. Поле restoredFrom появляется, если версия создана при восстановлении предыдущей версии.

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

Использование серверного SDK

В каждом SDK доступны те же вызовы. При ошибках выбрасывается исключение API с полями status, code, message и details. Если ответ не получен (timeout или 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

Клиентский API

Виджет и мобильные SDK используют дополнительный публичный интерфейс по пути /v1/client/{publicKey}: он возвращает опубликованную версию, записывает ход диалога и создаёт обращения из формы обращения. Он доступен и гостям и требует только публичный ключ. Вызывать его самостоятельно не нужно. Для полноты документации он описан в файле openapi.yaml.