API الخادم

يتيح API الخادم لخادمكم قراءة التذاكر وإغلاقها، وجلب التقارير، وتحديد من يرى البوت، وعرض الإصدارات المنشورة. يستخدم كل استدعاء المفتاح السري.

المواصفات الكاملة متاحة في ملف openapi.yaml (OpenAPI 3.1). يمكنكم استيراده إلى Postman أو Insomnia، أو توليد عميل منه. توفّر حزم SDK للخادم دوال لاستدعاء جميع نقاط النهاية في هذه الصفحة.

المصادقة

العنوان الأساسي: 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" }]
    }
  ]
}

باستخدام حزمة 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();

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 لاستكمال التوثيق.