Google Calendar

08.05.2026

Осы бетте

Google Calendar калькулятор функциялары арқылы басқарылады: чат-бот Google API-мен сіздің сервистік аккаунтыңызды пайдаланып байланысады. Жеке HTTP сұрауларын конфигурациялаудың қажеті жоқ.

Талаптар

Google Calendar API қосылған Google Cloud жобасы.
Осы жобаға арналған сервистік аккаунт және оның 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()

Функцияларды қалай шақыру, күн форматтары және уақыт белдеулері

Функциялар, төменде көрсетілгендердің барлығы, чат-бот конструкторындағы калькуляторға енгізіледі.

Нәтижені тікелей айнымалыға сақтау ыңғайлы:

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_datetime және end_datetime орнына extra_params арқылы start_date және end_date беріңіз.

Дүйсенбі және сәрсенбі күндері 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 күнін алатын оқиға жасау үшін end_date ретінде 02.09.2026 көрсетіңіз.

Оқиға жасау кезіндегі жауап

Функция жасалған оқиғаны қайтарады:

{
  "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 Cloud жобасында Google Calendar API қосылмаған
`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

Талаптар

Сервистік аккаунтты құру және кілт алу

Кілтті қайда сақтау керек: calendar_json_keys айнымалысы

Сервистік аккаунтқа күнтізбеге қол жеткізуді қалай беруге болады

Күнтізбе идентификаторын қалай табуға болады

Функцияларды қалай шақыру, күн форматтары және уақыт белдеулері

Мәндер форматтары

Күнтізбелер

Күнтізбені қалай құруға болады

Күнтізбе туралы ақпаратты қалай алуға болады

Сервистік аккаунттың күнтізбелер тізімін қалай алуға болады

Күнтізбені қалай жоюға болады

Оқиғалар

Оқиғаны жылдам қосу

Оқиғаны қосу

Қосымша extra_params параметрлері

Күні бойғы оқиға

Оқиға жасау кезіндегі жауап

Оқиғаны қалай жаңартуға болады

Оқиғалар тізімін қалай алуға болады

Оқиға туралы ақпаратты қалай алуға болады

Оқиғаны басқа күнтізбеге қалай жылжытуға болады

Оқиғаны қалай жоюға болады

Оқиға қатысушылары

Қатысушыны қалай қосуға болады

Қатысушыны қалай жоюға болады

Ықтимал қателер

Not Found қатесі

Google Calendar API қосылмаған

Қызметтік тіркелгі кілті табылмады

Күн мен уақыттың қате форматы

Күннің қате форматы

Жарамды жазылым жоспары жоқ

Жылдам мысал

Кілтті қайда сақтау керек: `calendar_json_keys` айнымалысы

Қосымша `extra_params` параметрлері

`Not Found` қатесі