للمطوّرين

كل ما يمكن الضغط عليه في اللوحة له endpoint

تكلّم واجهة REST برمجية، ومنتج الدعم مبني فوقها. أنشئ الوكلاء واضبط إعداداتهم، وادفع المعرفة، وابدأ المحادثات واقرأها، واشترك في Webhooks موقّعة، وركّب دردشة الويب بسطر واحد. عنوان الأساس هو https://api.takallam.ai/v1

سجّل بقائمة الانتظار كلّمونا

نطاق الواجهة

ما الذي يمكنك تشغيله من الكود

اللوحة نفسها عميل لهذه الواجهة. وإن كان الأمر موجوداً في المنتج، فخلفه endpoint.

REST فوق HTTPS

موارد متوقعة، وJSON في الاتجاهين، وأفعال HTTP القياسية، وترقيم بالمؤشر في كل قائمة. ويُرسل المفتاح في ترويسة Authorization.

الوكلاء

استخدم POST /agents لإنشاء وكيل، وPATCH لتعديل شخصيته أو لغاته أو صلاحياته أو قنواته. ومعرّف الوكيل هو المفتاح لكل ما بعده.

كيف يُبنى الوكيل

المعرفة

ادفع رابطاً أو مستنداً أو مجموعة سجلات إلى /agents/{id}/knowledge. واستبدل أي مصدر أو احذفه، فيتوقف الوكيل عن استخدامه.

المحادثات

ابدأ محادثة من واجهتك الخاصة، أو اقرأ المحادثات التي وصلت عبر QR والدردشة والبريد الإلكتروني والهاتف. القناة واللغة والنتيجة كلها في السجل نفسه.

داخل لوحة الدعم

Webhooks

أحداث موقّعة للمحادثات والتصعيد والتذاكر وتشغيل مسارات العمل، تصل إلى نقطة النهاية لديك، ويُعاد إرسالها إن لم تستجب.

التضمين وSDK

وسم script للويب، وSDK أصلية لـ iOS وأندرويد. نفس الوكيل، ونفس المعرفة، ونفس سجل المحادثة الذي يستخدمه الخط الهاتفي.

الوكلاء

أنشئ وكيلاً واعرضه على القنوات

طلب POST واحد ينشئ الوكيل ويعرضه على القنوات التي تحددها. والاستجابة تعطيك المعرّف الذي تستخدمه في المعرفة والمحادثات وWebhooks وكود التضمين.

استخدم PATCH على المورد نفسه لتغيير الشخصية أو اللغات أو قواعد التصعيد، دون إعادة نشر ودون معرّف جديد.
الوكيل يُنشأ كمسودة، ولا يصل إلى أي عميل قبل أن تنشره.
القنوات حقول داخل الوكيل، لا أربعة تكاملات منفصلة.

create-agent.sh

# أنشئ وكيلاً واعرضه على القنوات الأربع
curl https://api.takallam.ai/v1/agents \
  -H "Authorization: Bearer $TAKALLAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Layla",
    "role": "reservations",
    "languages": ["ar-AE", "en"],
    "knowledge_base": "kb_live",
    "channels": {
      "qr":    { "mode": "voice_first" },
      "chat":  { "embed": true },
      "email": { "address": "[email protected]" },
      "phone": { "number": "+971 4 555 0180" }
    },
    "escalate_when": ["low_confidence", "refund_requested"]
  }'

# => { "id": "agt_8fk21", "status": "draft" }

المعرفة والمحادثات

ادفع المعرفة، ثم اقرأ ما حدث

المعرفة تدخل على الوكيل، والمحادثات تخرج على مورد مستقل، أياً كانت القناة التي وصلت منها.

دفع المعرفة

أرسل POST برابط أو ملف أو مجموعة سجلات إلى /agents/{id}/knowledge، فيستخدمها الوكيل في الدور التالي، دون إعادة بناء ودون إعادة نشر.

إبقاؤها محدّثة

أعد زحف قسم من موقعك وفق جدولك، أو استبدل مستنداً عند تغيّر سعر، أو احذف مصدراً لم يعد يصح الرد منه.

بدء محادثة

إن كنت تبني واجهتك الخاصة، أو ترسل رسائل البريد من مسار بريد قائم لديك، أرسل POST /conversations مع معرّف الوكيل واستقبل الرد بصيغة JSON. وتصل المحادثة إلى صندوق الوارد نفسه وتُصعَّد إلى الفريق نفسه.

قناة البريد الإلكتروني

قراءة ما حدث

استخدم GET /conversations مع ترشيح حسب الوكيل أو القناة أو اللغة أو النتيجة، وتصفّح بالمؤشر. والتصعيد والتذاكر مرتبطة بالسجل نفسه.

Webhooks

