Google Calendar

Google Calendar diuruskan melalui fungsi kalkulator: chatbot berkomunikasi dengan API Google menggunakan akaun perkhidmatan anda. Tidak perlu mengkonfigurasi permintaan HTTP yang berasingan.

Keperluan

Projek Google Cloud dengan API Google Calendar diaktifkan.
Akaun perkhidmatan untuk projek ini dan kuncinya dalam format JSON.
Kalendar di mana akaun perkhidmatan mempunyai kebenaran untuk mengubah suai acara.

Cara Membuat Akaun Perkhidmatan dan Mendapatkan Kunci

Pergi ke Google Cloud Console dan buat projek baharu.

Pergi ke APIs & Services → Library, cari Google Calendar API, dan klik Enable. Tanpa langkah ini, semua permintaan akan mengembalikan ralat.

Pergi ke IAM & Admin → Service Accounts, buat akaun perkhidmatan, dan berikan peranan Owner.

Buka akaun perkhidmatan yang anda buat → tab Keys → Add key → Create new key → pilih JSON.

Fail kunci akan dimuat turun ke komputer anda.

Simpan alamat akaun perkhidmatan — medan client_email dalam fail yang dimuat turun, contohnya [email protected]. Anda akan memerlukannya untuk memberikan akses akaun perkhidmatan kepada kalendar.

Tempat Menyimpan Kunci: Pembolehubah `calendar_json_keys`

Muat naik fail JSON yang dimuat turun ke storan fail projek di mana anda bekerja dengan Google Calendar, kemudian klik kanan fail dan salin pautannya.

Dalam Project Constants, tambah pembolehubah bernama calendar_json_keys dan tetapkan nilainya kepada tatasusunan kunci:

Dengan kata lain, tampal pautan yang anda salin untuk fail kunci yang dimuat naik ke projek anda.

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

Anda boleh menentukan beberapa kunci, contohnya jika anda menggunakan projek yang berbeza. Untuk setiap permintaan, pembina akan menggunakan salah satu daripadanya:

[
  "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"
]

Daripada pautan, anda boleh memberikan keseluruhan kunci secara langsung dari fail yang dimuat naik:

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

Cara Memberikan Akses Akaun Perkhidmatan kepada Kalendar

Buka tetapan kalendar yang diperlukan → Share with people or groups → Add people and groups → masukkan client_email akaun perkhidmatan dan berikan kebenaran Make changes to events.

Tanpa kebenaran ini, Google mengembalikan Not Found walaupun kalendar wujud.

Kalendar yang dibuat menggunakan gcal_create_calendar tersedia serta-merta kepada akaun perkhidmatan, jadi anda tidak perlu berkongsinya secara berasingan.

Cara Mencari ID Kalendar

Buka tetapan kalendar → Integrate calendar → Calendar ID.

ID kelihatan lebih kurang seperti ini:

[email protected]

Anda juga boleh mendapatkan ID semua kalendar yang tersedia menggunakan:

gcal_calendars_list()

Cara Memanggil Fungsi, Format Tarikh, dan Zon Waktu

Fungsi, termasuk semua fungsi yang disenaraikan di bawah, dimasukkan dalam kalkulator di pembina chatbot.

Ia mudah untuk menyimpan hasil terus ke pembolehubah:

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

Setiap fungsi mengembalikan respons API Google dalam format JSON. Jika ralat berlaku, respons kelihatan seperti ini:

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

Anda boleh mendapatkan medan tertentu daripada respons menggunakan fungsi get.

Contohnya:

get(event, 'id')

Format Nilai

Nilai	Format	Contoh
Tarikh dan masa	`dd.mm.yyyy HH:MM`	`20.08.2026 14:00`
Tarikh (acara sepanjang hari)	`dd.mm.yyyy`	`20.08.2026`
Zon waktu	Pengecam IANA	`Europe/Moscow`, `Europe/Istanbul`

