텔레그램 봇으로 Google Calendar 일정 등록하기

2026. 7. 25. 15:23ㆍ파이썬

목차

  1. 프로젝트 목표
  2. 사용 기술
  3. 텔레그램 봇 생성
  4. 프로젝트 폴더 만들기
  5. 파이썬 가상환경 만들기
  6. 파이썬 라이브러리 설치
  7. .env 파일로 텔레그램 토큰 관리
  8. 첫 번째 텔레그램 에코 봇
  9. Google Cloud 프로젝트 생성
  10. OAuth란?
  11. OAuth 동의 화면 설정
  12. 테스트 사용자 등록
  13. OAuth 클라이언트 만들기
  14. credentials.json과 token.json 차이
  15. Google에서 확인하지 않은 앱 경고
  16. 자연어 일정 분석
  17. Google Calendar 일정 등록
  18. 실행 및 테스트
  19. 일반 인사말 처리
  20. 자주 발생하는 오류
  21. 보안 주의사항
  22. 교육용 실습 문제

핵심 포인트: 이 자료는 단순한 "작업 진행 내역"이 아니라, 왜 이 작업을 하는지 · 각 파일/기술의 역할 · 명령어의 의미 · 코드 동작 흐름 · 실행 결과 · 오류 해결 · 보안 주의사항 · 실습 문제까지 포함하는 완전한 교육자료 형태로 구성했습니다.

1. 프로젝트 목표

사용자가 텔레그램 앱에서 자연어로 일정을 입력하면, 파이썬 프로그램이 문장을 분석해 Google Calendar에 자동으로 일정을 등록합니다.

입력 예시

내일 오후 3시 프로젝트 회의

추출 정보

날짜: 내일
시간: 오후 3시
제목: 프로젝트 회의

Google Calendar 등록 결과

제목: 프로젝트 회의
시작: 내일 오후 3시
종료: 내일 오후 4시

전체 처리 흐름

텔레그램 모바일 앱
        ↓
텔레그램 봇
        ↓
파이썬 bot.py
        ↓
날짜·시간·제목 분석
        ↓
Google Calendar API
        ↓
Google Calendar 일정 등록

2. 사용 기술

기술 역할

텔레그램 사용자 입력을 받는 채팅 인터페이스
텔레그램 봇 사용자 ↔ 파이썬 프로그램 사이의 통신 창구 (분석/등록은 하지 않음)
Python 메시지 처리 + Calendar API 호출을 담당하는 핵심 로직
Google Calendar API 프로그램이 실제 캘린더에 일정을 등록하기 위한 인터페이스

봇의 역할 요약

텔레그램 봇 = 사용자와 파이썬 프로그램을 연결하는 통신 창구

API 요청 예시

2026년 7월 26일 오후 3시에 '프로젝트 회의' 일정을 등록해 주세요.

3. 텔레그램 봇 생성

BotFather는 텔레그램이 제공하는 공식 봇 관리 도구로, 봇 생성/이름 설정/토큰 발급/명령어 설정/삭제 및 재발급을 할 수 있습니다.

절차

  1. 텔레그램에서 @BotFather 검색
  2. /newbot 입력
  3. 봇 이름 입력 (예: 일정관리 도우미)
  4. 봇 사용자명 입력 — 반드시 bot으로 끝나야 함 (예: my_schedule_bot)
  5. 토큰 발급 확인 (예: 1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxx)

⚠️ 이 토큰은 봇을 제어하는 비밀번호와 같으므로 외부에 노출되면 안 됩니다.

4. 프로젝트 폴더 만들기

C:\python\telegram_bot

VS Code: File → Open Folder → C:\python\telegram_bot

최종 폴더 구조 및 역할

telegram_bot
 ├─ .venv            # 프로젝트 전용 파이썬 실행환경
 ├─ .env             # 텔레그램 봇 토큰 등 환경설정
 ├─ .gitignore       # GitHub 미업로드 대상 지정
 ├─ bot.py           # 메시지 처리 및 일정 등록 프로그램
 ├─ credentials.json # Google OAuth 클라이언트 정보
 ├─ token.json       # 사용자 Google 로그인 승인 결과
 └─ requirements.txt # 사용 라이브러리 목록

