تُدار مفاتيح الواجهة البرمجية والـ 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"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