Jika tiada zon waktu ditentukan, zon waktu yang dikonfigurasikan dalam tetapan projek digunakan.

Kalendar

Cara Membuat Kalendar

Gunakan fungsi berikut:

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

Parameter:

name — nama kalendar;
description — penerangan kalendar;
time_zone — zon waktu;
location — lokasi;
owner_email — alamat e-mel akaun Google yang akan menerima kebenaran pemilik. Akaun perkhidmatan akan mengekalkan akses kepada kalendar.

Contoh:

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

Fungsi mengembalikan data kalendar yang dibuat:

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

Simpan ID dari medan id ke pembolehubah projek — ia diperlukan oleh semua fungsi lain.

Cara Mendapatkan Maklumat Kalendar

gcal_get_calendar(calendar_id)

Fungsi mengembalikan nama kalendar, penerangan, zon waktu, dan alamat.

Cara Mendapatkan Senarai Kalendar Akaun Perkhidmatan

gcal_calendars_list()

Fungsi mengembalikan semua kalendar yang boleh diakses oleh akaun perkhidmatan, bersama dengan ID mereka.

Cara Memadam Kalendar

gcal_remove_calendar(calendar_id)

Jika kalendar dipadam dengan berjaya, fungsi mengembalikan:

{"status": true}

Acara

Cara Menambah Acara dengan Cepat

Gunakan fungsi berikut:

gcal_quick_add_event(calendar_id, event_name)

Google akan menghuraikan tarikh dan masa secara automatik daripada teks.

Contoh:

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

Cara Menambah Acara

Gunakan fungsi berikut:

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

Parameter:

calendar_id — ID kalendar;
event_name — nama acara;
start_datetime — tarikh dan masa mula acara;
end_datetime — tarikh dan masa tamat acara;
event_description — penerangan acara;
location — lokasi acara;
time_zone — zon waktu;
extra_params — parameter tambahan acara dalam format JSON.

Contoh:

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}')

Parameter Tambahan `extra_params`

extra_params ialah objek JSON yang mengandungi parameter pilihan:

