تقويم Google

08-05-2026

في هذه الصفحة

يتم إدارة تقويم Google من خلال دوال الحاسبة: يتواصل chatbot مع Google API باستخدام حساب الخدمة الخاص بك. ليست هناك حاجة لتكوين طلبات HTTP منفصلة.

المتطلبات

مشروع Google Cloud مع تفعيل Google Calendar API.
حساب خدمة لهذا المشروع ومفتاحه بتنسيق JSON.
تقويم حيث يمتلك حساب الخدمة إذنًا لتعديل الأحداث.

كيفية إنشاء حساب خدمة والحصول على مفتاح

انتقل إلى Google Cloud Console وأنشئ مشروعًا جديدًا.

انتقل إلى APIs & Services ← Library، وابحث عن Google Calendar API، وانقر على Enable. بدون هذه الخطوة، ستعيد جميع الطلبات خطأً.

انتقل إلى IAM & Admin ← Service Accounts، وأنشئ حساب خدمة، وامنحه دور Owner.

افتح حساب الخدمة الذي أنشأته ← علامة التبويب Keys ← Add key ← Create new key ← حدد JSON.

سيتم تنزيل ملف المفتاح إلى جهاز الكمبيوتر الخاص بك.

احفظ عنوان حساب الخدمة — حقل client_email في الملف الذي تم تنزيله، على سبيل المثال [email protected]. ستحتاج إليه لمنح حساب الخدمة حق الوصول إلى التقويم.

أين تخزن المفتاح: متغير `calendar_json_keys`

ارفع ملف JSON الذي تم تنزيله إلى تخزين الملفات للمشروع الذي تعمل فيه مع Google Calendar، ثم انقر بزر الماوس الأيمن على الملف وانسخ رابطه.

في Project Constants، أضف متغيرًا باسم calendar_json_keys واضبط قيمته على مصفوفة من المفاتيح:

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

["https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json"]

يمكنك تحديد مفاتيح متعددة، على سبيل المثال إذا كنت تستخدم مشاريع مختلفة. لكل طلب، سيستخدم البناء واحدًا منها:

[
  "https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json",
  "https://files.mavibot.ai/uploads/file_item/file/your_project_id/your_file_name.json"
]

بدلاً من الرابط، يمكنك تقديم المفتاح بأكمله مباشرة من الملف الذي تم رفعه:

[
  {
    "type": "service_account",
    "project_id": "my-project",
    "private_key": "-----BEGIN PRIVATE KEY-----...",
    "client_email": "[email protected]",
    "..."
  }
]

كيفية منح حساب الخدمة حق الوصول إلى تقويم

افتح إعدادات التقويم المطلوب ← Share with people or groups ← Add people and groups ← أدخل client_email لحساب الخدمة وامنح إذن Make changes to events.

بدون هذا الإذن، يعيد Google Not Found حتى إذا كان التقويم موجودًا.

التقويم الذي تم إنشاؤه باستخدام gcal_create_calendar متاح فورًا لحساب الخدمة، لذلك لا تحتاج إلى مشاركته بشكل منفصل.

كيفية العثور على معرف التقويم

افتح إعدادات التقويم ← Integrate calendar ← Calendar ID.

يبدو المعرف تقريبًا كما يلي:

[email protected]

يمكنك أيضًا الحصول على معرفات جميع التقاويم المتاحة باستخدام:

gcal_calendars_list()

كيفية استدعاء الدوال، تنسيقات التاريخ، والمناطق الزمنية

تُدخل الدوال، بما في ذلك جميع الدوال المذكورة أدناه، في الحاسبة في منشئ chatbot.

من الملائم حفظ النتيجة مباشرة في متغير:

event = gcal_add_event("[email protected]", "Consultation", "20.08.2026 14:00", "20.08.2026 15:00")

كل دالة تعيد استجابة Google API بتنسيق JSON. إذا حدث خطأ، تبدو الاستجابة كما يلي:

{"status": false, "err": "error description"}

يمكنك استرداد حقل معين من الاستجابة باستخدام دالة get.

على سبيل المثال:

get(event, 'id')

تنسيقات القيم

القيمة	التنسيق	مثال
التاريخ والوقت	`dd.mm.yyyy HH:MM`	`20.08.2026 14:00`
التاريخ (حدث ليوم كامل)	`dd.mm.yyyy`	`20.08.2026`
المنطقة الزمنية	معرف IANA	`Europe/Moscow`, `Europe/Istanbul`

إذا لم يتم تحديد منطقة زمنية، يتم استخدام المنطقة الزمنية المكونة في إعدادات المشروع.

التقاويم

كيفية إنشاء تقويم

استخدم الدالة التالية:

gcal_create_calendar(name, description=null, time_zone=null, location=null, owner_email=null)

المعلمات:

name — اسم التقويم؛
description — وصف التقويم؛
time_zone — المنطقة الزمنية؛
location — الموقع؛
owner_email — عنوان البريد الإلكتروني لحساب Google الذي سيحصل على أذونات المالك. سيحتفظ حساب الخدمة بالوصول إلى التقويم.

مثال:

calendar = gcal_create_calendar("Consultation Bookings", "Bot calendar", "Europe/Moscow", "", "[email protected]")

تعيد الدالة بيانات التقويم الذي تم إنشاؤه:

{
  "kind": "calendar#calendar",
  "id": "[email protected]",
  "summary": "Consultation Bookings",
  "timeZone": "Europe/Moscow"
}

احفظ المعرف من حقل id في متغير مشروع — فهو مطلوب لجميع الدوال الأخرى.

كيفية الحصول على معلومات التقويم

gcal_get_calendar(calendar_id)

تعيد الدالة اسم التقويم ووصفه ومنطقته الزمنية وعنوانه.

كيفية الحصول على قائمة تقاويم حساب الخدمة

gcal_calendars_list()

تعيد الدالة جميع التقاويم التي يمكن لحساب الخدمة الوصول إليها، مع معرفاتها.

كيفية حذف تقويم

gcal_remove_calendar(calendar_id)

إذا تم حذف التقويم بنجاح، تعيد الدالة:

{"status": true}

الأحداث

كيفية إضافة حدث بسرعة

استخدم الدالة التالية:

gcal_quick_add_event(calendar_id, event_name)

سيقوم Google تلقائيًا بتحليل التاريخ والوقت من النص.

مثال:

event = gcal_quick_add_event("[email protected]", "Meeting with John tomorrow at 15:00")

كيفية إضافة حدث

استخدم الدالة التالية:

gcal_add_event(calendar_id, event_name, start_datetime=null, end_datetime=null, event_description=null, location=null, time_zone=null, extra_params=null)

المعلمات:

calendar_id — معرف التقويم؛
event_name — اسم الحدث؛
start_datetime — تاريخ ووقت بدء الحدث؛
end_datetime — تاريخ ووقت انتهاء الحدث؛
event_description — وصف الحدث؛
location — موقع الحدث؛
time_zone — المنطقة الزمنية؛
extra_params — معلمات إضافية للحدث بتنسيق JSON.

مثال:

event = gcal_add_event("[email protected]", "Consultation #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Client phone: #{phone}", "Zoom", "Europe/Moscow", '{"popup_minutes": 30, "email_minutes": 60}')

معلمات `extra_params` الإضافية

extra_params هو كائن JSON يحتوي على معلمات اختيارية:

المعلمة	الوصف
`email_minutes`	يرسل تذكيرًا بالبريد الإلكتروني قبل الحدث بالدقائق المحددة
`popup_minutes`	يعرض تذكيرًا منبثقًا قبل الحدث بالدقائق المحددة
`start_date`	تاريخ البدء لحدث ليوم كامل
`end_date`	تاريخ الانتهاء لحدث ليوم كامل
`transparency`	`opaque` — يتم وضع علامة على الوقت كمشغول؛ `transparent` — يظل الوقت متاحًا
`recurrence_days`	أيام الأسبوع للتكرار الأسبوعي: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`, مفصولة بفواصل
`recurrence_until`	التاريخ الذي يتكرر فيه الحدث حتى، على سبيل المثال `20261231T000000Z`
`recurrence_count`	عدد مرات التكرار بدلاً من تاريخ الانتهاء

القيمة الافتراضية هي:

transparency = opaque

هذا يعني أن وقت الحدث يعتبر مشغولاً.

لإبقاء وقت الحدث متاحًا:

{"transparency": "transparent"}

حدث ليوم كامل

لحدث ليوم كامل، مرر start_date و end_date عبر extra_params بدلاً من start_datetime و end_datetime.

مثال لحدث ليوم كامل يتكرر أيام الاثنين والأربعاء 10 مرات:

event = gcal_add_event("[email protected]", "Webinar", null, null, "Weekly webinar", "", null, '{"start_date": "01.09.2026", "end_date": "02.09.2026", "recurrence_days": "MO,WE", "recurrence_count": 10}')

بالنسبة للأحداث ليوم كامل، يعامل Google تاريخ الانتهاء على أنه حصري. لإنشاء حدث يشغل فقط 01.09.2026، حدد 02.09.2026 كـ end_date.

الاستجابة عند إنشاء حدث

تعيد الدالة الحدث الذي تم إنشاؤه:

{
  "kind": "calendar#event",
  "id": "7b1k2m3n4o5p",
  "status": "confirmed",
  "htmlLink": "https://www.google.com/calendar/event?eid=..."
}

احفظ معرف الحدث id في متغير عميل.

على سبيل المثال:

event_id = get(event, 'id')

ستحتاج إلى المعرف لاحقًا لتحديث الحدث أو نقله أو حذفه.

كيفية تحديث حدث

استخدم الدالة التالية:

gcal_update_event(calendar_id, event_id, event_name=null, start_datetime=null, end_datetime=null, event_description=null, location=null, time_zone=null, extra_params=null)

مرر فقط الحقول التي تريد تغييرها. ستبقى جميع الحقول الأخرى دون تغيير.

على سبيل المثال، لإعادة جدولة حدث موجود إلى 21.08.2026 من 16:00 إلى 17:00:

event = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

بنية extra_params هي نفسها كما في gcal_add_event.

يتم تحديث التذكيرات حسب النوع.

على سبيل المثال، إذا مررت فقط:

{"popup_minutes": 30}

سيتم استبدال التذكير المنبثق، بينما يظل التذكير عبر البريد الإلكتروني الموجود دون تغيير.

كيفية الحصول على قائمة الأحداث

استخدم الدالة التالية:

gcal_get_event_list(calendar_id, start_date=null, end_date=null)

المعلمات:

calendar_id — معرف التقويم؛
start_date — بداية الفترة بتنسيق dd.mm.yyyy؛
end_date — نهاية الفترة بتنسيق dd.mm.yyyy.

مثال:

events = gcal_get_event_list("[email protected]", "20.08.2026", "27.08.2026")

إذا لم يتم تحديد تواريخ، تعيد الدالة أحداث اليوم الحالي:

events = gcal_get_event_list("[email protected]")

يتم إرجاع الأحداث مرتبة حسب وقت البدء.

يتم إرجاع الأحداث المتكررة كإدخالات منفصلة.

كيفية الحصول على معلومات الحدث

استخدم الدالة التالية:

gcal_get_event(calendar_id, event_id)

تُرجع الدالة جميع بيانات الحدث، بما في ذلك:

الاسم؛
الوصف؛
التاريخ والوقت؛
الموقع؛
الحاضرون؛
التذكيرات؛
معلمات الحدث الأخرى.

مثال:

event = gcal_get_event("[email protected]", "#{event_id}")

كيفية نقل حدث إلى تقويم آخر

استخدم الدالة التالية:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

حيث:

calendar_id — معرف التقويم الحالي؛
event_id — معرف الحدث؛
destination_calendar_id — معرف التقويم الذي يجب نقل الحدث إليه.

مثال:

event = gcal_move_event("[email protected]", "#{event_id}", "[email protected]")

كيفية حذف حدث

استخدم الدالة التالية:

gcal_remove_event(calendar_id, event_id)

مثال:

result = gcal_remove_event("[email protected]", "#{event_id}")

إذا تم حذف الحدث بنجاح، تُرجع الدالة:

{"status": true}

الحاضرون في الحدث

كيفية إضافة حاضر

استخدم الدالة التالية:

gcal_add_client(calendar_id, event_id, client_email, name=null, comment=null)

المعلمات:

calendar_id — معرف التقويم؛
event_id — معرف الحدث؛
client_email — البريد الإلكتروني للحاضر؛
name — الاسم الذي سيظهر في التقويم؛
comment — تعليق للحاضر.

مثال:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "تم الحجز عبر البوت")

إذا تمت إضافة هذا الحاضر بالفعل إلى الحدث، تُرجع الدالة خطأ:

{"status": false, "err": "attendee already exists"}

كيفية إزالة حاضر

استخدم الدالة التالية:

gcal_remove_client(calendar_id, event_id, client_email)

المعلمات:

calendar_id — معرف التقويم؛
event_id — معرف الحدث؛
client_email — البريد الإلكتروني للحاضر المراد إزالته.

مثال:

event = gcal_remove_client("[email protected]", "#{event_id}", "#{email}")

إذا لم يكن الحاضر المحدد موجودًا في الحدث، تُرجع الدالة:

{"status": false, "err": "attendee not found"}

الأخطاء المحتملة

في حالة حدوث خطأ، تُرجع الدوال كائنًا بالتنسيق التالي:

{
  "status": false,
  "err": "وصف الخطأ"
}

الأخطاء الشائعة:

الاستجابة	السبب
`Not Found`	لم تتم مشاركة التقويم مع حساب الخدمة، أو تم تحديد `calendar_id` غير صحيح
`Google Calendar API has not been used in project ... or it is disabled`	لم يتم تفعيل Google Calendar API في مشروع Google Cloud
`The key to access the calendar was not found in the passed link`	الرابط في `calendar_json_keys` لا يُرجع ملف المفتاح
`wrong datetime "...", expected format is dd.mm.yyyy HH:MM`	تم تقديم التاريخ والوقت بتنسيق غير صحيح
`wrong date "...", expected format is dd.mm.yyyy`	تم تقديم التاريخ بتنسيق غير صحيح
`Работает только на тарифах Бизнес и Инфобиз`	المشروع ليس لديه اشتراك نشط يتضمن الوصول إلى هذه الميزة

خطأ `Not Found`

إذا أرجع Google:

Not Found

تحقق مما يلي:

تأكد من صحة calendar_id.
تأكد من إضافة client_email لحساب الخدمة إلى إعدادات التقويم.
تأكد من أن حساب الخدمة لديه إذن إجراء تغييرات على الأحداث.

حتى إذا كان التقويم موجودًا، قد يُرجع Google Not Found إذا لم يكن لدى حساب الخدمة حق الوصول إليه.

Google Calendar API غير مفعل

يبدو الخطأ تقريبًا كما يلي:

Google Calendar API has not been used in project ... or it is disabled

افتح مشروعك في Google Cloud وقم بتمكين:

APIs & Services → Library → Google Calendar API → Enable

بعد تمكين API، كرر الطلب.

مفتاح حساب الخدمة غير موجود

الخطأ:

The key to access the calendar was not found in the passed link

تحقق من قيمة:

calendar_json_keys

إذا كنت تستخدم رابط ملف، يجب أن يُرجع مباشرة ملف JSON الذي يحتوي على مفتاح حساب الخدمة.

مثال:

["https://files.salebot.pro/xxxxxxxx/key.json"]

يمكنك أيضًا تقديم المفتاح مباشرة في calendar_json_keys ككائن JSON.

تنسيق التاريخ والوقت غير صحيح

الخطأ:

wrong datetime "...", expected format is dd.mm.yyyy HH:MM

التنسيق الصحيح:

dd.mm.yyyy HH:MM

مثال:

20.08.2026 14:00

أمثلة غير صحيحة:

2026-08-20 14:00
20/08/2026 14:00
20.08.2026

إذا كانت الدالة تتوقع كلاً من التاريخ والوقت، يجب عليك تقديم التاريخ مع الساعات والدقائق.

تنسيق التاريخ غير صحيح

الخطأ:

wrong date "...", expected format is dd.mm.yyyy

التنسيق الصحيح:

dd.mm.yyyy

مثال:

20.08.2026

لا توجد خطة اشتراك مؤهلة

الخطأ:

Работает только на тарифах Бизнес и Инфобиз

هذا يعني أن المشروع ليس لديه اشتراك نشط يسمح باستخدام دوال Google Calendar.

مثال سريع

إنشاء حدث وحفظ معرفه:

event = gcal_add_event("[email protected]", "استشارة #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "هاتف العميل: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

إضافة العميل إلى الحدث الذي تم إنشاؤه:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "تم الحجز عبر البوت")

إذا قرر العميل إعادة الجدولة:

event = gcal_update_event("[email protected]", "#{event_id}", null, "21.08.2026 16:00", "21.08.2026 17:00")

إذا ألغى العميل الحجز:

result = gcal_remove_event("[email protected]", "#{event_id}")

يتم إرجاع أخطاء Google API كما هي في حقل err. تساعد رسالة الخطأ في تحديد ما هو مفقود: الوصول إلى التقويم، أو API مفعل، أو مفتاح صالح، أو تنسيق التاريخ الصحيح، أو حدث موجود.

تقويم Google

المتطلبات

كيفية إنشاء حساب خدمة والحصول على مفتاح

أين تخزن المفتاح: متغير calendar_json_keys

كيفية منح حساب الخدمة حق الوصول إلى تقويم

كيفية العثور على معرف التقويم

كيفية استدعاء الدوال، تنسيقات التاريخ، والمناطق الزمنية

تنسيقات القيم

التقاويم

كيفية إنشاء تقويم

كيفية الحصول على معلومات التقويم

كيفية الحصول على قائمة تقاويم حساب الخدمة

كيفية حذف تقويم

الأحداث

كيفية إضافة حدث بسرعة

كيفية إضافة حدث

معلمات extra_params الإضافية

حدث ليوم كامل

الاستجابة عند إنشاء حدث

كيفية تحديث حدث

كيفية الحصول على قائمة الأحداث

كيفية الحصول على معلومات الحدث

كيفية نقل حدث إلى تقويم آخر

كيفية حذف حدث

الحاضرون في الحدث

كيفية إضافة حاضر

كيفية إزالة حاضر

الأخطاء المحتملة

خطأ Not Found

Google Calendar API غير مفعل

مفتاح حساب الخدمة غير موجود

تنسيق التاريخ والوقت غير صحيح

تنسيق التاريخ غير صحيح

لا توجد خطة اشتراك مؤهلة

مثال سريع

أين تخزن المفتاح: متغير `calendar_json_keys`

معلمات `extra_params` الإضافية

خطأ `Not Found`