بناء وكيل التسويق بالذكاء الاصطناعي (إعلانات Facebook/Meta)

1. ما الذي ستبنيه

يحصل كل تاجر على Kayroo بالفعل، مجاناً، على خبير تسويق ذكاء اصطناعي داخلي يقرأ سلال التسوّق المتروكة، والمخزون بطيء الحركة، وشرائح العملاء، ويصوغ نصائح حول ما يجب فعله. لا يرسل أي شيء إطلاقاً، ولا ينشر، ولا ينفق — إنّه تقرير، لا فاعل.

هذه الإضافة تفعل العكس: وكيل ذكاء اصطناعي يقوم فعلياً بالتسويق. يقرأ كتالوج المنتجات الحقيقي للمتجر وطلباته الأخيرة عبر واجهة Kayroo Connect، ويستخدم نموذج لغوي كبير مع استدعاء الأدوات (tool-use) على واجهة Meta Marketing لصياغة حملات إعلانية على Facebook/Meta، و— فقط بعد موافقة صريحة من التاجر — ينشرها على حساب التاجر الإعلاني الخاص، منفِقاً أموال التاجر.

• يقرأ كتالوج منتجات المتجر، والطلبات الأخيرة، وسياق رسوم التوصيل عبر واجهة Kayroo العامة.
• يصوغ استهداف الجمهور، واقتراحات الميزانية، والمحتوى الإعلاني (النص + اختيار صور المنتجات المستخدَمة)، وبنية الحملة (حملة ← مجموعة إعلانية ← إعلان).
• يعرض كل مسوَّدة على التاجر للمراجعة والموافقة الصريحة قبل أي نشر أو أي التزام بميزانية.
• بمجرد الموافقة، ينشر الحملة على حساب Meta Business الإعلاني الخاص بالتاجر، وعلى فوترته الإعلانية الخاصة.
• يرسل بيانات الطلبات/التحويلات إلى Meta عبر واجهة Conversions لتحسين إسناد أداء الحملات مع مرور الوقت.

ما لا تفعله هذه النسخة الأولى صراحة: الكتابة داخل Kayroo، أو التعامل مع بيانات العملاء الشخصية بما يتجاوز ما تتطلّبه واجهة Conversions الخاصة بـ Meta نفسها (مُجزَّأة تجزئة أحادية الاتجاه وفق قواعد Meta)، أو اتخاذ أي قرار إنفاق دون إشراف.

2. اقرأ دليل الواجهة قبل أن تبدأ

تُبنى هذه الإضافة بأكملها فوق Kayroo Connect — واجهة REST العامة ونظام webhooks الخاصين بـ Kayroo. يفترض هذا الدليل أنّك قرأت بالفعل ذلك المرجع وتفهم الرموز والصلاحيات والمسارات والتحقّق من توقيع webhook.

نموذج الثقة مطابق لأي تكامل آخر مع Kayroo: خدمتك تعيش بالكامل على بنيتك التحتية ومستودع الكود الخاص بك. لن تحصل أبداً على الكود المصدري لـ Kayroo، ولا بيانات اعتماد قاعدة البيانات، ولا وصول للخادم، ولا حساب داخلي — تتواصل فقط مع متجر تاجر عبر رمز API الخاص به ومسار webhook المسجَّل لديك.

3. خطة البناء خطوة بخطوة

هذا هو الترتيب الموصى به لبناء المرحلة الأولى. كل خطوة تعتمد فقط على الخطوات السابقة لها.

