بناء موظف استقبال بالذكاء الاصطناعي على Twilio في Node.js مع Wixzel Voice

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

• حساب Twilio مع Elastic SIP Trunking، ورقم هاتف من Twilio.
• مفتاح API من Wixzel Voice (wv_live_…) ورصيد في الحساب. الحد الأدنى لشحن الرصيد هو $5.
• Node.js 20 أو أحدث.

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

1. 01أنشئ Elastic SIP trunk في Twilio

   في لوحة تحكم Twilio، افتح Elastic SIP Trunking وأنشئ trunk. ضمن Termination، اختر Termination SIP URI، مثل your-clinic.pstn.twilio.com. اسم المضيف هذا هو قيمة host للـ trunk الذي تربطه في الخطوة التالية.

   أبقِ لوحة تحكم Twilio مفتوحة. ستعود إليها بعد أن تعطيك الـ API العنوانين اللذين يجب إدخالهما.

2. 02ثبّت الـ SDK واربط الـ trunk

   ثبّت الـ SDK وضع مفتاح API في متغيرات البيئة:

   shellنسخ

   npm install wixzel-voice
   export WIXZEL_API_KEY="wv_live_..."

   trunk.mjsنسخ

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   const trunk = await client.sipTrunks.create({
     name: 'Twilio',
     host: 'your-clinic.pstn.twilio.com', // your Termination SIP URI
     port: 5060,
     transport: 'udp',
   });
   
   console.log('TRUNK_ID', trunk.id);
   console.log('Allowlist at Twilio:', trunk.platform_ip);
   console.log('Origination URI:', trunk.origination_uri);

   لا يوجد اسم مستخدم أو كلمة مرور هنا لأن Twilio تصادق حسب عنوان IP المصدر، وهذه هي الخطوة التالية. لاستخدام Credential List من Twilio بدلًا من ذلك، مرّر username وpassword الخاصين بها. تُخزَّن كلمة المرور مشفّرة ولا تعيدها الـ API مرة أخرى أبدًا.

3. 03وجّه Twilio إلى Wixzel Voice، في الاتجاهين

   تضبط Twilio المكالمات الصادرة والواردة كلًّا على حدة، وكل منهما يفشل بصمت إذا كان مفقودًا.

   ضمن Termination ثم Authentication، أضف platform_ip المطبوع أعلاه إلى IP Access Control List. بدونه ترفض Twilio المكالمات خلال نحو ثانية بسبب الإنهاء (hangup cause) رقم 21.

   ضمن Origination، أضف Origination SIP URI مضبوطًا على origination_uri المطبوع أعلاه. بدونه لا يصل رقمك إلى الوكيل أبدًا ولا يظهر شيء في أي من السجلين، لأن المكالمة لا تغادر Twilio أصلًا.

   أخيرًا، اربط رقم Twilio بهذا الـ trunk ضمن Numbers.

4. 04أنشئ موظف الاستقبال

   الوكيل هو تعليمات وجملة افتتاحية ومحرك صوت. يتيح appointment_booking_enabled له عرض المواعيد وحجزها وإلغاءها أثناء المكالمة؛ وتخبره التعليمات بالأيام والساعات ومدد المواعيد التي يمكنه عرضها.

   agent.mjsنسخ

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   const agent = await client.agents.create({
     name: 'Reception',
     system_prompt: [
       'You are the receptionist for Riverside Dental, answering the phone.',
       'Keep every reply to one or two short sentences, and never read out lists.',
       'You can book, move and cancel check-ups and cleanings.',
       'Offer appointments Monday to Friday, 09:00 to 17:00, 30 minutes each.',
       'Before booking, ask for the full name of the caller and repeat the day and time back.',
       'For a dental emergency, tell the caller to hang up and ring the emergency number.',
       'If you cannot help, take a message and promise a callback.',
     ].join('\n'),
     opening_message: 'Riverside Dental, this is the automated assistant. How can I help?',
     appointment_booking_enabled: true,
     voice: {
       stt: { model: 'deepgram/nova-3', language: 'en-US' },
       llm: { model: 'openrouter/gpt-4o-mini' },
       tts: { model: 'elevenlabs/eleven_flash_v2_5' },
     },
   });
   
   console.log('AGENT_ID', agent.id);

   هذا هو محرك classic: Deepgram Nova-3 وGPT-4o-mini وElevenLabs Flash v2.5، أرخص تركيبة موثوقة للغة الإنجليزية بسعر $0.0867 في الدقيقة. أضف voice إلى كتلة tts لاختيار المتحدث؛ ويعرض client.engines.voices('classic') الأصوات التي يمكنه استخدامها.

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