اشترك مرة واحدة، ثم تعامل مع الأحداث

حدّد لتكلّم أين يرسل الأحداث وأيها تريد. وكل تسليم موقّع، فتتحقق من مصدره قبل أن تتصرف بناءً عليه.

أحداث للمحادثات والتصعيد والتذاكر وتشغيل مسارات العمل.
تحقّق من التوقيع على النص الخام قبل تحليله.
يُعاد إرسال التسليم الفاشل، لذا اجعل المعالج لديك idempotent.

webhooks.sh

# اشترك بنقطة نهاية في الأحداث التي تهمك
curl https://api.takallam.ai/v1/webhooks \
  -H "Authorization: Bearer $TAKALLAM_KEY" \
  -d '{
    "url": "https://example.com/hooks/takallam",
    "events": ["conversation.completed", "conversation.escalated",
               "ticket.created", "workflow_run.failed"]
  }'

# كل تسليم موقّع. وهذا هو النص الذي يصلك:
{
  "id": "evt_3c19a",
  "type": "conversation.escalated",
  "created_at": "2026-05-12T09:41:07Z",
  "data": {
    "conversation_id": "cnv_71b40",
    "agent_id": "agt_8fk21",
    "channel": "phone",
    "reason": "low_confidence"
  }
}

الأحداث

نفس عمليات التشغيل التي تفتحها في اللوحة

كل حدث يصلك يقابله شيء ظاهر في المنتج. فالحدث workflow_run.failed هو نفسه التشغيل الذي يمكنك فتحه في سجل التشغيل، خطوة بخطوة، بما دخل إليه وما عاد منه.

conversation.completed وconversation.escalated، ومعهما الوكيل والقناة واللغة في النص المرسل.
ticket.created وticket.updated لكل ما يحتاج إلى متابعة.
workflow_run.finished وworkflow_run.failed، لتربط إعادة المحاولة عندك بعملية تشغيل عندنا.
التوقيع بمفتاح سري مشترك يمكنك تدويره من اللوحة.

شاهد باني مسارات العمل

شاشة سجل تشغيل مسارات العمل تعرض كل عملية تشغيل ووقتها والخطوة التي توقفت عندها — شاشة من المنتج · بيانات تجريبية

تضمين الويب

سطر واحد في الصفحة

ألصق وسم script فتعمل الدردشة بوكيلك ومعرفتك وقواعد التصعيد لديك. وهي تكتب في سجل المحادثة نفسه الذي يستخدمه كود QR وصندوق البريد والخط الهاتفي، فالعميل الذي اتصل صباحاً ليس غريباً بعد الظهر.

بلا خطوة بناء، وبلا إطار عمل، وبلا حزمة تتابع تحديثها.
يتبع لغة الصفحة، أو ثبّت اللغة عبر data-lang.
التسليم إلى موظف يحدث داخل النافذة نفسها، وبلا إعادة تحميل.

index.html

<!-- دردشة الويب. سطر واحد قبل </body>. -->
<script src="https://cdn.takallam.ai/embed.js" data-agent="agt_8fk21" defer></script>

<!-- تثبيت اللغة بدل اتباع لغة الصفحة. -->
<script src="https://cdn.takallam.ai/embed.js"
        data-agent="agt_8fk21"
        data-lang="ar-AE" defer></script>

التطبيقات

SDK أصلية لـ iOS وأندرويد

قناة التطبيق تأتي كـ SDK أصلية، لا كصفحة ويب مضمّنة داخل تطبيقك. يحصل مستخدموك على الدردشة والصوت من الوكيل نفسه، وباللغة التي يستخدمون بها تطبيقك أصلاً.

استخدم الواجهة الجاهزة، أو استدعِ الـ API واعرض واجهتك أنت.
صوت ونص في جلسة واحدة — يبدأ المستخدم بالكتابة ثم ينتقل إلى الكلام.
العربية والإنجليزية، بما في ذلك من يبدّل بينهما داخل الجملة الواحدة.
وتستمر المحادثة في اللوحة إذا احتاج موظف إلى استلامها.

كيف يتعامل تكلّم مع العربية

شاشة إعداد قناة التطبيق والويب لوكيل داخل تكلّم — شاشة من المنتج · بيانات تجريبية

المفاتيح والبيئات

ابدأ في Sandbox، وانتقل إلى Live عن قصد

لكل مساحة عمل نوعان من المفاتيح. مفتاح Sandbox يعمل على مساحة اختبار بالأشكال نفسها للطلبات والاستجابات وبلا قنوات حية، فلا يمكن لحلقة خاطئة في سكربت أن تتصل بعميل حقيقي. ومفتاح Live هو الإنتاج فعلاً.

