Twilio هو مزود اتصالات دولي. يتيح للبوت إجراء مكالمات للعملاء وربطهم بموظفيك في أكثر من 100 دولة حيث يوفر Twilio أرقام هواتف، بما في ذلك المكسيك والبرازيل وتركيا وإسبانيا وألمانيا وفرنسا والإمارات العربية المتحدة وتايلاند وماليزيا وغيرها الكثير.

ما الذي ستحصل عليه بعد ربط Twilio:

  • إجراء مكالمة للعميل بنقرة واحدة مباشرة من بطاقة المحادثة؛
  • مكالمات آلية قائمة على السيناريوهات — يقوم البوت بالاتصال بالعميل وقراءة رسالة نصية بصوت مسموع؛
  • مكالمات جماعية — يقوم البوت بالاتصال بالعميل وربطه بأول موظف متاح؛
  • تسجيل جميع المكالمات، مع تخزين رابط التسجيل في متغيرات الطلب؛
  • أحداث المكالمات (رنين، رد، اكتمال) مباشرة في المحادثة — يمكنك استخدامها لبناء السيناريوهات.

الخطوة 1: إنشاء حساب وشراء رقم

  1. سجّل في twilio.com وأكمل عملية التحقق.
  2. في وحدة تحكم Twilio، افتح Phone Numbers ← Buy a number واختر رقمًا في البلد الذي تحتاجه. تأكد من تمكين Voice — بعض الأرقام تدعم الرسائل النصية فقط ولا يمكن استخدامها للمكالمات.

الخطوة 2: نسخ بيانات الاعتماد الخاصة بك

في الصفحة الرئيسية لوحدة تحكم Twilio، ضمن Account Info، ستجد قيمتين:

العنصر الشكل
Account SID ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token مخفي؛ انقر على Show لإظهاره

⚠️ انسخ Auth Token تمامًا كما يظهر، دون أي مسافات إضافية قبله أو بعده. نستخدمه للتحقق من صحة كل طلب من Twilio. قد يؤدي حرف إضافي غير مرئي واحد إلى عمل المكالمات بينما لا تظهر أحداث المكالمات في المحادثة.

يمنحك Auth Token وصولًا كاملًا إلى حساب Twilio الخاص بك والأموال الموجودة فيه. لا ترسله عبر تطبيقات المراسلة أو تنشره في أي مكان.

الخطوة 3: ربط Twilio في حسابك

افتح Project ← Integrations ← Telephony ← Twilio واملأ الحقول الثلاثة:

الحقل ما يجب إدخاله
Account SID من الخطوة 2
Auth Token من الخطوة 2
Twilio Number الرقم الذي اشتريته، بالصيغة الدولية: +14155550100

يجب إدخال الرقم بصيغة E.164: +، رمز البلد، ورقم الهاتف، بدون مسافات أو أقواس أو واصلات.

بعد الحفظ، سيظهر callback URL على الصفحة. انسخه. ثم افتح إعدادات الرقم الذي اشتريته في وحدة تحكم Twilio، وتحت Voice & Fax، قم بتكوين:

  • A call comes in ← Webhook ← الصق الرابط المنسوخ واختر HTTP POST.

بدون هذا التكوين، ستعمل المكالمات الصادرة، لكن المكالمات الواردة وأحداث المكالمات في المحادثة لن تعمل.

لفصل التكامل، امسح حقل Account SID واحفظ الإعدادات.

الخطوة 4: إضافة أرقام هواتف الموظفين

يتصل Twilio بالموظفين على أرقام هواتف عادية — لا توجد تحويلات داخلية هنا.

افتح علامة التبويب Team، وحدد موظفًا، واملأ حقل Twilio Phone Number برقم هاتفه الكامل بنفس الصيغة:

+905551112233

بدون هذا الرقم، لن يعمل زر الاتصال في بطاقة العميل لهذا الموظف.

الاتصال من بطاقة العميل

سيظهر زر اتصال بجوار رقم هاتف العميل في بطاقة المحادثة. يؤدي النقر عليه إلى بدء التسلسل التالي:

  1. يتصل Twilio بـ الموظف — يرى الموظف رقم Twilio الخاص بك كمعرّف المتصل.
  2. يرد الموظف على المكالمة.
  3. فقط بعد ذلك يتصل Twilio بـ العميل ويربط الطرفين.

