أضف شخصية تعريفية ناطقة بالذكاء الاصطناعي إلى موقعك مع Wixzel Voice

ما الذي تحتاجه قبل أن تبدأ؟

• حساب على Wixzel Voice فيه رصيد. تُدفع المكالمات عبر الـ widget من رصيد حقيقي، وليس من دقائق الاختبار المجانية؛ والحد الأدنى لشحن الرصيد هو $5.
• مفتاح API بالصلاحيتين agents:write وcalls:write، محفوظ على خادمك. يمكن أيضًا تنفيذ كل ما يلي من لوحة التحكم، في تبويب الشخصية التعريفية الخاص بالوكيل.
• موقع يُقدَّم عبر HTTPS ويمكنك إضافة وسم script إليه. لا تمنح المتصفحات الصفحة إذن الميكروفون إلا عبر HTTPS.

كيف تبني هذا على Wixzel Voice، خطوة بخطوة؟

1. 01أنشئ الوكيل من موقعك

   أعطه موقعك ودورًا. قيمة role هي receptionist أو support أو sales أو guide أو كلماتك الخاصة:

   shellنسخ

   curl https://api.voice.wixzel.com/v1/agents/generate \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "website_url": "https://smiledental.example", "role": "receptionist" }'

   make-agent.mjs (TypeScript SDK)نسخ

   import { WixzelVoice, waitForAgent } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   let agent = await client.agents.generate({
     website_url: 'https://smiledental.example',
     role: 'receptionist',
   });
   agent = await waitForAgent(client.agents, agent); // until the mascot is ready or failed
   console.log(agent.id, agent.name, agent.mascot.status, agent.knowledge_base_id);

   يجيب فورًا بوكيل قادر على التحدث بالفعل، مع mascot.status: "building". في الخلفية يقرأ صفحاتك، ويكتب التعليمات والجملة الافتتاحية، ويبني قاعدة المعرفة مما قرأه، ويرسم شخصية تعريفية بلون علامتك التجارية. استعلم عبر GET /v1/agents/{id} حتى تصبح قيمة mascot.status هي ready، وعادةً يحدث ذلك في أقل من دقيقة؛ وفي الـ SDK، تتولى waitForAgent الاستعلام. إذا فشل البناء يبقى الوكيل عاملًا بالمظهر الذي كان له.

   يبدأ الوكيل على Gemini Live. غيّر محركه أو صوته أو تعليماته مثل أي وكيل آخر عبر PATCH /v1/agents/{id}؛ وتبقى شخصيته التعريفية كما هي.

2. 02فعّل الـ widget، واختر من يمكنه الاتصال

   المشاركة متوقفة حتى تفعّلها. اذكر الأصول (origins) التي يُقدَّم منها موقعك؛ فلن يبدأ الـ widget مكالمة في أي مكان آخر:

   shellنسخ

   curl -X PATCH https://api.voice.wixzel.com/v1/agents/AGENT_ID/mascot \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "welcome_message": "Hi! I am Molly from Smile Dental. Tap Call to talk to me.",
       "sharing": {
         "embed": true,
         "embed_origins": ["https://smiledental.example", "https://www.smiledental.example"],
         "caller_info": "contact",
         "max_call_seconds": 300,
         "daily_minutes": 60,
         "calls_per_visitor_daily": 3,
         "max_concurrent_calls": 2
       }
     }'

   caller_info هو ما يقدّمه الزائر قبل المكالمة: none (الافتراضي) لا يطلب شيئًا، وcontact يطلب اسمًا ورقم هاتف أو بريدًا إلكترونيًا، وgoogle يطلب تسجيل الدخول بحساب Google. يخبرك تسجيل الدخول بـ Google بهوية الزائر ولا يُنشئ له حساب Wixzel أبدًا؛ وعلى موقعك يُفتح في نافذة صغيرة على voice.wixzel.com، تعيد النتيجة فقط إلى أصل موجود في embed_origins.

   تُبقي الحدود الأربعة المكالمات العامة ضمن ميزانية: أطول مكالمة، والدقائق العامة في اليوم لجميع الزوار معًا (حتى منتصف الليل بتوقيت UTC)، وعدد المكالمات التي يمكن لزائر واحد إجراؤها في اليوم، وعدد المكالمات في الوقت نفسه. القيم أعلاه هي القيم الافتراضية. أضف "link": true للحصول على صفحة مشاركة على voice.wixzel.com/m?id=… أيضًا.

   تحمل الاستجابة mascot.public_id، مثل m_4fT9qLx2Bv8K. وهو المعرّف المستخدم في وسم script.