1. أنشئ خدمتك الخاصة المستضافة (بنيتك التحتية، مستودعك، وأنظمة CI/CD الخاصة بك) — هنا يعمل كل ما يلي.
2. ابنِ مسار إعداد للتاجر: شاشة يلصق فيها التاجر رمز API خاص بـ Kayroo (ينشئه بنفسه من الإعدادات ← رموز API، بصلاحيات store.read + products.read + orders.read)، ويربط حساب Meta Business الخاص به بتطبيقك عبر تدفّق OAuth الخاص بـ Meta.
3. اجلب سياق المتجر عند الربط: استدعِ GET /api/v1/store للعملة/رسوم التوصيل، وGET /api/v1/products للكتالوج (الصور، الأسعار، المخزون)، وGET /api/v1/orders لسجلّ الطلبات الأخيرة — انظر الجدول في القسم 4 لمعرفة الحقول المهمّة هنا بالضبط.
4. سجّل اشتراك webhook (يقوم به التاجر من الإعدادات ← Webhooks في لوحته، موجَّهاً إلى مسارك) لحدثي order.created وproduct.updated، حتى تبقى بيانات حملتك ومحتواك الإعلاني متزامنَين دون استطلاع مستمر.
5. استخدم نموذجاً لغوياً كبيراً مع استدعاء الأدوات على واجهة Meta Marketing لصياغة حملة: استهداف الجمهور، اقتراح الميزانية، المحتوى الإعلاني (النص + اختيار صور المنتجات من الكتالوج)، والبنية (حملة ← مجموعة إعلانية ← إعلان).
6. اعرض على التاجر كل مسوَّدة في شاشة مراجعة واضحة واشترط موافقة صريحة قبل أي نشر أو أي التزام بميزانية — انظر القسم 5، هذه الخطوة إلزامية وليست اختيارية.
7. بمجرد الموافقة، انشر الحملة على حساب Meta Business الإعلاني الخاص بالتاجر عبر واجهة Meta، مفوترَة بالكامل عبر وسيلة الدفع الخاصة بالتاجر لدى Meta.
8. عند استلامك webhook من نوع order.created، أرسل حدث التحويل المطابق إلى واجهة Conversions الخاصة بـ Meta (مع تجزئة بيانات العميل الشخصية وفق متطلبات Meta نفسها) لتحسين أداء الإعلانات وإسنادها مع مرور الوقت.
9. عند استلامك webhook من نوع product.updated، حدّث المحتوى الإعلاني/بيانات الكتالوج المخزَّنة مؤقتاً لذلك المنتج، حتى لا تعلن الحملات أبداً عن أسعار قديمة أو منتجات نافدة من المخزون.

4. البيانات التي تجلبها من Kayroo Connect

تحتاج المرحلة الأولى فقط إلى صلاحيات قراءة موجودة بالفعل اليوم. اطلب هذه فقط — لا تطلب customers.read من التاجر إلا إذا كنت تبني المرحلة الثانية (انظر القسم 8).

5. قاعدة الإشراف البشري (غير قابلة للتفاوض)

هذا هو المتطلّب الأصعب الوحيد لهذه الإضافة، وليس خياراً في الأسلوب: يجب ألّا ينشر وكيلك أبداً حملة أو يلتزم بميزانية إعلانية للتاجر دون موافقة صريحة من ذلك التاجر أولاً، في كل مرّة.

• اعرض مسوَّدة واضحة ومقروءة (الجمهور، الميزانية، المحتوى، البنية) قبل أي نشر — وليس تفريغاً تقنياً بصيغة JSON.
• اشترط إجراءً صريحاً (نقرة حقيقية على "الموافقة والنشر") — وليس إعداداً افتراضياً أو مهلة زمنية توافق تلقائياً إذا لم يستجب التاجر.
• أي تغيير على حملة معتمَدة وقيد التشغيل بالفعل (زيادة الميزانية، محتوى جديد، إيقاف مؤقّت/استئناف) يحتاج نفس خطوة الموافقة الصريحة، وليس فقط الإطلاق الأولي.
• يمكن للوكيل أن يقترح ويشرح ويوصي — لكن التاجر يقرّر. في كل مرّة.

6. ما يجب ألّا تفعله إطلاقاً

• لا تحتفظ أبداً بميزانية إعلانات التاجر أو تسلّفها أو تحرّكها بنفسك. الأموال تنتقل فقط مباشرة بين التاجر وMeta — إضافتك تُعِدّ الحملات فقط، ولا تلمس الدفع إطلاقاً.
• لا تطلب أبداً من Kayroo أو من تاجر وصولاً مباشراً لقاعدة البيانات، أو وصولاً للخادم، أو SSH، أو نسخة من الكود المصدري لـ Kayroo. إذا بدا أنّ شيئاً ما يحتاج ذلك، فالحل هو أن تطلب من Kayroo توسيع الواجهة العامة — وليس الحصول على وصول مباشر.
• لا تتخذ أبداً قرار إنفاق أو نشر دون إشراف — انظر القسم 5.
• لا تعِد أبداً حساب منطق تعرضه Kayroo بالفعل. لتقسيم العملاء (المرحلة الثانية)، اقرأ GET /api/v1/customers/segments بدلاً من إعادة اشتقاق شرائح RFM بنفسك من بيانات الطلبات الخام.
• لا تشارك أو تجمّع أو تُعِد بيع بيانات تاجر واحد — سواء من Kayroo أو من Meta — مع تاجر آخر أو ضدّه.

7. متطلّبات الأمان والتعامل مع البيانات

