Server API

ה-Server API מאפשר לשרת שלכם לקרוא פניות, לסגור אותן, למשוך דוחות, לקבוע מי רואה את הבוט ולראות את הגרסאות שפורסמו. כל קריאה נעשית עם המפתח הסודי.

המפרט המלא נמצא בקובץ openapi.yaml (OpenAPI 3.1). אפשר לייבא אותו ל-Postman או ל-Insomnia, או לייצר ממנו לקוח. ערכות הפיתוח לשרת עוטפות את כל הנקודות שבעמוד הזה.

אימות

הכתובת הבסיסית: https://api.kavchat.com. שולחים את המפתח הסודי כ-bearer token. הוא נשאר בשרת שלכם ולא נשלח אף פעם לדפדפן או לאפליקציה. אפשר להחליף אותו בעמוד התקנה בלוח הבקרה.

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

סטטוס	קודים לדוגמה	משמעות
400	`ticket_status_invalid`	פרמטר או שדה בגוף הבקשה אינו תקין.
401	`invalid_key`	המפתח חסר, שגוי או שהוחלף.
404	`ticket_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

הפניות שנפתחו מהצ'אט, מהחדשה לישנה.

פרמטר	תיאור
`status`	`open` או `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" }]
    }
  ]
}

עם ערכת פיתוח לשרת

אותן קריאות בכל ערכה. שגיאות נזרקות כשגיאת 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();

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

הווידג'ט וערכות הפיתוח למובייל משתמשים בממשק ציבורי נוסף, תחת /v1/client/{publicKey}: הוא מחזיר את הגרסה שפורסמה, מתעד את מהלך השיחה ופותח פניות מטופס הפנייה. הוא פתוח גם לאורחים ודורש רק את המפתח הציבורי. אין צורך לקרוא לו בעצמכם, והוא מתואר בקובץ openapi.yaml לשם השלמות.