파이썬 카카오톡 API 연동: 6시간 토큰 만료 에러 완벽 해결법 (40대 실전)

지난 13편에서는 완성된 엑셀 보고서를 지메일(Gmail)로 자동 발송하는 시스템을 구축했습니다. 하지만 현장의 현실은 사무실 모니터 앞처럼 여유롭지 않습니다. 방역업을 직접 운영하며 뼈저리게 느낀 점이 하나 있습니다. 무거운 소독 장비를 메고 방진복을 입은 채 땀 흘리는 현장 팀장들에게 ‘이메일 확인’을 기대하는 것은 탁상공론에 불과하다는 것입니다.

긴급 방역 요청이나 동선 변경 지시가 담긴 엑셀 파일이 만들어졌다면, 즉각적으로 주머니 속 스마트폰을 울리게 만들어야 합니다. 대한민국 실무 환경에서 그 해답은 단 하나, ‘카카오톡(KakaoTalk)’ 뿐입니다.

오늘은 파이썬 업무 자동화의 진정한 꽃이라고 불리는 파이썬 카카오톡 API 연동 기술을 해부합니다. 단순한 메시지 전송 코드가 아닙니다. 인터넷에 떠도는 코드를 복사했다가 다음 날 아침 100% 마주하게 되는 치명적인 에러, ‘액세스 토큰 만료’ 문제를 OAuth 2.0 인증 로직의 관점에서 전문적으로 파헤치고 영구적인 무인 자동화로 뜯어고치는 진짜 실무 코딩을 시작하겠습니다.

1. 카카오 디벨로퍼스(Kakao Developers)와 REST API의 이해

파이썬이 내 카카오톡 계정을 제어하려면, 카카오 서버에 “내가 이 계정의 주인이고, 파이썬을 통해 메시지를 보낼 권한이 있다”는 것을 증명해야 합니다. 이를 위해 가장 먼저 ‘카카오 디벨로퍼스’에 접속하여 애플리케이션을 등록해야 합니다.

1. 애플리케이션 생성: 카카오 디벨로퍼스에 로그인 후 앱을 생성합니다.
2. REST API 키 발급: 앱 설정 요약 화면에서 제공하는 ‘REST API 키’를 메모장에 복사합니다. 이것은 카카오 서버의 문을 두드리는 1차 열쇠입니다.
3. 카카오 로그인 및 권한 동의: 왼쪽 메뉴의 [카카오 로그인]을 활성화하고, [동의 항목]에서 ‘카카오톡 메시지 전송’ 권한을 반드시 ‘선택 동의’ 이상으로 설정합니다.

여기까지는 검색 한 번이면 누구나 따라 할 수 있는 기초 세팅입니다. 진짜 문제는 지금부터 시작됩니다.

2. 실무 트러블슈팅: 6시간 시한부 ‘액세스 토큰(Access Token)’의 함정

REST API 키를 이용해 인증을 거치면, 카카오 서버는 우리에게 실제로 메시지를 보낼 수 있는 통행증인 액세스 토큰(Access Token)을 발급해 줍니다. 저 역시 처음 파이썬 카카오톡 연동에 성공했을 때, 이 토큰을 하드코딩(코드 안에 직접 입력)해두고 퇴근했습니다.

다음 날 아침, 윈도우 작업 스케줄러가 코드를 실행했지만 제 카카오톡은 조용했습니다. 로그를 확인해보니 아래와 같은 새빨간 에러가 출력되어 있었습니다.

{"msg":"this access token does not exist or expired","code":-401}

이유는 간단하면서도 치명적입니다. 보안을 위해 카카오의 액세스 토큰 수명은 단 6시간으로 제한되어 있기 때문입니다. 매일 자동으로 돌아가야 할 방역 대장 시스템이, 정작 6시간마다 사람이 수동으로 웹 브라우저를 띄워 새 토큰을 발급받아 코드에 붙여넣어야 한다면 그것은 자동화가 아니라 또 다른 스트레스일 뿐입니다.

3. 영구 동력의 핵심: 리프레시 토큰(Refresh Token) 자동 갱신 로직

이 6시간의 저주를 풀기 위해 카카오는 액세스 토큰과 함께 수명이 60일(두 달)에 달하는 리프레시 토큰(Refresh Token)을 발급해 줍니다. 진정한 실무용 파이썬 자동화 코드는 다음과 같은 논리(Logic)로 설계되어야 합니다.