• خزّن رموز API الخاصة بـ Kayroo ورموز OAuth الخاصة بـ Meta مشفَّرة أثناء التخزين في بنيتك التحتية الخاصة — لا ترى Kayroo أبداً رموز Meta، ولا ترى Meta أبداً رموز Kayroo.
• لا تسجّل الرموز الخام أبداً في السجلّات، ولا تكشفها أبداً في كود جانب العميل.
• ادعم الإلغاء الفوري: إذا عطّل تاجر إضافتك أو حذف رمز API الخاص به لدى Kayroo، يجب أن يتوقّف كل وصول من جانبك فوراً أيضاً — تعامل مع ذلك كانقطاع نهائي، وليس كخطأ عابر يُعاد المحاولة فيه.
• جزّئ أو عامل أرقام هواتف العملاء وبريدهم الإلكتروني تماماً وفق متطلّبات كل قناة (لواجهة Conversions الخاصة بـ Meta قواعدها الخاصة للتجزئة) — احتفظ بها فقط طالما احتاج الغرض ذلك، وليس أبداً لأي استخدام يتجاوز تسويق هذا التاجر.
• حدّد والتزم بفترة احتفاظ لأي بيانات مصدرها Kayroo تخزّنها مؤقتاً (بيانات منتجات/طلبات مسحوبة عبر الواجهة)، واحذفها عند الطلب أو عند فصل تاجر لتكامله.
• سجّل كل إجراء يتّخذه وكيلك (حملة صيغت، تاجر وافق، حملة نُشرت، ميزانية تغيّرت) من جانبك، بحيث يمكن استرجاعه إذا نازع تاجر في إجراء ما.
• أبلغ Kayroo فوراً عن أي اختراق أو تسريب اعتماد مشتبَه به يتعلّق ببيانات تاجر أو الوصول لحساب إعلاني.

8. مراحل مستقبلية محتملة — لا تبنِ بعد

هذه خطوات مستقبلية معقولة بمجرد أن تصبح المرحلة الأولى فعّالة ومُثبَتة — لم يُكلَّف بأي منها بعد، ولا ينبغي بناء أي منها حتى تمنح Kayroo موافقة صريحة. تُدرَج هنا لتفهم إلى أين يمكن أن يتّجه هذا التكامل، وليس كمواصفات تبدأ العمل عليها.

• وكيل محتوى عضوي — صياغة تعليقات لمنشورات التواصل الاجتماعي واقتراح صور المنتجات المناسبة، لينشرها التاجر يدوياً.
• حملات تفاعل تلقائية لإعادة الاستهداف — سلاسل رسائل واتساب/بريد إلكتروني تستهدف الشرائح التي تحدّدها GET /api/v1/customers/segments بالفعل (السلال المتروكة، العملاء المعرَّضون للخطر، الأبطال)، بنفس نمط الموافقة بإشراف بشري كما في المرحلة الأولى. لا تعِد تنفيذ منطق التقسيم — اقرأه من الواجهة.
• مساعدة محتوى تحسين محركات البحث (SEO) — اقتراحات عناوين ووصف meta لصفحات المتجر، تُقرأ وتُكتب عبر الواجهة العامة بدلاً من إعادة بنائها من الصفر.

9. كيف تبدأ

لا يوجد بعد مسار تسجيل مركزي "كن شريكاً لدى Kayroo" — هذا تعاون مباشر بين فريقين صغيرين، وليس إدراجاً في سوق تطبيقات.

1. أرسل بريداً إلكترونياً إلى [email protected] للتعريف بفريقك وتأكيد أنّك تبني هذه الفرصة المحدّدة (حتى لا يكرّر فريقان نفس الجهد).
2. اقرأ دليل مطوّري Kayroo Connect على /developers من البداية إلى النهاية.
3. اطلب من أي تاجر لدى Kayroo على باقة Scale أو الدفع حسب الاستخدام أن ينشئ لك رمز API تجريبياً (الإعدادات ← رموز API) بصلاحيات store.read وproducts.read وorders.read — يمكن أن يكون هذا متجراً تجريبياً تُعِدّه بنفسك، لأنّ هاتين الباقتين هما اللتان يتوفّر فيهما الوصول للواجهة.
4. ابنِ واختبر مسار الإعداد لديك، ومزامنة الكتالوج، وتدفّق الصياغة والموافقة من البداية إلى النهاية على ذلك المتجر التجريبي قبل لمس حساب Meta إعلاني حقيقي.

10. أسئلة؟

إذا لم يغطِّ هذا الدليل أو دليل المطوّرين على /developers أي جانب من الواجهة أو أحداث webhook أو تدفّق الموافقة الذي تحتاجه هذه الإضافة، أرسل بريداً إلكترونياً إلى [email protected] بدلاً من التخمين أو الالتفاف حول المشكلة.