Parameter	Penerangan
`email_minutes`	Menghantar peringatan e-mel beberapa minit sebelum acara
`popup_minutes`	Menunjukkan peringatan pop timbul beberapa minit sebelum acara
`start_date`	Tarikh mula untuk acara sepanjang hari
`end_date`	Tarikh tamat untuk acara sepanjang hari
`transparency`	`opaque` — masa ditandakan sebagai sibuk; `transparent` — masa kekal tersedia
`recurrence_days`	Hari dalam minggu untuk ulangan mingguan: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`, dipisahkan dengan koma
`recurrence_until`	Tarikh sehingga acara berulang, contohnya `20261231T000000Z`
`recurrence_count`	Bilangan kejadian dan bukannya tarikh tamat

Nilai lalai ialah:

transparency = opaque

Ini bermakna masa acara dianggap sibuk.

Untuk mengekalkan masa acara tersedia:

{"transparency": "transparent"}

Acara Sepanjang Hari

Untuk acara sepanjang hari, hantar start_date dan end_date melalui extra_params dan bukannya start_datetime dan end_datetime.

Contoh acara sepanjang hari yang berulang pada hari Isnin dan Rabu sebanyak 10 kali:

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}')

Untuk acara sepanjang hari, Google menganggap tarikh tamat sebagai eksklusif. Untuk mencipta acara yang hanya menduduki 01.09.2026, nyatakan 02.09.2026 sebagai end_date.

Respons Semasa Mencipta Acara

Fungsi mengembalikan acara yang dibuat:

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

Simpan id acara ke pembolehubah klien.

Contohnya:

event_id = get(event, 'id')

Anda akan memerlukan ID kemudian untuk mengemas kini, memindahkan, atau memadam acara.

Cara Mengemas Kini Acara

Gunakan fungsi berikut:

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)

Hantar hanya medan yang anda mahu ubah. Semua medan lain akan kekal tidak berubah.

Contohnya, untuk menjadualkan semula acara sedia ada ke 21.08.2026 dari 16:00 hingga 17:00:

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

Struktur extra_params adalah sama seperti untuk gcal_add_event.

Peringatan dikemas kini mengikut jenis.

Contohnya, jika anda hanya hantar:

{"popup_minutes": 30}

peringatan pop timbul akan diganti, manakala peringatan e-mel sedia ada akan kekal tidak berubah.

Cara Mendapatkan Senarai Acara

Gunakan fungsi berikut:

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

Parameter:

calendar_id — ID kalendar;
start_date — permulaan tempoh dalam format dd.mm.yyyy;
end_date — akhir tempoh dalam format dd.mm.yyyy.

Contoh:

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

Jika tiada tarikh ditentukan, fungsi mengembalikan acara untuk hari semasa:

events = gcal_get_event_list("[email protected]")

Acara disusun mengikut masa mula.

Acara berulang dikembalikan sebagai entri berasingan.

Cara Mendapatkan Maklumat Acara

Gunakan fungsi berikut:

gcal_get_event(calendar_id, event_id)

Fungsi ini mengembalikan semua data acara, termasuk:

nama;
penerangan;
tarikh dan masa;
lokasi;
peserta;
peringatan;
parameter acara lain.

Contoh:

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

Cara Memindahkan Acara ke Kalendar Lain

Gunakan fungsi berikut:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

di mana:

calendar_id — ID kalendar semasa;
event_id — ID acara;
destination_calendar_id — ID kalendar destinasi untuk acara dipindahkan.

Contoh:

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

Cara Memadam Acara

Gunakan fungsi berikut:

gcal_remove_event(calendar_id, event_id)

Contoh:

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

Jika acara berjaya dipadam, fungsi mengembalikan:

{"status": true}

Peserta Acara

Cara Menambah Peserta

Gunakan fungsi berikut:

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

Parameter:

calendar_id — ID kalendar;
event_id — ID acara;
client_email — alamat e-mel peserta;
name — nama yang akan dipaparkan dalam kalendar;
comment — komen untuk peserta.

Contoh:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Ditempah melalui bot")

Jika peserta ini telah ditambah ke acara, fungsi mengembalikan ralat:

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

Cara Membuang Peserta

Gunakan fungsi berikut:

gcal_remove_client(calendar_id, event_id, client_email)

Parameter:

calendar_id — ID kalendar;
event_id — ID acara;
client_email — alamat e-mel peserta untuk dibuang.

Contoh:

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

Jika peserta yang ditentukan tiada dalam acara, fungsi mengembalikan:

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

Ralat yang Mungkin Berlaku

Jika ralat berlaku, fungsi mengembalikan objek dalam format berikut:

{
  "status": false,
  "err": "penerangan ralat"
}

Ralat biasa:

Respons	Punca
`Not Found`	Kalendar tidak dikongsi dengan akaun perkhidmatan, atau `calendar_id` yang salah ditentukan
`Google Calendar API has not been used in project ... or it is disabled`	API Kalendar Google tidak diaktifkan dalam projek Google Cloud
`The key to access the calendar was not found in the passed link`	Pautan dalam `calendar_json_keys` tidak mengembalikan fail kunci
`wrong datetime "...", expected format is dd.mm.yyyy HH:MM`	Tarikh dan masa diberikan dalam format yang salah
`wrong date "...", expected format is dd.mm.yyyy`	Tarikh diberikan dalam format yang salah
`Работает только на тарифах Бизнес и Инфобиз`	Projek tidak mempunyai langganan aktif yang merangkumi akses kepada ciri ini

Ralat `Not Found`

Jika Google mengembalikan:

Not Found

semak perkara berikut:

Pastikan calendar_id adalah betul.
Pastikan client_email akaun perkhidmatan telah ditambah ke tetapan kalendar.
Pastikan akaun perkhidmatan mempunyai kebenaran Buat perubahan pada acara.

Walaupun kalendar wujud, Google mungkin mengembalikan Not Found jika akaun perkhidmatan tidak mempunyai akses kepadanya.

API Kalendar Google Tidak Diaktifkan

Ralat ini kelihatan lebih kurang seperti ini:

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

Buka projek anda dalam Google Cloud dan aktifkan:

APIs & Services → Library → Google Calendar API → Enable

Selepas mengaktifkan API, ulangi permintaan.

Kunci Akaun Perkhidmatan Tidak Ditemui

Ralat:

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

Semak nilai:

calendar_json_keys

Jika anda menggunakan pautan fail, ia mesti mengembalikan fail JSON yang mengandungi kunci akaun perkhidmatan secara langsung.

Contoh:

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

Anda juga boleh memberikan kunci secara langsung dalam calendar_json_keys sebagai objek JSON.

Format Tarikh dan Masa Salah

Ralat:

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

Format yang betul:

dd.mm.yyyy HH:MM

Contoh:

20.08.2026 14:00

Contoh yang salah:

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

Jika fungsi menjangkakan kedua-dua tarikh dan masa, anda mesti memberikan tarikh bersama jam dan minit.

Format Tarikh Salah

Ralat:

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

Format yang betul:

dd.mm.yyyy

Contoh:

20.08.2026

Tiada Pelan Langganan Layak

Ralat:

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

Ini bermakna projek tidak mempunyai langganan aktif yang membenarkan penggunaan fungsi Kalendar Google.

Contoh Pantas

Cipta acara dan simpan IDnya:

event = gcal_add_event("[email protected]", "Konsultasi #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Telefon pelanggan: #{phone}", "Zoom", "Europe/Moscow")

event_id = get(event, 'id')

Tambah pelanggan ke acara yang dicipta:

event = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Ditempah melalui bot")

Jika pelanggan memutuskan untuk menjadualkan semula:

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

Jika pelanggan membatalkan tempahan:

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

Ralat API Google dikembalikan tanpa perubahan dalam medan err. Mesej ralat membantu menentukan apa yang hilang: akses kalendar, API yang diaktifkan, kunci yang sah, format tarikh yang betul, atau acara sedia ada.

Google Calendar

Keperluan

Cara Membuat Akaun Perkhidmatan dan Mendapatkan Kunci

Tempat Menyimpan Kunci: Pembolehubah calendar_json_keys

Cara Memberikan Akses Akaun Perkhidmatan kepada Kalendar

Cara Mencari ID Kalendar

Cara Memanggil Fungsi, Format Tarikh, dan Zon Waktu

Format Nilai

Kalendar

Cara Membuat Kalendar

Cara Mendapatkan Maklumat Kalendar

Cara Mendapatkan Senarai Kalendar Akaun Perkhidmatan

Cara Memadam Kalendar

Acara

Cara Menambah Acara dengan Cepat

Cara Menambah Acara

Parameter Tambahan extra_params

Acara Sepanjang Hari

Respons Semasa Mencipta Acara

Cara Mengemas Kini Acara

Cara Mendapatkan Senarai Acara

Cara Mendapatkan Maklumat Acara

Cara Memindahkan Acara ke Kalendar Lain

Cara Memadam Acara

Peserta Acara

Cara Menambah Peserta

Cara Membuang Peserta

Ralat yang Mungkin Berlaku

Ralat Not Found

API Kalendar Google Tidak Diaktifkan

Kunci Akaun Perkhidmatan Tidak Ditemui

Format Tarikh dan Masa Salah

Format Tarikh Salah

Tiada Pelan Langganan Layak

Contoh Pantas

Tempat Menyimpan Kunci: Pembolehubah `calendar_json_keys`

Parameter Tambahan `extra_params`

Ralat `Not Found`