المفاتيح تُنشأ وتُلغى من اللوحة، لكل بيئة على حدة.
بيئة الاختبار بلا رقم هاتف حي، وبلا كود QR حي، وبلا عملاء حقيقيين على الطرف الآخر.
المسار البرمجي واحد في الحالتين — تغيّر المفتاح لا العناوين.
وإلغاء المفتاح يسري فوراً، لا في نهاية الجلسة.

كيف يعمل التسعير

شاشة إعدادات مساحة العمل في تكلّم حيث تُدار التهيئة والصلاحيات — شاشة من المنتج · بيانات تجريبية

في الإنتاج

التفاصيل غير اللامعة

السلوك الذي لا تلاحظه إلا حين يتعطل شيء عند الثالثة فجراً هو السلوك الذي يستحق التوثيق.

كتابات idempotent

أرسل مفتاح idempotency مع طلب POST، فتعيد المحاولة بعد انقطاع النتيجة الأصلية بدل إنشاء وكيل أو محادثة أو تذكرة ثانية.

حدود المعدل

الحدود تُطبّق على كل مفتاح. والطلب المحجوب يعود بالرمز 429 دون أن يُنشئ شيئاً، فتكون إعادة المحاولة مع تراجع تدريجي آمنة لا مكرِّرة للعمل.

ترقيم بالمؤشر

القوائم تعيد مؤشراً لا رقم صفحة، فلا تتخطى عملية السحب سجلات ولا تكررها بينما تصل محادثات جديدة خلفها.

منطقة واحدة

مساحة عملك في منطقة الإمارات me-central-1. والمحادثات والنصوص وقواعد المعرفة تبقى داخل المنطقة افتراضياً، وأنت تقرر ما يُحتفظ به.

أسئلة

ما يسأل عنه المطوّرون أولاً

هل توجد واجهة برمجية؟

نعم. تكلّم واجهة REST على https://api.takallam.ai/v1 واللوحة مبنية فوقها. الوكلاء والمعرفة والمحادثات والتذاكر ومسارات العمل وWebhooks كلها موارد يمكنك استدعاؤها مباشرة، بصيغة JSON في الاتجاهين وترقيم بالمؤشر في كل قائمة.

كيف أحصل على مفتاح API؟

تكلّم قبل الإطلاق، والمفاتيح تُصدر مع المجموعة الأولى. سجّل بقائمة الانتظار وأخبرنا بما تريد بناءه — فالتكاملات التي تُطلب أولاً هي التي تُبنى وتُوثّق أولاً.

هل توجد بيئة اختبار؟

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

هل الـ Webhooks موقّعة؟

نعم. كل تسليم يحمل توقيعاً محسوباً على النص الخام بمفتاح سري يمكنك تدويره. تحقّق منه قبل التحليل، واجعل المعالج idempotent — فالتسليم الفاشل يُعاد إرساله، وقد يصلك الحدث نفسه أكثر من مرة.

هل أستطيع بناء واجهتي الخاصة مع الاستمرار في استخدام اللوحة؟

نعم. المحادثات التي تبدأها عبر الـ API تصل إلى صندوق الوارد نفسه مع QR والدردشة والبريد الإلكتروني والهاتف. فريقك يستلمها في المحادثة نفسها، والتصعيد يتحول إلى التذاكر نفسها، ومسارات العمل نفسها تعمل خلفها.

هل لديكم SDK؟

SDK أصلية لـ iOS وأندرويد تغطي قناة التطبيق، والويب وسم script واحد. وما عدا ذلك HTTP وJSON عاديان، فأي لغة فيها عميل HTTP تعمل دون انتظار مكتبة جاهزة.

ما هي حدود المعدل؟

الحدود تُطبّق على كل مفتاح. والطلب المحجوب يعود بالرمز 429 دون أن يُنشئ شيئاً، فإعادة المحاولة مع تراجع تدريجي آمنة، ومفتاح idempotency على الكتابات يجعل إعادة المحاولة بعد انقطاع تعيد النتيجة الأصلية لا نسخة مكررة. والحدود النهائية تُحدد مع المجموعة الأولى وفق الأحجام الحقيقية.

أين تعمل الواجهة؟

في منطقة الإمارات me-central-1. المحادثات والنصوص وقواعد المعرفة تبقى داخل المنطقة افتراضياً، وأنت تتحكم بما يُحتفظ به وبمدته.

أخبرنا بما تريد بناءه

الوصول إلى الـ API يبدأ مع المجموعة الأولى. سجّل بقائمة الانتظار وقل لنا أي القنوات وأي نقاط النهاية تهمك — فهذا ما يحدد ترتيب ما نطلقه.

سجّل بقائمة الانتظار كلّمونا

الدفع على التفاعل · سعر لكل قناة · بدون مقاعد وبدون حد أدنى