Google Takvimi, hesap makinesi fonksiyonları aracılığıyla yönetilir: sohbet robotu, hizmet hesabınızı kullanarak Google API ile iletişim kurar. Ayrı HTTP istekleri yapılandırmanıza gerek yoktur.

Gereksinimler

  1. Google Calendar API'nin etkinleştirildiği bir Google Cloud projesi.
  2. Bu proje için bir hizmet hesabı ve JSON formatında anahtarı.
  3. Hizmet hesabının etkinlikleri değiştirme iznine sahip olduğu bir takvim.

Hizmet Hesabı Oluşturma ve Anahtar Alma

  1. Google Cloud Console adresine gidin ve yeni bir proje oluşturun.

  1. APIs & Services → Library bölümüne gidin, Google Calendar API'yi bulun ve Enable düğmesine tıklayın. Bu adım olmadan tüm istekler hata döndürür.

  1. IAM & Admin → Service Accounts bölümüne gidin, bir hizmet hesabı oluşturun ve ona Owner rolünü atayın.

  1. Oluşturduğunuz hizmet hesabını açın → Keys sekmesi → Add key → Create new key → JSON seçeneğini seçin.

Anahtar dosyası bilgisayarınıza indirilecektir.

  1. Hizmet hesabı adresini kaydedin — indirilen dosyadaki client_email alanı, örneğin [email protected]. Hizmet hesabına takvime erişim izni vermek için buna ihtiyacınız olacak.

Anahtarı Nerede Saklamalı: calendar_json_keys Değişkeni

  1. İndirilen JSON dosyasını Google Calendar ile çalıştığınız projenin dosya deposuna yükleyin, ardından dosyaya sağ tıklayın ve bağlantısını kopyalayın.

  1. Project Constants bölümünde calendar_json_keys adında bir değişken ekleyin ve değerini anahtarlar dizisi olarak ayarlayın:

Başka bir deyişle, projenize yüklediğiniz anahtar dosyası için kopyaladığınız bağlantıyı yapıştırın.

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

Birden fazla anahtar belirtebilirsiniz, örneğin farklı projeler kullanıyorsanız. Her istek için oluşturucu bunlardan birini kullanacaktır:

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

Bağlantı yerine, anahtarın tamamını doğrudan yüklenen dosyadan sağlayabilirsiniz:

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

Hizmet Hesabına Takvime Erişim İzni Verme

İlgili takvimin ayarlarını açın → Share with people or groups → Add people and groups → hizmet hesabının client_email adresini girin ve Make changes to events iznini verin.

Bu izin olmadan, takvim mevcut olsa bile Google Not Found hatası döndürür.

gcal_create_calendar kullanılarak oluşturulan bir takvim, hizmet hesabı için hemen kullanılabilir; bu nedenle ayrıca paylaşmanıza gerek yoktur.

Takvim Kimliğini Bulma

Takvim ayarlarını açın → Integrate calendar → Calendar ID.

Kimlik yaklaşık olarak şuna benzer:

[email protected]

Ayrıca, mevcut tüm takvimlerin kimliklerini şu şekilde alabilirsiniz:

gcal_calendars_list()

Fonksiyonları Çağırma, Tarih Formatları ve Saat Dilimleri

Aşağıda listelenen tüm fonksiyonlar dahil olmak üzere fonksiyonlar, sohbet robotu oluşturucudaki hesap makinesine girilir.

Sonucu doğrudan bir değişkene kaydetmek uygundur:

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

Her fonksiyon, Google API yanıtını JSON formatında döndürür. Bir hata oluşursa, yanıt şöyle görünür:

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

Yanıttan belirli bir alanı get fonksiyonunu kullanarak alabilirsiniz.

Örneğin:

get(event, 'id')

Değer Formatları

Değer Format Örnek
Tarih ve saat dd.mm.yyyy HH:MM 20.08.2026 14:00
Tarih (tüm gün etkinliği) dd.mm.yyyy 20.08.2026
Saat dilimi IANA tanımlayıcısı Europe/Moscow, Europe/Istanbul

Saat dilimi belirtilmezse, proje ayarlarında yapılandırılan saat dilimi kullanılır.

Takvimler

Takvim Oluşturma

Aşağıdaki fonksiyonu kullanın:

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

Parametreler:

  • name — takvim adı;
  • description — takvim açıklaması;
  • time_zone — saat dilimi;
  • location — konum;
  • owner_email — sahip izinlerini alacak Google hesabının e-posta adresi. Hizmet hesabı takvime erişimini koruyacaktır.

Örnek:

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

Fonksiyon, oluşturulan takvim verilerini döndürür:

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

id alanındaki kimliği bir proje değişkenine kaydedin — diğer tüm fonksiyonlar tarafından gereklidir.

Takvim Bilgilerini Alma

gcal_get_calendar(calendar_id)

Fonksiyon, takvim adını, açıklamasını, saat dilimini ve adresini döndürür.

Hizmet Hesabının Takvim Listesini Alma

gcal_calendars_list()

Fonksiyon, hizmet hesabının erişebildiği tüm takvimleri ve kimliklerini döndürür.