الترتيب مقصود: لا يضطر العميل إلى الاستماع إلى نغمة الرنين بينما يصل الموظف إلى هاتفه. إذا لم يرد الموظف، لا يتم الاتصال بالعميل على الإطلاق.

المكالمات من سيناريوهات البوت

أربع طرق متاحة في الحاسبة.

twilio_employee_call(client_phone, employee_phone, caller_id)

يربط موظفًا بعميل. يعمل بنفس طريقة زر الاتصال في بطاقة العميل: أولاً يتم الاتصال بالموظف، ثم بالعميل.

twilio_employee_call(client_phone, "+905551112233")

الوسيطة الثالثة اختيارية. تحدد رقم الهاتف الذي سيراه العميل كمعرّف المتصل. افتراضيًا، يتم استخدام رقم Twilio الخاص بك.

twilio_group_call(client_phone, employee_phones, caller_id)

يتصل بالعميل، وبمجرد أن يرد العميل، يتصل في نفس الوقت بجميع الموظفين في القائمة المحددة. يتم ربط المكالمة بأول موظف يرد.

twilio_group_call(client.phone, "+905551112233,+905554445566,+905557778899")

⚠️ الترتيب معكوس هنا. على عكس الطريقة السابقة، يرد العميل أولاً وقد يسمع بضع ثوانٍ من الصمت بينما يتصل Twilio بالموظفين. هذا قيد من Twilio: الاتصال بمجموعة في نفس الوقت وربط أول شخص يرد يعمل فقط بهذه الطريقة. إذا كان من المهم ألا ينتظر العميل، استخدم twilio_employee_call.

twilio_play_message(client_phone, text, voice, language)

يتصل بالعميل ويقرأ النص المحدد باستخدام كلام مُصنّع. هذا مفيد لتذكيرات المواعيد وتأكيدات الطلبات وإشعارات التسليم.

twilio_play_message(client.phone, "Hello! This is a reminder about your appointment tomorrow at 3:00 PM.", "alice", "en-EN")

الصوت alice عالمي ويدعم اللغات الرئيسية، بما في ذلك tr-TR وes-ES وes-MX وpt-BR وde-DE وfr-FR وen-US وru-RU وar-XA.

حدد اللغة دائمًا بشكل صريح — وإلا فقد يقرأ Twilio النص باستخدام نطق إنجليزي.

لا تدرج كلمات مرور أو رموز تحقق أو معلومات حساسة أخرى في الرسالة: قد يرد البريد الصوتي على المكالمة.

يعيد رابط تسجيل المكالمة. نادرًا ما يكون هذا مطلوبًا لأن الرابط يظهر تلقائيًا عادةً (انظر القسم التالي). يمكن أن يكون مفيدًا إذا لم يتم استلام رابط التسجيل ويحتاج إلى طلبه مرة أخرى.

twilio_get_record_link()

إذا لم يتم توفير وسيطة، يتم استخدام أحدث مكالمة للعميل.

المتغيرات والأحداث

بعد كل مكالمة، يخزن البوت المتغيرات التالية في طلب العميل:

المتغير ما يحتويه
twilio_call_id معرّف مكالمة Twilio
twilio_call_disposition نتيجة المكالمة: completed، busy، no-answer، failed، canceled
twilio_call_duration مدة المكالمة بالثواني
twilio_record_link رابط التسجيل
twilio_record_id معرّف تسجيل Twilio

يتم إرسال أحداث بصيغة twilio_call_event <status> إلى المحادثة. يمكنك استخدامها كشروط في سيناريوهاتك:

الحدث متى يتم إرساله
twilio_call_event initiated تم إنشاء المكالمة
twilio_call_event ringing الهاتف يرن
twilio_call_event answered تم الرد على المكالمة
twilio_call_event completed انتهت المكالمة
twilio_call_event busy / no-answer / failed / canceled تعذر إكمال المكالمة
twilio_call_event recording تسجيل المكالمة جاهز