5. 파이썬 가상환경 만들기

가상환경이란? 프로젝트별로 라이브러리 버전을 독립적으로 관리하는 공간입니다.

프로젝트 A → python-telegram-bot 22 버전
프로젝트 B → python-telegram-bot 20 버전

가상환경이 없으면 한 프로젝트의 라이브러리 업데이트가 다른 프로젝트를 깨뜨릴 수 있습니다.

생성 및 활성화

py -m venv .venv
.venv\Scripts\Activate.ps1

명령 요소 의미

py Windows의 Python 실행 명령
-m Python 모듈 실행 옵션
venv 가상환경 생성 모듈
.venv 생성될 폴더 이름

정상 활성화 시 터미널 표시:

(.venv) PS C:\python\telegram_bot>

6. 파이썬 라이브러리 설치

pip install python-telegram-bot python-dotenv google-api-python-client google-auth-httplib2 google-auth-oauthlib

라이브러리 역할

python-telegram-bot 텔레그램 메시지 수신/응답
python-dotenv .env 파일 읽기
google-api-python-client Google Calendar API 호출
google-auth-httplib2 Google 인증 통신 처리
google-auth-oauthlib Google OAuth 로그인 처리

관리 명령

pip list                          # 설치된 라이브러리 확인
pip freeze > requirements.txt     # 목록 저장
pip install -r requirements.txt   # 다른 PC에 동일 환경 설치

7. .env 파일로 텔레그램 토큰 관리

토큰을 bot.py에 직접 작성하면(예: TOKEN = "1234...") 코드 공유 시 토큰이 함께 노출되어 위험합니다.

.env 파일

TELEGRAM_BOT_TOKEN=실제_텔레그램_토큰

bot.py에서 읽기

import os
from dotenv import load_dotenv

load_dotenv()
TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")

처리 흐름

.env 파일 → load_dotenv() → 프로그램 환경변수 등록 → os.getenv() → bot.py에서 사용

.env는 Windows 시스템 환경변수 자체가 아니며, python-dotenv가 실행 시점에 파일 내용을 읽어 프로그램 내부 환경변수처럼 사용하게 해주는 방식입니다.

8. 첫 번째 텔레그램 에코 봇

Google Calendar 연동 전, 텔레그램 통신 자체가 되는지 먼저 확인합니다.

import os

from dotenv import load_dotenv
from telegram import Update
from telegram.ext import (
    ApplicationBuilder,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)

load_dotenv()

TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if update.message is None:
        return
    await update.message.reply_text("안녕하세요. 텔레그램 봇입니다.")


async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if update.message is None or update.message.text is None:
        return
    user_message = update.message.text
    await update.message.reply_text(f"받은 메시지: {user_message}")


def main() -> None:
    if not TOKEN:
        raise RuntimeError("TELEGRAM_BOT_TOKEN을 찾을 수 없습니다.")

    application = ApplicationBuilder().token(TOKEN).build()
    application.add_handler(CommandHandler("start", start))
    application.add_handler(
        MessageHandler(filters.TEXT & ~filters.COMMAND, echo)
    )

    print("텔레그램 봇이 실행되었습니다.")
    application.run_polling()


if __name__ == "__main__":
    main()

주요 코드 설명

코드 의미

load_dotenv() .env 설정값 읽기
os.getenv("TELEGRAM_BOT_TOKEN") 환경변수에서 토큰 가져오기
ApplicationBuilder().token(TOKEN).build() 봇 인스턴스 생성
CommandHandler("start", start) /start 입력 시 start() 실행
MessageHandler(filters.TEXT & ~filters.COMMAND, echo) 일반 텍스트 수신 시 echo() 실행
application.run_polling() 새 메시지를 지속적으로 확인

