Developer cookbook

متغيرات لكل مكالمة

خصّص وكيلاً محفوظًا لكل مكالمة دون تغيير موجّهه أو أدواته أو إعداداته المنشورة.

ضع العناصر النائبة في موجّه وكيلك المحفوظ، ثم وفّر كائن variables عند بدء مكالمة. تظل الإعدادات المحفوظة وسجل الإصدارات دون تغيير. يعرض ThunderPhone النص قبل إرسال إعدادات المكالمة إلى بيئة تشغيل الصوت.

عند عدم الحاجة إلى قيم، احذف variables، ولا ترسل null (يُرفض بالرمز 400).

العناصر النائبة والقيم الافتراضية#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

الأسماء حساسة لحالة الأحرف وتتبع [A-Za-z_][A-Za-z0-9_]*. يُسمح بالمسافات البيضاء حول الاسم؛ وتكون المسافة البيضاء بعد | جزءًا من القيمة الافتراضية ويتم الاحتفاظ بها. يستخدم {{name|Friend}} القيمة Friend عندما تكون name مفقودة أو null؛ أما السلسلة الفارغة فهي قيمة تم توفيرها صراحةً. تتحول القيم المفقودة دون قيمة افتراضية إلى سلاسل فارغة، وتظهر أسماؤها في unresolved_variables. يُزال النص الموجود بين أقواس مزدوجة إذا لم يكن عنصرًا نائبًا صالحًا. يُزال النص ذو الأقواس المزدوجة داخل كل قيمة مقدمة بشكل مستقل؛ ولا يمكن لقيمة أن تزيل النص المحيط في الموجّه أو قيمة أخرى. تُزال أيضًا محددات الأقواس المزدوجة غير المتطابقة. يجب ألا تستخدم أمثلة JSON في الموجّهات {{. القيم نص عادي، ولا تُقيَّم كشيفرة أو تُوسَّع بصورة متكررة كقوالب.

يمكن أن تظهر المتغيرات أيضًا في موجّهات الإقرار، ورسائل البريد الصوتي الصادرة، ونص إعلان الموافقة عند إرسال هذا الحقل لإجراء مكالمة هاتفية. لا يحتوي الوكيل على حقل first_message منفصل: ضع تعليمات الافتتاح في الموجّه. تستمر العناصر النائبة الحالية للبريد الصوتي {agent_name} و{org_name} في العمل.

يمكن أن تكون القيم سلاسل نصية أو أرقامًا أو قيمًا منطقية أو null؛ وتُعرض القيم المنطقية بصيغة true وfalse. تُزال محارف التحكم في يونيكود (Cc) باستثناء السطر الجديد (\n) وعلامة الجدولة (\t) وعودة العربة (\r)، وجميع محارف التنسيق (Cf)، ونقاط الشيفرة البديلة (Cs)؛ ويُطبَّع \r\n إلى \n. تقتصر كل قيمة على 2,000 حرف عند عرضها. تُنظَّف السلاسل المقدمة وتُقتطع قبل التخزين أيضًا. يجب أن يتسع الكائن الأصلي ضمن 32 كيلوبايت من JSON بترميز UTF-8؛ وتتلقى الكائنات الأكبر الرمز 400 في طلبات المكالمات/الجلسات، بينما تُبلغ عمليات استيراد الحملات عن الصفوف غير الصالحة كلٌّ على حدة. لا تُقبل المصفوفات والكائنات المتداخلة كقيم. تُحتفظ بمفاتيح البيانات الوصفية غير المطابقة (مثل عنوان CSV يحتوي على مسافة) وتُعاد، لكنها لا يمكن الإشارة إليها بعنصر نائب.

مصدر القيم#

واجهة برمجة التطبيقات للمكالمات الصادرة#

أرسل variables إلى جانب agent_id في POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

يعمل ذلك أيضًا مع وكيل المكالمات الصادرة الافتراضي لرقم الهاتف، أو مع config.prompt مضمن. لا يمكن إعادة استخدام مفتاح عدم التكرار مع متغيرات مختلفة.

ملف CSV للحملة#

تُخزَّن أعمدة CSV غير الخاصة بالهاتف بالفعل كمتغيرات لجهة الاتصال. يستخدمها كل اتصال الآن تلقائيًا. استخدم رؤوسًا مثل name وaccount_id وappointment_slot لمطابقة العناصر النائبة لديك. يمكن لتعيين الاسم الحالي دمج عمودَي الاسم الأول واسم العائلة في المتغير name.

خطاف ويب للتهيئة الديناميكية#

في مسار خطاف ويب للتهيئة الحاجب، أعد وكيلًا محفوظًا في مؤسستك مع أي قيم خاصة بكل مكالمة:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

تستبدل مفاتيح الاستجابة المتغيرات على مستوى الطلب، بينما تبقى مفاتيح الطلب الأخرى. تحدد قيمة الاستجابة null القيمة الافتراضية للعنصر النائب. يجب أن يتسع الكائن المدمج أيضًا ضمن 32 كيلوبايت. تقبل استجابات الوكيل المحفوظ agent_id وvariables فقط؛ أعد تهيئة مضمنة عندما تحتاج إلى استبدال الموجّه أو الإعدادات. تستخدم الاستجابة التي تحتوي على prompt دائمًا تهيئة مضمنة: يُتجاهل أي agent_id في تلك الاستجابة، بما في ذلك البيانات الوصفية الفارغة أو غير الصحيحة. يجب أن يجتاز الموجّه المضمن التحقق المعتاد. يمكن أن تتضمن استجابات خطاف الويب المضمنة variables أيضًا. تستخدم استجابات خطاف ويب للوكيل المحفوظ تقسيم A/B المنشور للوكيل في كل من مكالمات الهاتف والودجت؛ وتُعرض المتغيرات بعد اختيار النسخة. في مكالمات الهاتف الواردة، استخدم رقمًا لا وكيل واردًا معيّنًا له وهيّئ خطاف ويب رقم الهاتف أو المؤسسة؛ تستخدم مفاتيح الودجت mode="webhook". لا توفر الإشعارات الواردة لنظام نقطة النهاية استجابات تهيئة حاجبة.

واجهات برمجة تطبيقات جلسات الودجت وRealtime#

يقبل POST /v1/widget/session كائن variables على المستوى الأعلى. يحدد مفتاحه القابل للنشر الوكيل المحفوظ. تمرر المفاتيح في وضع خطاف الويب هذه القيم إلى خطاف ويب للتهيئة وتدمج الاستجابة كما هو موضح أعلاه. تُدار variables الخاصة بالودجت وRealtime التي يوفرها المتصفح من جهة العميل، وتُمرر حرفيًا في web.incoming بعد التحقق وتنظيف السلاسل النصية الموضحين أعلاه، وتُعاد في خطافات ويب للإكمال وسجل المكالمات. لا تعاملها كبيانات موثوقة للهوية أو التفويض.

يقبل POST /v1/realtime/sessions variables إلى جانب agent_id (أو config مضمن). هذه حقول لواجهة برمجة تطبيقات إنشاء الجلسة. لا تمرر وصلة Realtime WebSocket خيار المتغيرات؛ وفّره مباشرةً إلى واجهة برمجة تطبيقات إنشاء الجلسة. يجب أن يضمّن عملاء الودجت variables في حمولة الجلسة المُرسلة؛ ولا يُعد تمرير SDK جزءًا من هذا التغيير في واجهة برمجة التطبيقات. تحل مكالمات اختبار الميكروفون والمحاكاة في المنشئ القيم الافتراضية والعناصر النائبة المفقودة، لكنها لا تتضمن إدخال متغيرات خاصًا بكل مكالمة.

القيم المعادة بعد المكالمة#

يتضمن GET /v1/calls وGET /v1/calls/{call_id} وtelephony.complete وweb.complete قيم variables وunresolved_variables المدمجة النهائية. تتضمنها أيضًا حمولات الإكمال القديمة التي تحتوي على data.history:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

خزّن معرّف CRM أو المهمة في كائن المتغيرات لربط المكالمة المكتملة بسجل مصدرها. تُحتفظ بهذه الحقول مع سجل المكالمة؛ أرسل فقط المعلومات المناسبة للاحتفاظ بها في سجل المكالمات وخطافات الويب.

توافق الموجّهات الحالية#

ينطبق التصيير أيضًا على موجّهات الوكلاء المحفوظة الحالية ومتغيرات A/B، وإعدادات الاتصال الصادر والوقت الفعلي المضمّنة، والموجّهات المُعادة بواسطة خطافات ويب الإعدادات. تصبح عناصر {{name}} النائبة غير المعروفة نصًا فارغًا، حتى عند عدم توفير variables. تحقّق من الموجّهات الحالية قبل النشر، بما في ذلك الموجّهات المضمّنة أو موجّهات خطافات الويب المورّدة خارجيًا التي لا يستطيع ThunderPhone جردها. تطبّق مكالمات الميكروفون والمحاكاة في أداة الإنشاء السلوك الافتراضي/الفارغ نفسه.