telyzer

الواجهة البرمجية والـ Webhooks

اقرأ المكالمات والتقارير بمفاتيح للقراءة فقط، واستقبل أحداث Webhooks موقّعة.

قائمة الدليل

تُدار مفاتيح الواجهة البرمجية والـ Webhooks من صفحة الواجهة البرمجية والـ Webhooks في البوابة، وهي متاحة في خطة المؤسسات وخلال الفترة التجريبية. تقدم الواجهة البرمجية البيانات والمرشحات نفسها الموجودة في البوابة، وهي للقراءة فقط.

مفاتيح الواجهة البرمجية

اختر مفتاح جديد، وأعطه اسمًا ومدة صلاحية، وحدد صلاحياته:

الصلاحيةتتيح
calls.readسجلات المكالمات مع إخفاء الأرقام الخارجية.
calls.unmaskإظهار الأرقام كاملة.
reports.readالتقارير والتصدير واللوحة المباشرة.

يبدأ المفتاح بـ tzk_ ويُعرض مرة واحدة فقط، فانسخه فورًا. لا يخزن تيلايزر إلا بصمة (hash) للمفتاح. ويوقف زر إلغاء المفتاح فورًا.

المصادقة والحدود

أرسل المفتاح كرمز Bearer. العنوان الأساسي هو https://app.telyzer.com/api/v1.

curl -H "Authorization: Bearer $TELYZER_KEY" \
  "https://app.telyzer.com/api/v1/calls?from=2026-10-01&to=2026-10-07&limit=200"
  • حتى 300 طلب في الدقيقة لكل مفتاح، وبعدها تردّ الواجهة بالرمز 429.
  • 401: المفتاح مفقود أو غير صالح. 403: المفتاح لا يملك الصلاحية التي يحتاجها الطلب.
  • الأوقات المنتهية بـ Local هي الوقت المحلي في الموقع، والمنتهية بـ Utc بالتوقيت العالمي.

نقاط الوصول

الطلبيُرجعالصلاحية
GET /api/v1/callsالمكالمات، صف لكل محادثة، الأحدث أولًا.calls.read
GET /api/v1/calls/{id}مكالمة واحدة بكل مراحل التحويل وسطر السنترال الأصلي.calls.read
GET /api/v1/reportsالتقارير المتاحة.reports.read
GET /api/v1/reports/{key}تقرير بصيغة JSON: الأعمدة والصفوف والقاعدة التي أنتجتها.reports.read
GET /api/v1/reports/{key}/exportملف التقرير: format=csv|xlsx|pdf وlang=en|ar.reports.read
GET /api/v1/wallboardأرقام اليوم حتى الآن: الإجماليات، والمكالمات الفائتة التي لم يُعاود الاتصال بها، وأحدث المكالمات.reports.read

مفاتيح التقارير: summary, daily, hourly, extensions, unanswered, top-numbers, destinations, sites, costs, after-hours, service-level, callers, trunks, account-codes, data-quality, calls، إضافة إلى تقاريرك المخصصة المحفوظة.

المرشحات

تقبل المكالمات والتقارير المرشحات from وto (بصيغة YYYY-MM-DD، وبحد أقصى 366 يومًا)، وsiteId، وdepartmentId، وdirection، وoutcome، وcategory، وextension، وnumber، وafterHours، وminTalk (بالثواني).

تشغيل تقرير
curl -H "Authorization: Bearer $TELYZER_KEY" \
  "https://app.telyzer.com/api/v1/reports/extensions?from=2026-10-01&to=2026-10-31"
تنزيل تقرير بصيغة CSV
curl -H "Authorization: Bearer $TELYZER_KEY" -o daily.csv \
  "https://app.telyzer.com/api/v1/reports/daily/export?format=csv&lang=en&from=2026-10-01&to=2026-10-31"

تقسيم النتائج إلى صفحات

تُرجع /calls صفحة تضم حتى limit مكالمة (من 1 إلى 200، والافتراضي 50) مع قيمة nextCursor. أعد إرسالها في cursor للحصول على الصفحة التالية، وتكون null في الصفحة الأخيرة.

// Node.js 18+: read every call in a date range, 200 per page
let cursor = null;
do {
  const url = new URL("https://app.telyzer.com/api/v1/calls");
  url.searchParams.set("from", "2026-10-01");
  url.searchParams.set("to", "2026-10-31");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: "Bearer " + process.env.TELYZER_KEY } });
  if (res.status === 429) { await new Promise((r) => setTimeout(r, 1000)); continue; }
  const page = await res.json();
  for (const call of page.items) console.log(call.startLocal, call.direction, call.outcome);
  cursor = page.nextCursor; // null on the last page
} while (cursor);

العقد الكامل منشور بمواصفات OpenAPI 3.1 على app.telyzer.com/api/v1/openapi.json.

الـ Webhooks

اختر Webhook جديد، وأدخل عنوان HTTPS الخاص بك، وحدد الأحداث. يرسل تيلايزر حدثًا موقّعًا بصيغة JSON (طلب POST) عند وقوعه:

الحدثيُرسل عند
alert.triggeredانطلاق قاعدة تنبيه.
report.deliveredإرسال تقرير مجدول بالبريد.
source.silentتوقف نظام هاتف عن إرسال السجلات.
  • يرسل زر إرسال تجربة حدثًا تجريبيًا ويعرض رد عنوانك، ويعرض سجل الإرسال المحاولات الأخيرة.
  • يُعاد إرسال الأحداث الفاشلة لمدة يومين تقريبًا بفواصل متزايدة، ويُعطَّل العنوان بعد 20 إخفاقًا متتاليًا.
  • لا تُرسل الأحداث إلا إلى عناوين عامة على الإنترنت.

التحقق من التوقيع

لكل Webhook سر توقيع يُعرض مرة عند إنشائه، ثم من سر التوقيع. يحمل كل طلب الترويسة X-Telyzer-Signature: t=<unix time>,v1=<hex>، حيث v1 هو HMAC-SHA256 للقيمة t متبوعة بنقطة ثم جسم الطلب الخام، بمفتاح هو السر. احسبه على الجسم الخام قبل تحليل JSON، وقارن بزمن ثابت، وارفض الطوابع الزمنية القديمة.

// Node.js: verify X-Telyzer-Signature ("t=<unix>,v1=<hex>") on the raw request body
import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  const a = Buffer.from(parts.v1 ?? "", "hex"), b = Buffer.from(expected, "hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; // reject replays older than 5 minutes
  return a.length === b.length && crypto.timingSafeEqual(a, b) && fresh;
}
# Python: the same check
import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return hmac.compare_digest(expected, parts.get("v1", "")) and fresh