⚠️ انتظر حدث recording قبل استخدام رابط التسجيل، وليس حدث completed. يعالج Twilio ملف التسجيل بعد انتهاء المكالمة بالفعل. في وقت استلام حدث completed، يكون متغير twilio_record_link فارغًا. لذلك يجب أن يتم تشغيل السيناريو الذي يرسل التسجيل إلى مدير أو CRM بواسطة حدث recording.

سيناريو نموذجي "تعذر الوصول إلى العميل — أرسل له رسالة" يعمل على النحو التالي: شرط لـ twilio_call_event no-answer أو busy ← إرسال رسالة إلى العميل.

تسجيلات المكالمات

التسجيل مفعل افتراضيًا لجميع المكالمات التي تشمل موظفًا. يتم تسجيل كلا جانبي المحادثة بدءًا من لحظة الرد على المكالمة. يتم تخزين الملفات في حساب Twilio الخاص بك ويتم فوترتها بواسطة Twilio.

⚠️ يشير رابط twilio_record_link مباشرة إلى Twilio وهو محمي ببيانات اعتماد حسابك. لا يمكنك ببساطة فتحه في متصفح أو إرساله إلى عميل — سيتم عرض خطأ وصول. لتنزيل التسجيل، افتح وحدة تحكم Twilio وانتقل إلى Monitor ← Logs ← Calls، ثم ابحث عن المكالمة باستخدام twilio_call_id الخاص بها.

⚖️ تسجيل المكالمات منظم بالقانون. في العديد من البلدان — بما في ذلك ألمانيا وفرنسا وإسبانيا وفي العديد من الولايات الأمريكية — قد تكون موافقة الطرفين مطلوبة، وفي بعض الحالات يجب تشغيل إشعار منطوق في بداية المكالمة. بصفتك مالك حساب Twilio، فأنت مسؤول عن الامتثال للمتطلبات المعمول بها. إذا كانت هذه القواعد تنطبق عليك، فابدأ المكالمة بإشعار تسجيل أو عطّل التسجيل في إعدادات رقم Twilio الخاص بك.

استكشاف الأخطاء وإصلاحها

لا يتم إنشاء المكالمة ويتم إرجاع خطأ مصادقة

Account SID أو Auth Token غير صحيح. انسخهما مرة أخرى من وحدة تحكم Twilio. الأسباب الأكثر شيوعًا هي مسافة إضافية أو نسخ Test Token عن طريق الخطأ بدلاً من Auth Token الرئيسي.

المكالمات تعمل، ولكن لا توجد أحداث أو تسجيلات في المحادثة

لم يتم تكوين callback URL في إعدادات رقم Twilio (انظر الخطوة 3)، أو تم تكوينه بطريقة HTTP خاطئة. يجب أن تكون الطريقة HTTP POST.

سبب شائع آخر هو تغيير Auth Token في Twilio ولكن لا يزال التكوين القديم في حسابك. في هذه الحالة، لم تعد توقيعات الطلبات متطابقة، لذلك يتم رفض جميع عمليات الاسترجاع.

خطأ 21606 أو "From number not valid"

الرقم الذي تم إدخاله في حقل Twilio Number إما لم يتم شراؤه تحت حساب Twilio الخاص بك أو لا يدعم المكالمات الصوتية.

افتح Phone Numbers ← Manage ← Active numbers وتأكد من أن الرقم مدرج وله إمكانية Voice.

خطأ 21215 — Geo Permissions

افتراضيًا، يحظر Twilio المكالمات إلى العديد من البلدان كإجراء لمنع الاحتيال.

افتح Voice ← Settings ← Geo Permissions وقم بتمكين الوجهات التي تحتاجها.

يتصل عميل، ولكن يتم إنشاء بطاقة محادثة لرقم الموظف

تم تكوين callback بعنوان URL خاطئ. انسخ callback URL من صفحة التكامل مرة أخرى، وتأكد من نسخ العنوان بالكامل، بما في ذلك كل شيء بعد علامة الاستفهام.

حساب تجريبي: يشغل Twilio رسالة صوتية قبل المكالمة

هذا سلوك قياسي لحسابات Twilio التجريبية. يمكن للحسابات التجريبية أيضًا الاتصال فقط بأرقام هواتف موثقة.

أضف أموالًا إلى حسابك وقم بالترقية إلى حساب Twilio كامل.