9. Google Cloud 프로젝트 생성

Google Calendar를 외부 프로그램에서 쓰려면 Google Cloud 프로젝트가 필요합니다. 프로젝트는 API·인증정보·권한·사용량을 하나의 단위로 관리합니다.

Google Cloud 프로젝트
 ├─ Google Calendar API
 ├─ OAuth 동의 화면
 ├─ OAuth 클라이언트
 ├─ API 사용량
 └─ 보안 설정

절차

  1. 새 프로젝트 생성 (예: Telegram Calendar Bot)
  2. API 및 서비스 → 라이브러리 → Google Calendar API → 사용

10. OAuth란?

OAuth는 Google 비밀번호를 프로그램에 직접 넘기지 않고, 필요한 권한만 승인받는 인증 방식입니다.

인증 흐름

Python 프로그램
    ↓
Google 로그인 화면
    ↓
사용자가 계정 선택
    ↓
캘린더 관리 권한 승인
    ↓
token.json 발급

프로그램은 비밀번호를 알 수 없고, Google이 발급한 토큰만 사용합니다.

11. OAuth 동의 화면 설정

앱 이름: Telegram Calendar Bot
사용자 지원 이메일: 본인 Gmail
대상: 외부
연락처 이메일: 본인 Gmail

구분 설명

내부 특정 Workspace 조직 사용자만 가능 (개인 Gmail 불가한 경우 많음)
외부 개인 Gmail 포함 가능. 테스트 상태에서는 등록된 테스트 사용자만 사용

→ 개인 Gmail로 테스트한다면 외부를 선택합니다.

12. 테스트 사용자 등록

외부·테스트 상태에서는 등록된 사용자만 로그인 가능합니다.

경로: Google Auth Platform → 대상 → 테스트 사용자 → 사용자 추가

등록하지 않으면 발생하는 오류:

403 오류: access_denied

→ 해당 계정이 앱 사용 권한이 없다는 뜻입니다.

13. OAuth 클라이언트 만들기

경로: Google Auth Platform → 클라이언트 → 클라이언트 만들기

애플리케이션 유형: 데스크톱 앱
이름: Telegram Calendar Bot Windows

생성 후 다운로드된 JSON 파일(client_secret_....json)을 **credentials.json**으로 이름을 바꿔 bot.py와 같은 폴더에 저장합니다.

14. credentials.json과 token.json 차이

파일 의미 발급 시점

credentials.json 프로그램의 신분증 (앱 인증정보) Google Cloud에서 다운로드
token.json 사용자의 로그인·권한 승인 결과 최초 로그인 성공 후 자동 생성

두 파일 모두 절대 외부에 공개하면 안 됩니다.

15. Google에서 확인하지 않은 앱 경고

최초 로그인 시 다음 경고가 나타날 수 있습니다.

Google에서 확인하지 않은 앱

아래 조건을 모두 만족하면 안전하게 진행 가능합니다.

  • 내가 직접 만든 Google Cloud 프로젝트
  • 내가 다운로드한 credentials.json 사용
  • 로그인 계정이 테스트 사용자로 등록됨

진행 경로: 계속 → Google Calendar 권한 확인 → 허용 → 인증 성공 시 token.json 생성

16. 자연어 일정 분석

입력 예:

내일 오후 3시 프로젝트 회의

분리 결과

날짜 표현: 내일
시간 표현: 오후 3시
일정 제목: 프로젝트 회의

날짜/시간 변환

target_date = today + timedelta(days=1)

오후 3시 → 24시간 형식 15시

결과

시작: 2026-07-26 15:00
종료: 2026-07-26 16:00   (기본 1시간 뒤로 설정 가능)

17. Google Calendar 일정 등록

이벤트 데이터 구조

event = {
    "summary": title,
    "start": {
        "dateTime": start.isoformat(),
        "timeZone": "Asia/Seoul",
    },
    "end": {
        "dateTime": end.isoformat(),
        "timeZone": "Asia/Seoul",
    },
}