1. 파이썬이 카카오톡 전송을 시작하기 전, 로컬에 저장된 json 파일에서 기존 토큰을 읽어 들입니다.
2. 이전 액세스 토큰이 만료되었다는 가정하에, 리프레시 토큰을 카카오 서버(OAuth 2.0 인증 서버)로 보냅니다.
3. “내 리프레시 토큰은 아직 유효하니, 새로운 6시간짜리 액세스 토큰을 내놔라!”라고 API 요청을 보냅니다.
4. 새로 발급받은 액세스 토큰으로 json 파일을 덮어쓰기(업데이트) 한 뒤, 그 토큰으로 안전하게 메시지를 발송합니다.

4. 실전 파이썬 코드: 토큰 갱신부터 카톡 발송까지 완벽 통합

아래는 위에서 설명한 ‘리프레시 토큰 자동 갱신’ 로직이 완벽하게 탑재된 실전 코드입니다. (실행 전 터미널에서 pip install requests 명령어로 라이브러리를 설치해야 합니다.)

Python

import requests
import json
import os

# 1. 카카오 디벨로퍼스에서 복사한 REST API 키
REST_API_KEY = "본인의_REST_API_키_입력"
TOKEN_FILE = "kakao_token.json"

# 2. 토큰 갱신 전용 함수 (핵심 로직)
def refresh_kakao_token():
    url = "https://kauth.kakao.com/oauth/token"
    
    # 사전에 최초 1회 발급받아 저장해둔 토큰 파일을 엽니다.
    if not os.path.isfile(TOKEN_FILE):
        print("토큰 파일이 존재하지 않습니다. 최초 발급을 먼저 진행하세요.")
        return None

    with open(TOKEN_FILE, "r") as fp:
        tokens = json.load(fp)
    
    data = {
        "grant_type": "refresh_token",
        "client_id": REST_API_KEY,
        "refresh_token": tokens["refresh_token"]
    }
    
    # 카카오 서버에 토큰 갱신 요청
    response = requests.post(url, data=data)
    result = response.json()
    
    # 갱신된 액세스 토큰을 기존 딕셔너리에 덮어쓰기
    if "access_token" in result:
        tokens["access_token"] = result["access_token"]
        # 리프레시 토큰 자체도 갱신될 수 있으므로 체크 후 덮어쓰기
        if "refresh_token" in result:
            tokens["refresh_token"] = result["refresh_token"]
            
        with open(TOKEN_FILE, "w") as fp:
            json.dump(tokens, fp)
        print("토큰 갱신 성공!")
        return tokens["access_token"]
    else:
        print("토큰 갱신 실패:", result)
        return None

# 3. 갱신된 토큰으로 방역 긴급 메시지 전송
new_token = refresh_kakao_token()

if new_token:
    header = {"Authorization": f"Bearer {new_token}"}
    url = "https://kapi.kakao.com/v2/api/talk/memo/default/send"

    post = {
        "object_type": "text",
        "text": "🚨 [긴급 알림] 금일 A구역 방역 현장 긴급 동선 변경 및 엑셀 취합이 완료되었습니다. 즉시 확인 바랍니다.",
        "link": {
            "web_url": "https://smartcodesblog.com",
            "mobile_web_url": "https://smartcodesblog.com"
        },
        "button_title": "방역 대장 확인하기"
    }

    data = {"template_object": json.dumps(post)}
    response = requests.post(url, headers=header, data=data)

    if response.status_code == 200:
        print("카카오톡 전송이 완벽하게 성공했습니다.")
    else:
        print("에러 발생:", response.text)

이 코드는 매번 실행될 때마다 스스로 카카오 서버와 통신하여 유효한 토큰을 얻어냅니다. 즉, 지난 12편에서 세팅한 ‘윈도우 작업 스케줄러’에 이 코드를 걸어두면 1년 365일 에러 없이 무인으로 돌아가는 궁극의 알림 시스템이 완성됩니다.

5. 글을 마치며: 기술을 넘어선 실무 적용력

파이썬의 문법을 아는 것과, 그것을 내 현장 업무에 적용하는 것은 완전히 다른 차원의 이야기입니다. 오늘 다룬 ‘토큰 만료 에러 우회’ 기술은 API 통신의 본질을 이해하지 못하면 절대 구현할 수 없는 실무자의 핵심 노하우입니다.

지금까지 14편에 걸쳐 엑셀 합치기부터 폴더 분류, 지메일, 그리고 대망의 카카오톡 연동까지 달려왔습니다. 우리의 퇴근 시간은 한층 빨라졌고, 업무의 정확도는 100%에 수렴하게 되었습니다. 아직 전체 파이썬 자동화 사이클을 연결하지 못하셨다면, 첫 단추인 엑셀 필터링부터 차분히 다시 복습해 보시길 권장합니다.

스마트워크는 어려운 것이 아닙니다. 40대 비전공자도 나의 업무 불편함을 코딩으로 하나씩 부숴나간다면, 그것이 곧 최고의 IT 기술입니다.