دمج Google Chat

اربط الـ Agent الخاص بك بـ Google Chat للتواصل السلس داخل Google Workspace.

نظرة عامة

يوفّر دمج Google Chat ما يلي:

• مراسلة مباشرة مع روبوتك
• دعم مساحات Google Workspace (Spaces) مع محفّزات @mention
• توجيه الـ Agent على مستوى المساحة — عيّن Agents مختلفة لمساحات مختلفة
• ردود نصية مع ذاكرة محادثة ووعي اختياري بسياق المساحة
• معالجة غير متزامنة مع إقرار فوري
• أمان جاهز للمؤسّسات مع عزل قائم على النطاق

المتطلّبات المسبقة

• Agent ذكي نشط (مُنشأ في قسم Agents)
• حساب Google Workspace (حسابات Gmail الشخصية غير مدعومة)
• نطاق مُتحقَّق منه — تحقّق من ملكية نطاقك في Settings > Domains قبل الاتصال

خطوات الإعداد

1. تحقّق من نطاقك (إعداد لمرة واحدة)

قبل ربط Google Chat، تحقّق من ملكية نطاقك:

1. انتقل إلى Settings من الشريط الجانبي
2. انقر على تبويب Domains
3. يُكتشَف نطاقك تلقائيًا من بريد حسابك الإلكتروني
4. أضف سجلّ TXT في مزوّد DNS الخاص بك بالقيم المعروضة:
   • النوع: TXT
   • الاسم: _cuneiform-verify (أو القيمة الكاملة المعروضة)
   • المحتوى: سلسلة التحقّق المعروضة (مثل cuneiform-verify=abc123...)
5. انقر على Verify Now — قد تستغرق تغييرات DNS حتى 48 ساعة للانتشار
6. بمجرّد أن تتغيّر الحالة إلى Verified، تابع لإنشاء عملية الدمج

تُعرض روابط سريعة لمزوّدي DNS الشائعين (Cloudflare وGoDaddy وNamecheap وRoute 53 وDigitalOcean وHostinger) على بطاقة التحقّق.

2. أنشئ دمج Google Chat

1. انتقل إلى Integrations من الشريط الجانبي
2. ضمن “Google Chat Bots”، انقر على Connect Bot
3. اختر Agent الذي سيكون الافتراضي للرسائل المباشرة والمساحات غير المرتبطة
4. أدخل Bot Name (لمرجعك في لوحة الإدارة)
5. انقر على Connect Bot
6. انسخ Verification Code المعروض (الصيغة: VERIFY-XXXXXX)

3. أكمل التحقّق من الروبوت

بعد إنشاء عملية الدمج، ستتلقّى رمز تحقّق:

1. افتح Google Chat
2. انقر على Start a chat ← Find apps
3. ابحث عن روبوت المنصّة
4. ابدأ رسالة مباشرة مع الروبوت
5. أرسل رمز التحقّق (مثل VERIFY-ABC123)
6. سيؤكّد الروبوت: “Setup complete! Your workspace (yourdomain.com) is now connected. Send a message to start chatting!”

ستتغيّر حالة عملية الدمج من “Pending Verification” إلى “Active”.

استخدام الروبوت

الرسائل المباشرة

يمكن للمستخدمين بدء محادثة:

1. افتح Google Chat
2. انقر على Start a chat ← Find apps
3. ابحث عن اسم روبوتك
4. ابدأ التحدّث بشكل طبيعي — يردّ الروبوت على كل الرسائل في الرسائل المباشرة

تُعالَج الرسائل المباشرة دائمًا بواسطة الـ Agent الافتراضي.

في المساحات (Spaces)

أضف الروبوت إلى مساحة:

1. افتح المساحة
2. انقر على اسم المساحة ← Manage apps
3. أضف روبوتك
4. أشِر إلى الروبوت بـ @Cuneiform Chat للتفاعل — يردّ الروبوت فقط على @mentions في المساحات

توجيه الـ Agent على مستوى المساحة

يمكن لكل مساحة اختياريًا استخدام Agent مختلف عن الافتراضي. استخدم أوامر الروبوت هذه في مساحة (تتطلّب @mention):

كيف يعمل التوجيه:

• الرسائل المباشرة ← تستخدم دائمًا الـ Agent الافتراضي
• مساحة بـ Agent مخصّص ← تستخدم الـ Agent المُعيَّن
• مساحة بلا Agent مخصّص ← ترجع إلى الـ Agent الافتراضي

الوعي بسجلّ السلاسل

افتراضيًا، يرى الروبوت فقط الرسالة التي أشارت إليه مباشرةً بـ @mention. إذا أرسل أعضاء الفريق رسائل سياق أولًا (في سلاسل أخرى أو في وقت سابق في المساحة) ثم أشاروا إلى الروبوت، فلن يكون لديه ذلك السياق — ما لم يشغّل مدير مساحة /connect.

