لاستخدام هاتف TotalVoice في Mavibot، تحتاج إلى الحصول على رمز الوصول (Access Token) من لوحة تحكم TotalVoice وإدخاله في إعدادات التكامل. TotalVoice هي خدمة هاتفية برازيلية أصبحت الآن جزءًا من مجموعة Zenvia.
يمكن للبوت ربط الموظف بالعميل، وتحويل المكالمات وإنهائها، واسترداد تسجيلات المكالمات، وإرسال أحداث المكالمات إلى المحادثة. توفر TotalVoice أيضًا تكلفة كل مكالمة.
الحصول على البيانات المطلوبة
- قم بإنشاء حساب Zenvia Voice وأضف رصيدًا إلى رصيدك.
- سجّل الدخول إلى لوحة التحكم. في الزاوية السفلية اليسرى من الشاشة الرئيسية، بجوار Access Token، انقر على أيقونة النسخ.
Access Token هو المفتاح الوحيد الذي يوفر الوصول إلى حسابك بالكامل، بما في ذلك إجراء المكالمات المدفوعة. لا تنشره أو تشاركه خارج شركتك.
الاتصال
في إعدادات الهاتف، حدد TotalVoice وأدخل:
- Access Token — المفتاح من لوحة تحكم TotalVoice.
-
Client-facing number — الرقم الذي سيراه العميل، بالتنسيق
+551140028922. هذا الحقل اختياري. إذا تركه فارغًا، سيتم استخدام الرقم الافتراضي من حساب TotalVoice الخاص بك.
بعد الحفظ، سيظهر notification URL في صفحة الاتصال. تحتاج إلى إضافته إلى لوحة تحكم TotalVoice — راجع القسم التالي.
تم الآن ربط التكامل. لفصله، امسح حقل Access Token واحفظ الإعدادات.
إعداد الإشعارات
على عكس تكاملات الهاتف الأخرى، يجب تكوين عنوان URL للإشعار يدويًا لأن TotalVoice لا توفر طريقة لـ Mavibot للقيام بذلك تلقائيًا.
- انسخ عنوان URL المعروض في صفحة الاتصال.
- في لوحة تحكم TotalVoice، افتح Desenvolvedores → Configurações da API.
- الصق نفس عنوان URL في جميع حقول webhook الثلاثة:
- Status Tempo Real — تغييرات حالة المكالمة أثناء المكالمة؛
- Chamada - Fim — نهاية المكالمة؛
- DID - Fim de Chamada — نهاية مكالمة واردة إلى رقمك.
⏳ قد تستغرق الإشعارات ما يصل إلى 20 دقيقة لبدء الوصول بعد حفظ الإعدادات. هذا قيد من TotalVoice. إذا لم تظهر أي أحداث في المحادثة مباشرة بعد الإعداد، فقط انتظر.
إذا قمت بإعادة إنشاء رمز الوصول الخاص بك، فسيتغير عنوان URL للإشعار. احفظ الرمز الجديد في Mavibot وقم بتحديث عنوان URL في لوحة تحكم TotalVoice، وإلا ستتوقف أحداث المكالمات عن الوصول.
الموظفون
في إعدادات الموظف، أدخل رقم TotalVoice الخاص بالموظف.
يمكنك استخدام إما رقم داخلي (
ramal، عادة 3-4 أرقام) أو رقم جوال عادي بالتنسيق+5511987654321. هذا أحد التكاملات القليلة حيث يكون التنسيق مرنًا: إذا لم يستخدم الموظف امتداد PBX داخليًا، أدخل رقم جواله.
الاتصال من بطاقة العميل
سيظهر زر اتصال بجوار رقم هاتف العميل في بطاقة المحادثة. يتصل TotalVoice أولاً بـ الموظف، وفقط بعد أن يرد الموظف، يتصل بالعميل.
هذا الترتيب مقصود: لن يسمع العميل صمتًا على الخط لأن الموظف متصل بالفعل عندما يبدأ هاتف العميل في الرنين.
وظائف الحاسبة
مكالمة من موظف إلى عميل
totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)
المعلمات:
-
client_phone— رقم هاتف العميل بالتنسيق+5511987654321. مطلوب. -
employee_number— رقم الموظف: إما رقم داخلي أو رقم جوال. مطلوب. -
bina— الرقم الذي سيراه العميل. اختياري. إذا تم حذفه، يتم استخدام الرقم من إعدادات الاتصال. -
gravar_audio— ما إذا كان سيتم تسجيل المكالمة. اختياري. التسجيل مفعل افتراضيًا.
تحويل المكالمة
totalvoice_transfer_call(number, call_id, leg)
المعلمات:
-
number— الرقم الذي يجب تحويل المكالمة إليه. مطلوب. -
call_id— معرف المكالمة. اختياري. إذا تم حذفه، يتم استخدام أحدث مكالمة للعميل. -
leg— أي جانب من المكالمة سيتم تحويله:destino(العميل، القيمة الافتراضية) أوorigem(الموظف).
إنهاء المكالمة
totalvoice_hangup_call(call_id)
المعلمات:
-
call_id— معرف المكالمة. اختياري. إذا تم حذفه، يتم استخدام أحدث مكالمة للعميل.
الحصول على رابط تسجيل المكالمة
totalvoice_get_record_link(call_id)
عادةً، يتم استلام رابط التسجيل تلقائيًا مع حدث نهاية المكالمة. هذه الوظيفة مفيدة إذا لم يتم استلام الإشعار أو إذا كنت بحاجة إلى تسجيل من مكالمة أقدم.
المعلمات:
-
call_id— معرف المكالمة. اختياري. إذا تم حذفه، يتم استخدام أحدث مكالمة للعميل.
الاستدعاءات أثناء المكالمة
مع تقدم المكالمة، يتم إرسال الاستدعاءات إلى المحادثة بالتنسيق التالي:
totalvoice_call_event atendida
الأحداث المحتملة:
| الحدث | متى يتم تشغيله |
|---|---|
chamando |
المكالمة ترن |
preparando |
يتم تحضير الخط للاتصال |
atendida |
تم الرد على المكالمة |
sem_resposta |
لا إجابة |
ocupado |
مشغول |
cancelada |
تم إلغاء المكالمة |
congestionado |
ازدحام شبكة الناقل |
falha |
تعذر إتمام المكالمة |
nao_existe |
الرقم غير موجود |
أسماء الحالات تُستلم بالبرتغالية لأنها أسماء الحالات المستخدمة من قبل TotalVoice.
يمكن بناء سيناريو نموذجي "لا إجابة → إرسال رسالة في المراسل" عن طريق التحقق من المتغير totalvoice_call_answered.
يتم إرسال إشعارات حالة المكالمة بما لا يزيد عن مرة كل ثانيتين لكل مكالمة. بالنسبة للمكالمات القصيرة جدًا، قد لا تصل بعض الحالات الوسيطة في الوقت المناسب. يتم دائمًا إرسال حدث نهاية المكالمة.
متغيرات العميل بعد المكالمة
| المتغير | القيمة |
|---|---|
totalvoice_call_id |
معرف المكالمة |
totalvoice_call_status |
حالة المكالمة كما حددتها TotalVoice |
totalvoice_call_answered |
1 — تم الرد على المكالمة، 0 — لم يتم الرد |
totalvoice_call_duration |
مدة المكالمة بالثواني |
totalvoice_call_price |
تكلفة المكالمة بالريال البرازيلي |
totalvoice_hangup_reason |
سبب انتهاء المكالمة |
totalvoice_record_link |
رابط تسجيل المكالمة |
المدة تعني وقت التحدث الفعلي، باستثناء الوقت المستغرق في انتظار الرد على المكالمة. ضع في اعتبارك أن TotalVoice تحسب الفوترة بشكل مختلف: يتم تقريب الوقت القابل للفوترة إلى الدقيقة الكاملة التالية، لذا سيتم فوترة مكالمة مدتها 24 ثانية كدقيقة واحدة. للتحقق من الرسوم، استخدم تقرير الفوترة في لوحة تحكم TotalVoice بدلاً من هذا المتغير.
تسجيلات المكالمات
يتم تكوين التسجيل بشكل منفصل لكل مكالمة وهو مفعل افتراضيًا. يمكنك تعطيله لمكالمة معينة باستخدام المعلمة gravar_audio في وظيفة المكالمة.
عند انتهاء المكالمة، يتم استلام رابط التسجيل مع الحدث وحفظه في المتغير totalvoice_record_link. لا تحتاج إلى طلبه بشكل منفصل.
تسجيل المكالمات منظم بالقانون. في البرازيل، يخضع لمتطلبات LGPD: يجب إبلاغ العميل بأن المكالمة يتم تسجيلها، ويجب أن يكون هناك أساس قانوني لتخزين البيانات. مالك حساب TotalVoice مسؤول عن الامتثال لهذه المتطلبات.
استكشاف الأخطاء وإصلاحها
| الخطأ | السبب / الحل |
|---|---|
| لا يتم إنشاء المكالمة ورسالة الخطأ بالبرتغالية | تقوم TotalVoice بإرجاع السبب كنص. الأسباب الأكثر شيوعًا هي عدم كفاية الرصيد أو تنسيق رقم هاتف غير صالح. |
| المكالمات تعمل، لكن لا تظهر أي استدعاءات في المحادثة | لم تتم إضافة عنوان URL للإشعار إلى لوحة تحكم TotalVoice، أو لم تتم إضافته إلى جميع webhooks الثلاثة، أو لم تمر 20 دقيقة منذ التكوين. |
| كل شيء كان يعمل من قبل، لكن الأحداث توقفت فجأة | تم إعادة إنشاء رمز الوصول، مما غيّر عنوان URL للإشعار. احفظ الرمز الجديد في Mavibot وقم بتحديث عنوان URL في لوحة تحكم TotalVoice. |
| "رقم TotalVoice غير محدد" | رقم TotalVoice الخاص بالموظف مفقود من إعداداته. |
الحالة nao_existe
|
رقم العميل غير موجود. تحقق من التنسيق. تستخدم الأرقام المحمولة البرازيلية +55 + DDD + 9 أرقام. |
الحالة congestionado
|
هناك مشكلة في شبكة الناقل ولا علاقة لها برقم العميل. إذا استمرت المشكلة، اتصل بدعم TotalVoice. |
| لا يوجد رابط تسجيل | تم إنشاء المكالمة مع تعطيل التسجيل، أو لم يتم الرد على المكالمة. |