필드 의미

summary 일정 제목
start.dateTime 시작 날짜/시간
end.dateTime 종료 날짜/시간
timeZone 시간대

API 호출

service.events().insert(
    calendarId="primary",
    body=event,
).execute()

primary는 현재 로그인된 계정의 기본 캘린더를 의미합니다.

18. 실행 및 테스트

.venv\Scripts\Activate.ps1
python bot.py

텔레그램 입력:

내일 오후 3시 프로젝트 회의

정상 응답 예:

✅ Google 캘린더에 등록했습니다.
제목: 프로젝트 회의
시간: 2026-07-26 15:00 ~ 16:00

Google Calendar에서 실제 등록 여부를 확인합니다.

19. 일반 인사말 처리

날짜/시간이 없는 문장(예: 안녕하세요)은 일정으로 분석할 수 없으므로 별도 처리가 필요합니다.

greetings = {
    "안녕하세요", "안녕", "반갑습니다", "하이", "hello", "hi",
}

if text.lower() in greetings:
    await update.message.reply_text(
        "안녕하세요. 일정관리 봇입니다.\n"
        "예: 내일 오후 3시 프로젝트 회의"
    )
    return

return 이후에는 일정 분석 코드가 실행되지 않습니다.

20. 자주 발생하는 오류

오류 확인 사항

TELEGRAM_BOT_TOKEN을 찾을 수 없습니다 .env 파일명·위치 확인 / python-dotenv 설치 여부 / 변수명 오타
텔레그램 봇 무응답 bot.py 실행 중인지 / 토큰 정확한지 / 다른 PC에서 중복 실행 중인지 / /start 먼저 눌렀는지
Google 403 access_denied 로그인 계정이 테스트 사용자로 등록됐는지 → Google Auth Platform → 대상 → 테스트 사용자에 추가
credentials.json을 찾을 수 없음 파일 위치가 bot.py와 다름 / 파일명 오류
Google 로그인 반복 token.json 정상 생성 여부 / 삭제 여부 / OAuth 권한 범위 변경 여부

21. 보안 주의사항

다음 파일은 절대 외부 공유·GitHub 업로드 금지:

.env
credentials.json
token.json

.gitignore 예시

.env
.venv/
credentials.json
token.json
__pycache__/

토큰 노출이 의심되면 BotFather에서 기존 토큰을 폐기하고 재발급받아야 합니다.

22. 교육용 실습 문제

  1. 날짜 표현 확장: 모레 오전 10시 병원 같은 입력도 처리되도록 수정
  2. 기본 일정 시간 변경: end = start + timedelta(hours=2) 로 2시간 기본값 적용
  3. 요일 기반 날짜 분석 추가: 다음 주 월요일 오후 2시 주간회의 처리
  4. 등록 전 확인 절차 추가: 
    다음 일정으로 등록할까요?제목: 회의시간: 내일 오후 3시~4시[등록] [취소]
  5. 일정 취소 명령 추가: /undo 로 최근 등록 일정 삭제

정리

이 자료의 핵심은 설치 절차만 나열하는 것이 아니라, 각 기술·파일의 역할, 코드 흐름, 인증 구조(OAuth), 오류 해결법, 보안 주의사항, 실습 과제까지 포함해 학습자가 스스로 이해하고 확장할 수 있도록 구성한 것입니다.

텔레그램봇_구글캘린더_교육자료.md.pdf
0.59MB

'파이썬' 카테고리의 다른 글

텔레그램 봇으로 Google Calendar 일정 관리하기  (0) 2026.07.25
파이썬으로 텔레그램 Echo Bot 만들기  (0) 2026.07.25
🎯 파이썬으로 숫자 맞히기 게임 만들기  (1) 2026.07.19
Python 문자열 슬라이싱과 % 포맷 결합 문제 풀이(Claude)  (0) 2026.07.11
문자열 조각을 이어 문장 완성하기(Chatgpt)  (0) 2026.07.11

관련글

티스토리툴바