Takvim Silme

gcal_remove_calendar(calendar_id)

Takvim başarıyla silinirse, fonksiyon şunu döndürür:

{"status": true}

Etkinlikler

Hızlı Etkinlik Ekleme

Aşağıdaki fonksiyonu kullanın:

gcal_quick_add_event(calendar_id, event_name)

Google, metinden tarihi ve saati otomatik olarak ayrıştırır.

Örnek:

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

Etkinlik Ekleme

Aşağıdaki fonksiyonu kullanın:

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

Parametreler:

  • calendar_id — takvim kimliği;
  • event_name — etkinlik adı;
  • start_datetime — etkinlik başlangıç tarihi ve saati;
  • end_datetime — etkinlik bitiş tarihi ve saati;
  • event_description — etkinlik açıklaması;
  • location — etkinlik konumu;
  • time_zone — saat dilimi;
  • extra_params — JSON formatında ek etkinlik parametreleri.

Örnek:

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

Ek extra_params Parametreleri

extra_params, isteğe bağlı parametreler içeren bir JSON nesnesidir:

Parametre Açıklama
email_minutes Etkinlikten belirtilen dakika önce e-posta hatırlatıcısı gönderir
popup_minutes Etkinlikten belirtilen dakika önce açılır pencere hatırlatıcısı gösterir
start_date Tüm gün etkinliği için başlangıç tarihi
end_date Tüm gün etkinliği için bitiş tarihi
transparency opaque — zaman meşgul olarak işaretlenir; transparent — zaman müsait kalır
recurrence_days Haftalık tekrar için haftanın günleri: MO, TU, WE, TH, FR, SA, SU, virgülle ayrılmış
recurrence_until Etkinliğin tekrarlanacağı tarih, örneğin 20261231T000000Z
recurrence_count Bitiş tarihi yerine tekrar sayısı

Varsayılan değer:

transparency = opaque

Bu, etkinlik zamanının meşgul olarak kabul edildiği anlamına gelir.

Etkinlik zamanını müsait tutmak için:

{"transparency": "transparent"}

Tüm Gün Etkinliği

Tüm gün etkinliği için, start_datetime ve end_datetime yerine extra_params aracılığıyla start_date ve end_date değerlerini iletin.

Pazartesi ve Çarşamba günleri 10 kez tekrarlanan tüm gün etkinliği örneği:

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

Tüm gün etkinlikleri için Google, bitiş tarihini hariç tutar. Yalnızca 01.09.2026 tarihini kapsayan bir etkinlik oluşturmak için end_date olarak 02.09.2026 belirtin.

Etkinlik Oluştururken Yanıt

Fonksiyon, oluşturulan etkinliği döndürür:

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

Etkinlik id değerini bir istemci değişkenine kaydedin.

Örneğin:

event_id = get(event, 'id')

Kimliğe daha sonra etkinliği güncellemek, taşımak veya silmek için ihtiyacınız olacak.

Etkinlik Güncelleme

Aşağıdaki fonksiyonu kullanın:

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)

Yalnızca değiştirmek istediğiniz alanları iletin. Diğer tüm alanlar değişmeden kalacaktır.

Örneğin, mevcut bir etkinliği 21.08.2026 tarihine 16:00'dan 17:00'a yeniden planlamak için:

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

extra_params yapısı gcal_add_event ile aynıdır.

Hatırlatıcılar türe göre güncellenir.

Örneğin, yalnızca şunu iletirseniz:

{"popup_minutes": 30}

açılır pencere hatırlatıcısı değiştirilirken, mevcut e-posta hatırlatıcısı değişmeden kalır.

Etkinlik Listesi Alma

Aşağıdaki fonksiyonu kullanın:

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

Parametreler:

  • calendar_id — takvim kimliği;
  • start_date — dönemin başlangıcı dd.mm.yyyy formatında;
  • end_date — dönemin sonu dd.mm.yyyy formatında.

Örnek:

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

Tarih belirtilmezse, fonksiyon geçerli gün için etkinlikleri döndürür:

etkinlikler = gcal_get_event_list("[email protected]")

Etkinlikler başlangıç saatine göre sıralanmış olarak döndürülür.

Tekrarlanan etkinlikler ayrı girişler olarak döndürülür.

Etkinlik Bilgisi Nasıl Alınır

Aşağıdaki işlevi kullanın:

gcal_get_event(calendar_id, event_id)

İşlev, aşağıdakiler dahil tüm etkinlik verilerini döndürür:

  • ad;
  • açıklama;
  • tarih ve saat;
  • konum;
  • katılımcılar;
  • hatırlatıcılar;
  • diğer etkinlik parametreleri.

Örnek:

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

Bir Etkinlik Başka Bir Takvime Nasıl Taşınır

Aşağıdaki işlevi kullanın:

gcal_move_event(calendar_id, event_id, destination_calendar_id)

burada:

  • calendar_id — geçerli takvimin kimliği;
  • event_id — etkinlik kimliği;
  • destination_calendar_id — etkinliğin taşınacağı takvimin kimliği.