كيف يعمل

1. يرسل مدير مساحة @Cuneiform Chat /connect في المساحة
2. يرسل الروبوت رابط تصريح لمرة واحدة (تنتهي صلاحيته خلال 10 دقائق)
3. ينقر المدير على الرابط ويسجّل الدخول بحساب Google Workspace الخاص به
4. يمكن للروبوت الآن قراءة الرسائل المرسلة في المساحة خلال آخر 15 دقيقة قبل كل @mention

بمجرّد الاتصال، عند كل @mention يقرأ الروبوت تلقائيًا رسائل المساحة الأخيرة كسياق — فيفهم ما كان الفريق يناقشه قبل أن يُشار إليه.

مثال: ينشر أعضاء الفريق “what are the pricing plans?” و”what’s included in starter?” ثم يشيرون إلى الروبوت بـ “can you help?” — يرى الروبوت الرسائل الثلاث ويردّ بسياق كامل.

المتطلّبات والخصوصية

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

إعادة التصريح

إذا فقد الروبوت الوصول (مثلًا، إذا أُلغي الرمز في حساب Google الخاص بك)، فسيُخطر المساحة:

⚠️ Thread history access has expired or been revoked. A space manager should run /connect to restore it.

شغّل /connect مرة أخرى لاستعادة الوصول.

الميزات

الردود غير المتزامنة

عندما ترسل رسالة، يردّ الروبوت فورًا بإقرار مختصر (مثل “Working on it…”) ثم يقدّم الإجابة الكاملة بمجرّد اكتمال المعالجة. يستغرق هذا عادةً 3–8 ثوانٍ حسب تعقيد سؤالك.

ذاكرة المحادثة

يتذكّر الروبوت السياق ضمن الجلسة، فيمكنك طرح أسئلة متابعة دون تكرار نفسك.

الوعي بسياق المساحة (اختياري): بعد أن يشغّل مدير مساحة /connect، يقرأ الروبوت الرسائل المرسلة في المساحة خلال آخر 15 دقيقة قبل كل @mention — فيفهم ما كان الفريق يناقشه بالفعل دون حاجتك إلى تكرار السياق. راجع الوعي بسجلّ السلاسل أدناه لخطوات الإعداد.

وضع الرسائل في قائمة الانتظار

إذا أرسلت رسائل إضافية بينما لا يزال الروبوت يعالج، تُوضَع في قائمة الانتظار وتُضمَّن في الرد التالي. سترى رسالة مثل “I’m still working on your previous question. I’ll include this in my next response.”

أمر /help

اكتب /help أو help لرؤية تعليمات الاستخدام، بما في ذلك أوامر المساحة المتاحة.

الوصول القائم على النطاق

يمكن فقط للمستخدمين من نطاق Google Workspace الخاص بك التفاعل مع روبوتك، ما يضمن أمانًا على مستوى المؤسّسات.

الردود النصية

يردّ الروبوت برسائل نصية فقط. الصور والملفات والأزرار التفاعلية ومرفقات البطاقات غير مدعومة. تُحدَّد الردود بنحو 30,000 حرف.

إدارة عملية الدمج

تعرض كل بطاقة دمج:

• اسم الروبوت - الاسم المعروض الذي ضبطته
• شارة الحالة - Active أو Pending Verification أو Error
• اسم النطاق - نطاق Google Workspace الخاص بك (بعد التحقّق)
• الـ Agent الافتراضي - قائمة منسدلة لتغيير الـ Agent الافتراضي (يُستخدم للرسائل المباشرة + المساحات غير المرتبطة)
• Space mappings - قسم قابل للطيّ يُظهر أي المساحات لها تعيينات Agent مخصّصة
• Space commands - قسم قابل للطيّ يُظهر أوامر الروبوت المتاحة
• طابع زمني لـ Last activity

الإجراءات المتاحة

استكشاف الأخطاء وإصلاحها

الروبوت لا يظهر في Google Chat

1. تأكّد من استخدامك حساب Google Workspace (وليس Gmail شخصي)
2. ابحث عن اسم الروبوت في “Find apps”
3. انتظر بضع دقائق حتى ينتشر التطبيق

قسم Google Chat غير مرئي

1. يظهر Google Chat فقط للمؤسّسات التي تستخدم Google Workspace
2. إذا كانت مؤسّستك تستخدم مزوّد بريد إلكتروني مختلفًا (مثل Microsoft 365)، يكون القسم مخفيًا
3. يكتشف النظام مزوّد بريدك الإلكتروني تلقائيًا عبر سجلّات MX

مشكلات التحقّق من النطاق

