Gemini Live في مكالمة هاتفية حقيقية عبر Wixzel Voice API

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

• مفتاح API من Wixzel Voice مع رصيد. الحد الأدنى لشحن الرصيد هو $5.
• SIP trunk لدى مزوّد الاتصالات ورقم عليه يسمح لك المزوّد بعرضه كرقم المتصل.
• الأدوات curl وjq وuuidgen.

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

1. 01اربط SIP trunk

   اضبط مفتاحك وعنوان الـ API الأساسي مرة واحدة، ثم أنشئ الـ trunk. يحتفظ tee بالاستجابة كاملة، لأنك تحتاج منها قيمتين إلى جانب المعرّف:

   shellنسخ

   export WIXZEL_API_KEY="wv_live_..."
   API=https://api.voice.wixzel.com/v1
   
   TRUNK_ID=$(curl -s $API/sip-trunks \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My carrier",
       "host": "sip.your-carrier.example",
       "username": "your-sip-username",
       "password": "your-sip-password"
     }' | tee trunk.json | jq -r .id)
   
   jq -r '.platform_ip, .origination_uri' trunk.json

   احذف username وpassword إذا كان مزوّد الاتصالات يصادق حسب IP. في الحالتين، أضف platform_ip إلى قائمة السماح لدى المزوّد حتى يقبل المكالمات من المنصة؛ أما origination_uri فهو المكان الذي يجب أن يرسل إليه المزوّد المكالمات الواردة، وهو ما لا يحتاجه هذا الدليل.

2. 02سجّل الرقم الذي ستتصل منه

   استخدم رقمك الخاص، بصيغة E.164:

   shellنسخ

   NUMBER_ID=$(jq -n --arg trunk "$TRUNK_ID" \
     '{phone_number: "+14155550100", sip_trunk_id: $trunk}' |
     curl -s $API/phone-numbers \
       -H "Authorization: Bearer $WIXZEL_API_KEY" \
       -H "Content-Type: application/json" \
       -d @- | jq -r .id)

3. 03أنشئ وكيل Gemini Live

   الصوت نموذج آني واحد بدلًا من ثلاث مراحل:

   shellنسخ

   AGENT_ID=$(jq -n --arg number "$NUMBER_ID" '{
       name: "Gemini Live",
       system_prompt: "You are a friendly assistant on a phone call. Keep answers to one or two sentences.",
       opening_message: "Hi, this is an automated assistant. Do you have a minute?",
       outbound_phone_number_id: $number,
       voice: { realtime: { model: "google/gemini-live", voice: "Charon" } }
     }' |
     curl -s $API/agents \
       -H "Authorization: Bearer $WIXZEL_API_KEY" \
       -H "Content-Type: application/json" \
       -d @- | jq -r .id)

   يسلّم voice.realtime الدور كاملًا، الاستماع والتفكير والكلام، إلى Gemini Live، لذا لا توجد كتلة stt أو llm أو tts؛ وترفض الـ API أي صوت يحدد الشكلين معًا. Charon أحد الأصوات الجاهزة في Gemini، ويعرض GET /v1/engines/gemini_live/voices جميعها مع أوصاف Google المكوّنة من كلمة واحدة.

   يعطي outbound_phone_number_id الوكيلَ رقم متصل، وهذا ما يتيح للطلب التالي حذف from_number_id.

4. 04أجرِ المكالمة

   استبدل الرقم في to بالهاتف الذي تريد الاتصال به:

   shellنسخ

   CALL_ID=$(jq -n --arg agent "$AGENT_ID" '{to: "+14155551234", agent_id: $agent}' |
     curl -s $API/calls \
       -H "Authorization: Bearer $WIXZEL_API_KEY" \
       -H "Idempotency-Key: $(uuidgen)" \
       -H "Content-Type: application/json" \
       -d @- | jq -r .id)

   تجيب الـ API فورًا بـ 201 مع status: "queued"، ويرن الهاتف بعد لحظة. Idempotency-Key مطلوب هنا: انتهاء مهلة الشبكة لا يخبرك بشيء عن إجراء المكالمة من عدمه، وإعادة المحاولة بالمفتاح نفسه تعيد المكالمة الأصلية بدلًا من الاتصال مرتين، لذا احتفظ بالمفتاح إذا كتبت منطق إعادة المحاولة. المكالمة التي لا يمكن تمويل أول 15 ثانية منها تُرفض بـ 402 قبل أي اتصال.

5. 05اقرأ ما حدث

   الطلب الخامس يقرأ المكالمة:

   shellنسخ

   curl -s $API/calls/$CALL_ID \
     -H "Authorization: Bearer $WIXZEL_API_KEY" | jq

   Example response, shortenedنسخ

   {
     "id": "6a96a3ead6e886d42462dd3e",
     "object": "call",
     "session_id": "sip-5b0c7c0e-9d1f-4c52-8a9e-2f0d3a4b6c7d",
     "status": "completed",
     "direction": "outbound",
     "channel": "phone",
     "engine": "gemini_live",
     "to": "+14155551234",
     "duration_seconds": 94,
     "cost_micros": 76923,
     "failure_code": null,
     "failure_reason": null,
     "transcript": [
       { "role": "assistant", "content": "Hi, this is an automated assistant. Do you have a minute?" },
       { "role": "user", "content": "Sure, go ahead." }
     ]
   }

   تنتقل status من queued عبر ringing وin-progress إلى completed، أو تنتهي بـ failed أو busy أو no-answer. تُكتب cost_micros عند تسوية المكالمة (1,000,000 تساوي $1.00) وتبقى null في المكالمة التي لم تتصل أبدًا، لأن مثل هذه المكالمة لا تُحتسب. عند فشل المكالمة، تكون failure_code هي سبب Q.850 من مزوّد الاتصالات (17 مشغول، 19 لا رد، 21 رفضها المزوّد) وتوضح failure_reason ما يجب فعله. يفصّل GET /v1/usage/events?session_id=… كل رسم.

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

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

• المكالمات الهاتفية تحتاج إلى SIP trunk خاص بك. لا يبيع Wixzel Voice الأرقام ولا ينقلها ولا يحتفظ بها. ويمكنه شراء رقم لك على حساب Twilio أو Telnyx أو Plivo أو Vobiz أو Vonage تربطه من لوحة التحكم، ويحاسبك عليه مزوّد الاتصالات.
• مكالمة الاختبار من POST /v1/agents/{id}/test-call تنطق عبارتها الواحدة عبر مسار الصوت classic، لأن Gemini Live لا يملك وضع العبارة الواحدة. لسماع صوت Gemini نفسه، أجرِ مكالمة عادية.
• يمكن أن تكون خمس مكالمات نشطة في وقت واحد لكل حساب افتراضيًا، ويُرفع الحد عند الطلب.
• لا يُنشر رقم لزمن الاستجابة: يجيب المحرك الآني بالسرعة التي يجيب بها النموذج نفسه. تُطرح التغييرات في سلوك Wixzel Voice خلف ترويسة Wixzel-Version مؤرّخة.