3. 03الصق وسم script واحدًا

   أضف هذا إلى كل صفحة يجب أن تظهر فيها الشخصية التعريفية، قبل وسم إغلاق body:

   index.htmlنسخ

   <script src="https://voice.wixzel.com/embed.js" data-mascot="m_4fT9qLx2Bv8K" async></script>

   تنتظر الشخصية التعريفية في الزاوية السفلية اليمنى مع رسالة الترحيب. يضغط الزائر Call، ويسمح بالميكروفون ويتحدث؛ فتستمع الشخصية التعريفية وتفكر وتحرّك فمها مع صوت الوكيل. يعمل الـ widget داخل shadow root، فلا يتداخل CSS الخاص بك مع CSS الخاص به أبدًا.

4. 04ضعها بنفسك، ودع الوكيل يتصرف في صفحتك

   لعرضها داخل عنصر خاص بك بدلًا من الزاوية، احذف data-mascot من الوسم واستدعِ WixzelMascot.mount بعد تحميل السكربت.

   أداة العميل (client tool) تعمل في صفحتك عندما يطلبها الوكيل، مثلًا لفتح صفحة الحجز. أنشئ الأداة للوكيل في لوحة التحكم أو عبر POST /v1/tools، ثم سجّل ما تفعله، قبل تحميل السكربت أو بعده:

   index.htmlنسخ

   <div id="talk"></div>
   <script>
     window.WixzelMascot = Object.assign(window.WixzelMascot || {}, {
       tools: {
         open_page: ({ path }) => {
           location.href = path;
           return { opened: path };
         },
       },
     });
   </script>
   <script
     src="https://voice.wixzel.com/embed.js"
     async
     onload="WixzelMascot.mount(document.getElementById('talk'), { mascot: 'm_4fT9qLx2Bv8K' })"
   ></script>

   ما تعيده الدالة يعود إلى الوكيل، الذي يخبر به المتصل. أدوات webhook، التي تستدعي خادمك، تعمل في الـ widget أيضًا.

5. 05اعرف من اتصل، واحظر شخصًا

   كل مكالمة عبر الـ widget تسجّل المتصل. اعرض قائمة المتصلين بوكيل:

   shellنسخ

   curl "https://api.voice.wixzel.com/v1/callers?agent_id=AGENT_ID&limit=20" \
     -H "Authorization: Bearer $WIXZEL_API_KEY"
   
   curl -X PATCH https://api.voice.wixzel.com/v1/callers/CALLER_ID \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "blocked": true }'

   لكل متصل location تقريبي (المدينة والمنطقة والدولة، مستنتجة من عنوان IP الذي لا يُحفظ إلا كقيمة hash)، وplatform (المتصفح ونظام التشغيل والجهاز)، وpage_url الذي اتصل منه، وما قدّمه لك، وcall_count. يجمع معرّف عشوائي يحفظه متصفحه مكالماتِ الشخص الواحد؛ ولا توجد بصمة رقمية (fingerprinting)، ويخبر الـ widget المتصلين بما يُشارك معك.

   المتصل المحظور لا يستطيع الاتصال بذلك الوكيل مجددًا من الـ widget أو رابط المشاركة أو التطبيق أو الهاتف. كل مكالمة موجودة أيضًا في GET /v1/calls مع نصها المكتوب وتكلفتها، ويمكن تصفيتها حسب caller_id.

كم يكلّف هذا البناء على Wixzel Voice؟

ما حدود Wixzel Voice التي تنطبق على هذا البناء؟

• الصوت بجودة الهاتف، G.711 µ-law بتردد 8 kHz في الاتجاهين.
• لا يبدأ الـ widget المكالمات إلا من الأصول المذكورة في embed_origins، وحدها الأقصى 20 أصلًا.
• تبقى المكالمات العامة ضمن الحدود المضبوطة على الوكيل. بعد تجاوز daily_minutes تُرفض المكالمات حتى منتصف الليل بتوقيت UTC.
• تُحتسب مكالمات الـ widget ضمن حد المكالمات المتزامنة للحساب، خمس افتراضيًا، إلى جانب المكالمات الهاتفية وجلسات التطبيقات. يمنع max_concurrent_calls صفحةً مزدحمة من استهلاكها كلها.
• تستخدم مكالمات الـ widget رصيدًا حقيقيًا. دقائق الاختبار المجانية مخصصة للتحدث إلى وكلائك من لوحة التحكم.
• لا يوجد تحويل إلى شخص من مكالمة ويب؛ فالتحويل يحتاج إلى خط هاتف.