AI SALES AGENT — نسخة البداية
============================

ماذا يفعل هذا المشروع؟
1. يبحث عن مؤسسات عبر Google Places API.
2. يجلب رقم الهاتف المنشور للمؤسسة.
3. يحفظ العملاء في MySQL ويمنع التكرار بواسطة Google Place ID.
4. يبدأ مكالمة Telnyx AI Assistant إلى العميل.
5. يمرر اسم المؤسسة ورقمها وبيانات المنتج للوكيل تلقائيًا.
6. إذا وافق العميل أثناء المكالمة على استلام رابط الشراء، يستدعي الوكيل Webhook يرسل قالب WhatsApp المعتمد.
7. يمكن تشغيل cron/agent.php دوريًا من cPanel ليبحث ويتصل تلقائيًا ضمن ساعات وحدود الاتصال التي تحددها.

ما تحتاجه قبل التشغيل
---------------------
A) حساب Telnyx موثق + رصيد.
B) رقم هاتف في Telnyx قادر على إجراء المكالمات إلى الجزائر.
C) TeXML Application في Telnyx، واحفظ الـ Application ID.
D) AI Assistant في Telnyx، واحفظ Assistant ID.
E) WhatsApp Business مفعّل عبر Telnyx + قالب Marketing معتمد من Meta لإرسال رابط الشراء.
F) Google Cloud Project مع Places API (New) مفعّل ومفتاح API وبilling مفعل.
G) قاعدة MySQL على الاستضافة.

التركيب
-------
1. ارفع مجلد المشروع إلى الاستضافة.
2. أنشئ قاعدة MySQL واستورد database.sql.
3. انسخ config.example.php إلى config.php.
4. ضع بيانات MySQL ومفاتيح Google/Telnyx في config.php.
5. غيّر admin_key إلى قيمة طويلة وعشوائية.
6. أنشئ AI Assistant داخل Telnyx والصق محتوى assistant/INSTRUCTIONS_AR.txt في Instructions.
7. أضف Webhook Tool حسب assistant/TOOL_SETUP_AR.txt.
8. أنشئ قالب WhatsApp معتمدًا يحتوي في الـBODY على متغيرين:
   {{1}} = اسم العميل/المؤسسة
   {{2}} = رابط الشراء
   ثم ضع Template ID في config.php.
9. افتح لوحة الإدارة:
   https://YOUR-DOMAIN.COM/ai-sales-agent/public/?key=YOUR_ADMIN_KEY
10. جرّب البحث عن نوع مؤسسة وولاية، ثم اضغط "اتصل بالعميل التالي".

التشغيل التلقائي
----------------
من cPanel > Cron Jobs شغّل:
php /FULL/PATH/ai_sales_agent_starter/cron/agent.php
كل 10 أو 15 دقيقة. السكربت يحترم call_start_hour وcall_end_hour وdaily_call_limit.
ابدأ بـ max_calls_per_run = 1 و daily_call_limit = 5 أثناء الاختبار.

ملاحظة مهمة حول Google Places
-------------------------------
المشروع يستخدم Text Search لطلب Place IDs فقط، ثم Place Details للأماكن المرشحة من أجل رقم الهاتف. هذا يقلل طلبات البيانات المدفوعة مقارنة بطلب أرقام كل نتائج البحث مباشرة.

ملاحظة مهمة حول WhatsApp
-------------------------
المكالمة الهاتفية لا تفتح نافذة محادثة WhatsApp لمدة 24 ساعة. لذلك بدء الرسالة على WhatsApp يحتاج قالبًا معتمدًا من Meta. السكربت لا يرسل الرابط إلا عندما تستدعي أداة المساعد endpoint بعد موافقة العميل.

ملاحظة الامتثال
----------------
استخدم أرقام الأعمال المنشورة علنًا، حدّد ساعات اتصال مناسبة، احترم طلب عدم الاتصال، ولا ترسل WhatsApp دون موافقة واضحة. لا تستخدم قوائم أرقام شخصية مسرّبة أو مجهولة المصدر.

اختبار قبل الإطلاق
-------------------
- جرب الاتصال برقمك أنت أولًا.
- اختبر العربية والفرنسية والمقاطعة أثناء الكلام.
- تأكد أن الوكيل لا يرسل WhatsApp قبل الموافقة.
- ضع حدًا يوميًا صغيرًا أول أسبوع.
- راقب أسعار الاتصال إلى +213 في حساب Telnyx قبل الاتصال على نطاق واسع؛ تكلفة الاتصال الدولي منفصلة عن تكلفة AI.