Örnek:

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

Bir Etkinlik Nasıl Silinir

Aşağıdaki işlevi kullanın:

gcal_remove_event(calendar_id, event_id)

Örnek:

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

Etkinlik başarıyla silinirse, işlev şunu döndürür:

{"status": true}

Etkinlik Katılımcıları

Katılımcı Nasıl Eklenir

Aşağıdaki işlevi kullanın:

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

Parametreler:

  • calendar_id — takvim kimliği;
  • event_id — etkinlik kimliği;
  • client_email — katılımcının e-posta adresi;
  • name — takvimde görüntülenecek ad;
  • comment — katılımcı için bir yorum.

Örnek:

etkinlik = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Bot üzerinden rezerve edildi")

Bu katılımcı etkinliğe zaten eklenmişse, işlev bir hata döndürür:

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

Katılımcı Nasıl Kaldırılır

Aşağıdaki işlevi kullanın:

gcal_remove_client(calendar_id, event_id, client_email)

Parametreler:

  • calendar_id — takvim kimliği;
  • event_id — etkinlik kimliği;
  • client_email — kaldırılacak katılımcının e-posta adresi.

Örnek:

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

Belirtilen katılımcı etkinlikte yoksa, işlev şunu döndürür:

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

Olası Hatalar

Bir hata oluşursa, işlevler aşağıdaki biçimde bir nesne döndürür:

{
  "status": false,
  "err": "hata açıklaması"
}

Yaygın hatalar:

Yanıt Neden
Not Found Takvim hizmet hesabıyla paylaşılmamış veya yanlış bir calendar_id belirtilmiş
Google Calendar API has not been used in project ... or it is disabled Google Cloud projesinde Google Calendar API etkinleştirilmemiş
The key to access the calendar was not found in the passed link calendar_json_keys içindeki bağlantı anahtar dosyasını döndürmüyor
wrong datetime "...", expected format is dd.mm.yyyy HH:MM Tarih ve saat yanlış biçimde sağlanmış
wrong date "...", expected format is dd.mm.yyyy Tarih yanlış biçimde sağlanmış
Работает только на тарифах Бизнес и Инфобиз Projede bu özelliğe erişimi içeren aktif bir abonelik yok

Not Found Hatası

Google şunu döndürürse:

Not Found

şunları kontrol edin:

  1. calendar_id değerinin doğru olduğundan emin olun.
  2. Hizmet hesabının client_email değerinin takvim ayarlarına eklendiğinden emin olun.
  3. Hizmet hesabının Etkinliklerde değişiklik yap iznine sahip olduğundan emin olun.

Takvim mevcut olsa bile, hizmet hesabının erişimi yoksa Google Not Found döndürebilir.

Google Calendar API Etkin Değil

Hata yaklaşık olarak şöyle görünür:

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

Google Cloud'da projenizi açın ve şunu etkinleştirin:

APIs & Services → Library → Google Calendar API → Enable

API'yi etkinleştirdikten sonra isteği tekrarlayın.

Hizmet Hesabı Anahtarı Bulunamadı

Hata:

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

Şu değeri kontrol edin:

calendar_json_keys

Bir dosya bağlantısı kullanıyorsanız, hizmet hesabı anahtarını içeren JSON dosyasını doğrudan döndürmelidir.

Örnek:

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

Anahtarı doğrudan calendar_json_keys içinde bir JSON nesnesi olarak da sağlayabilirsiniz.

Yanlış Tarih ve Saat Biçimi

Hata:

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

Doğru biçim:

dd.mm.yyyy HH:MM

Örnek:

20.08.2026 14:00

Yanlış örnekler:

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

İşlev hem tarih hem de saat bekliyorsa, tarihi saat ve dakika ile birlikte sağlamalısınız.

Yanlış Tarih Biçimi

Hata:

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

Doğru biçim:

dd.mm.yyyy

Örnek:

20.08.2026

Uygun Abonelik Planı Yok

Hata:

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

Bu, projede Google Calendar işlevlerinin kullanımına izin veren aktif bir aboneliğin olmadığı anlamına gelir.

Hızlı Örnek

Bir etkinlik oluşturun ve kimliğini kaydedin:

etkinlik = gcal_add_event("[email protected]", "Danışma #{name}", "20.08.2026 14:00", "20.08.2026 15:00", "Müşteri telefonu: #{phone}", "Zoom", "Europe/Moscow")

etkinlik_id = get(etkinlik, 'id')

Müşteriyi oluşturulan etkinliğe ekleyin:

etkinlik = gcal_add_client("[email protected]", "#{event_id}", "#{email}", "#{name}", "Bot üzerinden rezerve edildi")

Müşteri yeniden planlamaya karar verirse:

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

Müşteri rezervasyonu iptal ederse:

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

Google API hataları err alanında değiştirilmeden döndürülür. Hata mesajı, neyin eksik olduğunu belirlemeye yardımcı olur: takvim erişimi, etkinleştirilmiş bir API, geçerli bir anahtar, doğru tarih biçimi veya mevcut bir etkinlik.