5. 05وجّه رقمك إلى موظف الاستقبال

   سجّل الرقم على الـ trunk، مع تحديد الوكيل الذي يجيب عليه:

   number.mjsنسخ

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   const number = await client.phoneNumbers.create({
     phone_number: '+14155550100', // your Twilio number, in E.164
     sip_trunk_id: process.env.TRUNK_ID,
     inbound_agent_id: process.env.AGENT_ID,
   });
   
   console.log('NUMBER_ID', number.id);

   بدون inbound_agent_id تُرفض المكالمات الواردة إلى الرقم. لكي يُجري الوكيل نفسه مكالمات أيضًا، للتذكيرات أو لمكالمة اختبار، اجعل الرقم رقم المتصل الخاص به عبر client.agents.update(agentId, { outbound_phone_number_id: number.id }).

6. 06اتصل به، ثم اقرأ المكالمة والحجز

   اتصل برقم Twilio من هاتف محمول واحجز موعدًا. عندما تُنهي المكالمة، تكون المكالمة والموعد كلاهما في الـ API:

   results.mjsنسخ

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   // Lists are newest first.
   const calls = await client.calls.list({ direction: 'inbound', limit: 1 });
   const latest = calls.data[0];
   if (latest) {
     const call = await client.calls.retrieve(latest.id);
     console.log(call.status, call.duration_seconds + 's', (call.cost_micros ?? 0) / 1e6, 'USD');
     for (const line of call.transcript) console.log(line.role + ': ' + line.content);
   }
   
   const appointments = await client.appointments.list({ limit: 5 });
   for (const a of appointments.data) {
     console.log(a.date_time, a.client_name, a.phone_number, a.status);
   }

   قيمة date_time دائمًا بتوقيت UTC. كل حجز يُطلق أيضًا الـ webhook appointmentBooked، وبه يمكنك نسخه إلى تقويمك الخاص لحظة حدوثه.

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

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

• يعرف موظف الاستقبال ساعات عملك من تعليماته. لا تحتوي الإصدارة v1 من الـ API على نقطة نهاية للتوفّر، فلا يرى تقويمك الحقيقي: يُرفض أي وقت محجوز مسبقًا عبر الـ API، لكن المواعيد التي تحتفظ بها في مكان آخر غير مرئية له.
• تُقرأ الحجوزات بالمنطقة الزمنية للحساب، وهي UTC ما لم تُغيَّر، ولا تستطيع الإصدارة v1 من الـ API تغييرها بعد. تحقق من date_time في حجوزاتك الأولى قبل الاعتماد عليها، وراسل aqeel@wixzel.com إذا كان نشاطك التجاري لا يعمل بتوقيت UTC.
• يمكن أن تكون خمس مكالمات نشطة في وقت واحد لكل حساب افتراضيًا. تُرفض المكالمات الإضافية حتى تنتهي إحداها، ويُرفع الحد عند الطلب.
• يبقى رقمك لدى Twilio. لا يبيع Wixzel Voice الأرقام ولا ينقلها ولا يحتفظ بها.
• تُطرح التغييرات في سلوك Wixzel Voice خلف ترويسة Wixzel-Version مؤرّخة.