1. قد تستغرق تغييرات DNS حتى 48 ساعة للانتشار — انتظر وجرّب Verify Now مرة أخرى
2. تحقّق من إضافتك سجلّ TXT بالقيم الدقيقة المعروضة في Settings > Domains
3. تحقّق من أن السجلّ على النطاق الصحيح (مثل _cuneiform-verify.yourdomain.com)
4. استخدم روابط مزوّد DNS السريعة على بطاقة التحقّق للوصول السهل

رمز التحقّق لا يعمل

1. تأكّد من إرسالك الرمز من بريد Google Workspace الإلكتروني الخاص بك
2. تحقّق من إدخال الرمز تمامًا كما هو معروض (بما في ذلك البادئة VERIFY-)
3. تحقّق من أن عملية الدمج لا تزال في حالة “Pending Verification”
4. جرّب إنشاء عملية دمج جديدة إذا انتهت صلاحية الرمز

الروبوت يقول “Working on it…” لكن لا يتبعه رد

1. يعالج الروبوت الرسائل بشكل غير متزامن — انتظر حتى 25 ثانية للرد الكامل
2. إذا لم يصل رد، جرّب إرسال رسالتك مرة أخرى
3. تحقّق من أن الـ Agent المرتبط مُعدّ بشكل صحيح

الرسائل لا تُعالَج

1. تأكّد من أن مساحة عملك مُتحقَّق منها (يجب أن تكون الحالة “Active”)
2. بالنسبة للمساحات، تأكّد من أنك تشير إلى الروبوت بـ @mention
3. تحقّق من أن الـ Agent المرتبط مُعدّ بشكل صحيح

رسالة “Organization hasn’t connected”

هذا يعني أن الروبوت لا يتعرّف على نطاق Google Workspace الخاص بك:

1. لم ينشئ مسؤولك عملية الدمج بعد
2. لم يُتحقَّق من النطاق برمز تحقّق
3. أنت تراسل من حساب Gmail شخصي (غير مدعوم)

/set-agent يقول إن الـ Agent غير موجود

1. تحقّق من اسم الـ Agent الدقيق في لوحة الإدارة (حسّاس لحالة الأحرف)
2. تأكّد من أن الـ Agent في حالة “Active”
3. أسماء الـ Agents التي تحتوي على مسافات مدعومة — اكتب الاسم الكامل بعد /set-agent

/connect يقول “Only space managers can run /connect”

يجب أن تكون مدير مساحة لتشغيل /connect. اطلب من مدير مساحة في مساحتك تشغيل الأمر.

انتهت صلاحية رابط تصريح /connect

الرابط صالح لمدة 10 دقائق. شغّل @Cuneiform Chat /connect مرة أخرى للحصول على رابط جديد.

الروبوت يقول “Thread history access has expired”

يحتاج مدير مساحة إلى تشغيل @Cuneiform Chat /connect مرة أخرى لإعادة التصريح. يحدث هذا عند إلغاء رمز Google OAuth (مثلًا، في إعدادات حساب Google).

الأمان

• التحقّق من ملكية النطاق — يثبت سجلّ DNS TXT أن مؤسّستك تملك النطاق قبل الاتصال
• اكتشاف Google Workspace — يؤكّد فحص سجلّ MX أن نطاقك يستخدم Google Workspace
• العزل القائم على النطاق — يمكن فقط لمستخدمي Google Workspace في مؤسّستك التفاعل مع روبوتك
• التحقّق من الـ Webhook — يُتحقَّق من كل طلب وارد مقابل مشروع Google Cloud الخاص بمنصّتك
• رموز التحقّق للاستخدام مرة واحدة ومرتبطة بنطاقك
• تُعالَج الرسائل عبر اتصالات آمنة ومُشفَّرة

قطع الاتصال

لإزالة دمج Google Chat:

1. انتقل إلى Integrations من الشريط الجانبي
2. اعثر على بطاقة دمج Google Chat الخاصة بك
3. انقر على القائمة ثلاثية النقاط
4. اختر Disconnect

ملاحظات مهمّة

• Google Workspace مطلوب: لا يمكن لحسابات Gmail الشخصية استخدام عملية الدمج هذه. إذا كانت مؤسّستك لا تستخدم Google Workspace، فلن يظهر قسم Google Chat.
• التحقّق من النطاق مطلوب: تحقّق من نطاقك في Settings > Domains قبل ربط Google Chat.
• عملية دمج واحدة لكل مؤسّسة: يمكن لكل مؤسّسة أن تملك دمج Google Chat واحدًا
• نص فقط: لا يدعم الروبوت الصور أو الملفات أو الأزرار التفاعلية
• مُدار على مستوى المؤسّسة: يُضبَط Google Chat في صفحة Integrations، وليس لكل Agent
• توجيه المساحة: استخدم /set-agent في المساحات لتعيين Agents متخصّصة لفِرق مختلفة
• الـ Agent الافتراضي: غيّر الـ Agent الافتراضي في أي وقت باستخدام القائمة المنسدلة — بلا حاجة لقطع الاتصال