카카오톡 나에게 보내기 API로 자동화 알림 채널 만들기 — 토큰 만료 대비까지 2026

자동화는 다 만들어 놓고 마지막 한 칸에서 멈추는 경우가 많아요. 가격이 떨어졌는지, 페이지가 바뀌었는지 다 잡아 놓고도 정작 그 결과를 어디로 받을지가 애매하거든요. 이메일은 묻히고, 슬랙은 회사 계정이라 개인 알림에 쓰기 애매하고요.

결론부터 말하면 카카오톡 나에게 보내기 API가 이 자리에 잘 맞아요. 카카오 로그인으로 받은 액세스 토큰 하나로 POST https://kapi.kakao.com/v2/api/talk/memo/default/send 를 호출하면 내 카카오톡 나와의 채팅방에 메시지가 도착해요. 별도 앱을 깔 필요도 없고, 받는 사람도 나 하나라 남에게 폐를 끼칠 일도 없고요.

다만 이 채널은 붙이는 것보다 살려 두는 게 어려워요. 액세스 토큰과 리프레시 토큰에 각각 만료 시계가 걸려 있어서, 잘 돌던 알림이 두 달째 어느 날 조용히 멈추는 일이 실제로 생겨요. 그래서 이 글은 순서를 거꾸로 잡을게요. 만료 구조를 먼저 그려 놓고, 그 위에 연결을 얹는 순서로 갑니다.

카카오톡 나에게 보내기란 무엇이고, 자동화 알림 채널로 쓸 수 있나요

카카오톡 나에게 보내기는 카카오디벨로퍼스가 제공하는 카카오톡 메시지 API의 한 갈래예요. REST API 문서의 메시지 전송 대상 표에서 나에게 발송 항목은 "현재 로그인한 사용자의 카카오톡 나와의 채팅에 메시지를 발송합니다"라고 설명해요. 같은 칸에 "이 기능으로는 다른 사용자에게 메시지를 보낼 수 없고, 로그인한 사용자 본인에게만 메시지를 보낼 수 있습니다"라는 문장이 이어지고요.

이 두 문장이 이 API의 성격을 그대로 말해 줘요. 도착지는 내 나와의 채팅방 하나예요. 친구 목록도, 단톡방도, 고객도 대상이 아니에요. 자동화 알림 채널로 보면 오히려 이 제약이 장점이 돼요. 수신자가 나뿐이니 오발송 사고가 날 여지가 적고, 스팸 논란도 생기지 않아요.

제공되는 나에게 보내기 계열 API는 세 가지예요. 미리 정의된 기본 템플릿을 JSON으로 구성해 보내는 방식, 도구에서 미리 만들어 둔 사용자 정의 템플릿으로 보내는 방식, 웹 페이지 주소를 스크랩해 보내는 방식이에요. 자동화 알림에는 첫 번째가 가장 손이 덜 가요. 템플릿을 따로 만들어 등록하는 단계가 없거든요.

다만 사전 준비가 아예 없는 건 아니에요. 나에게 기본 템플릿으로 메시지 발송 API의 기본 정보 표는 사전 설정 칸에 제품 링크 관리, 카카오 로그인 활성화, 동의항목 세 가지를 적어 두었어요. 이 셋을 마쳐 두면 그다음부터는 요청 본문만 조립하면 되는 구조고요.

권한 이야기도 짚고 갈게요. 카카오톡 메시지 문서의 "사용 방법" 절 첫 문장은 "카카오톡 메시지 API로 친구에게 메시지 발송 기능을 서비스에 적용하려면 추가 기능을 신청해 사용 권한을 얻어야 합니다"예요. 이어지는 문장은 "사용 권한이 없는 앱과 그 앱의 테스트 앱에서는 앱의 멤버에게만 메시지를 보낼 수 있습니다"고요. 즉 비즈 앱 전환과 심사가 명시된 대상은 친구에게 보내기예요. 여기에 한 겹을 더 얹는 근거가 카카오 로그인 활용하기 문서에 있어요. 그 문서의 접근권한 동의항목 표는 카카오톡 메시지 전송(talk_message)의 동의 단계를 "[필수 동의]: 설정 불가", "[선택, 이용 중 동의]: 제한된 기능 제공, 사용 권한 신청"으로 적어 두었어요. 같은 문서의 참고 상자는 제한된 기능 제공을 "권한 획득 전, 아래 중 하나 이상의 기능 제한이 적용되는 동의항목"이라고 풀고, 그 제한으로 "앱의 멤버 대상으로만 기능 동작"과 "쿼터 제한"을 들어요.

정리하면 사용 권한을 신청하기 전에도 이 동의항목 자체는 쓸 수 있되, 기능이 제한된 상태로 쓰는 거예요. 나에게 보내기는 받는 사람이 앱을 만든 나 자신이라 앱 멤버 조건은 자연히 맞아떨어져요. 남는 건 쿼터 쪽인데, 이쪽은 카카오톡 메시지 문서의 이용 정책 절이 "카카오톡 메시지 API는 사용 권한 신청 전에는 쿼터 한도가 제한되며"라고 못 박아 두었어요. 그러니 "나에게 보내기는 아무 제한 없이 된다"고 미리 단정하지 말고, 앱을 만든 뒤 [내 애플리케이션]의 동의항목과 쿼터 화면에서 지금 내 앱이 무엇을 할 수 있는지를 직접 확인하는 편이 확실해요.

나에게 보내기·알림톡·텔레그램, 알림 채널은 무엇으로 고를까요

세 채널은 이름만 비슷하고 성격이 완전히 달라요. 카카오 문서의 메시지 발송 기능 안내 표가 이 차이를 분명히 갈라 두었어요. 알림톡은 "서비스가 정보성 메시지를 사용자에게 발송"하는 제품이고, 발송 주체는 서비스의 카카오톡 채널이며 제공 플랫폼은 카카오비즈니스예요. 반면 카카오톡 메시지는 발송 주체와 수신자가 모두 "서비스의 카카오 로그인 사용자"이고 카카오디벨로퍼스에서 제공해요.

같은 문서의 "카카오톡 공유와 카카오톡 메시지의 기능 차이" 절에는 "두 제품 모두 사용자간 메시지 전송만 지원하며, 서비스가 사용자에게 메시지를 발송할 수 없습니다"라는 문장이 있어요. 여기서 말하는 두 제품은 그 절의 제목 그대로 카카오톡 공유와 카카오톡 메시지예요. 알림톡은 애초에 서비스가 사용자에게 보내는 쪽이라 이 문장의 대상이 아니고요. 어느 쪽이든 결론은 같아요. 고객에게 주문 안내를 보내려고 나에게 보내기를 고르면 방향이 처음부터 어긋나요.

이 표에서 출처를 밝힌 칸은 카카오톡 나에게 보내기 열과, 카카오 공식 문서가 알림톡과 카카오톡 메시지를 갈라 놓은 위 네 줄이에요. 알림톡의 신청 절차나 요금, 텔레그램의 토큰 정책은 이 글에서 원문으로 확인하지 않았으니 각 제품의 공식 안내를 직접 보고 결정하시는 게 맞아요.

표만 보면 텔레그램이 편해 보이는데, 실제로는 갈리는 지점이 하나 있어요. 한국에서 하루 종일 켜 두는 메신저가 카카오톡이라는 점이요. 알림을 받는 앱이 평소에 안 켜는 앱이면 알림 자체가 무의미해지거든요. 그래서 텔레그램 봇을 이미 굴리고 있어도 개인 알림만 카카오톡으로 옮기는 사람이 꽤 있어요. 텔레그램 쪽 구성은 텔레그램 봇과 ChatGPT API 연동 5단계에 따로 정리해 두었으니 두 채널을 비교해 보고 고르셔도 좋아요.

카카오 개발자 앱 만들고 카카오톡 메시지 전송 동의항목 켜는 순서

여기부터는 실제 설정이에요. 순서를 지키는 게 중요해요. 뒤 단계에서 막히는 원인 대부분이 앞 단계의 누락이거든요.

첫째, 카카오디벨로퍼스에서 애플리케이션을 하나 추가해요. 앱을 만들면 플랫폼 키가 함께 생겨요. 이 중에서 우리가 쓸 건 REST API 키예요. 앱 관리 페이지의 앱 메뉴 아래 플랫폼 키에서 확인할 수 있어요.

둘째, 카카오 로그인을 활성화하고 리다이렉트 URI를 등록해요. 인가 코드를 돌려받을 주소라 반드시 필요해요. 서버가 없다면 로컬 주소를 넣어도 돼요. 어차피 주소로 붙은 코드 값만 눈으로 읽어 오면 되니까요.

셋째, 제품 링크 관리에서 웹 도메인을 등록해요. 앞에서 본 기본 정보 표가 사전 설정으로 지목한 항목이에요. 기본 템플릿 문서도 "기본 템플릿으로 발송한 메시지의 웹 링크와 앱 링크는 앱 관리 페이지의 [제품 링크 관리]에 등록된 아래 도메인과 스킴만 연결이 허용됩니다"라고 적고, 웹 링크는 "웹 도메인 중 하나 지정"으로 못 박아요. 뒤에 나올 텍스트 템플릿에서 link는 필수 항목이라 이 단계를 건너뛰면 본문이 맞아도 링크가 안 붙어요.

넷째, 동의항목을 켜요. 나에게 기본 템플릿으로 메시지 발송 API의 기본 정보 표에는 동의항목이 "필요: 카카오톡 메시지 전송(talk_message)" 하나만 적혀 있어요. 앱 관리 페이지의 카카오 로그인 메뉴에서 동의항목으로 들어가 접근권한 아래 카카오톡 메시지 전송을 찾아 설정하면 돼요. 이때 동의 단계를 필수 동의로 고르려다 막히는 사람이 있는데, 카카오 로그인 활용하기 문서의 접근권한 동의항목 표가 이 항목을 "[필수 동의]: 설정 불가"로 적어 두었기 때문이에요. 문서가 열어 둔 선택지는 선택 동의와 이용 중 동의예요.

여기서 헷갈리기 쉬운 지점이 하나 있어요. 카카오톡 메시지 "사용 방법" 절에는 동의항목을 두 가지 설정하라고 적혀 있는데, 그건 친구에게 보내기까지 붙일 때의 안내예요. 거기 나오는 친구목록 동의항목은 수신자 정보를 조회하기 위한 거라 나에게 보내기에는 쓰이지 않아요. 문서의 어느 절에 있는 문장인지를 같이 봐야 이 둘이 안 섞여요.

다섯째, 클라이언트 시크릿 상태를 확인해요. 카카오 로그인 REST API 문서에 "REST API 키(앱과 함께 자동 생성된 키 포함)는 클라이언트 시크릿 기능이 활성화된 상태로 추가됩니다"라는 안내가 있어요. 그다음 문장이 "따라서 토큰 발급 요청 시 client_secret 를 포함해야 합니다"고요. 예전 예제 코드를 그대로 복사했다가 실패하는 사례가 여기서 나와요. 시크릿 값을 미리 복사해 두세요.

액세스 토큰과 리프레시 토큰 발급 — 만료 시간부터 확인해요

토큰을 받기 전에 만료 구조를 먼저 보는 게 이 글의 핵심이에요. 카카오 로그인 문서의 토큰별 역할과 만료 시간 표를 그대로 옮기면 이래요.

액세스 토큰 값이 플랫폼마다 다르다는 점을 놓치지 마세요. 자동화 툴이나 서버에서 HTTP로 직접 부르는 방식은 REST API 줄에 해당하니 6시간이에요. 안드로이드 SDK를 쓰면 12시간이고요. "카카오 토큰은 6시간"이라고 조건을 떼어 외우면 SDK로 넘어갔을 때 계산이 어긋나요.

발급 절차는 두 단계예요. 먼저 브라우저에서 GET https://kauth.kakao.com/oauth/authorize 를 열어 인가 코드를 받아요. 쿼리 파라미터로 REST API 키를 담은 client_id, 등록한 redirect_uri, 그리고 code로 고정된 response_type이 필요해요. 동의항목을 추가로 요청할 때는 scope 파라미터에 동의항목 ID를 쉼표로 이어 붙여요.

그다음 받은 인가 코드로 POST https://kauth.kakao.com/oauth/token 을 호출해요. 본문에는 authorization_code로 고정된 grant_type, client_id, redirect_uri, code가 들어가고, 클라이언트 시크릿이 켜져 있으면 client_secret도 함께 넣어요. 응답에 access_token과 refresh_token이 같이 담겨 와요.

이 두 값을 어디에 둘지도 지금 정해 두세요. 액세스 토큰은 어차피 몇 시간 뒤 버릴 값이라 임시로 두어도 되지만, 리프레시 토큰은 이 채널의 수명 그 자체예요. 워크플로 안에 하드코딩해 두면 갱신할 때마다 사람이 파일을 열어야 하니, 처음부터 읽고 쓸 수 있는 자리에 두는 편이 나아요.

n8n·Make에서 HTTP 요청으로 카카오톡에 알림 보내기

메시지 전송은 생각보다 단순해요. n8n 공식 문서는 HTTP Request 노드를 REST API를 가진 모든 앱이나 서비스에 요청을 보낼 수 있는 노드로 소개해요. 카카오는 별도 전용 노드가 없으니 이 범용 노드로 부르면 돼요.

설정 값은 이렇게 잡아요. 메서드는 POST, URL은 https://kapi.kakao.com/v2/api/talk/memo/default/send 예요. 헤더는 두 개가 필요한데, 카카오 문서의 요청 헤더 표에 Authorization과 Content-Type이 모두 필수로 표기돼 있어요. Authorization에는 Bearer 뒤에 액세스 토큰을 붙이고, Content-Type은 application/x-www-form-urlencoded;charset=utf-8 이에요.

본문에는 template_object 하나만 넣어요. 문서의 요청 본문 표에서 이 항목은 Object 타입 필수이고, 피드·리스트·위치·커머스·텍스트·캘린더 중 하나를 담는다고 설명해요. 알림 용도라면 텍스트가 가장 간단해요.

{
  "object_type": "text",
  "text": "가격 알림: 관심 상품이 목표가 아래로 내려왔어요.",
  "link": {
    "web_url": "https://example.com/watchlist",
    "mobile_web_url": "https://example.com/watchlist"
  },
  "button_title": "확인하기"
}

기본 템플릿 문서의 텍스트 템플릿 표를 보면 object_type은 text로 고정이고, text는 최대 200자, link는 필수 항목이에요. 버튼 이름을 바꾸고 싶을 때만 button_title을 넣으면 되고요. 긴 요약을 통째로 밀어 넣기보다 200자 안에 결론만 담고 나머지는 링크로 넘기는 구성이 안전해요.

위 예제의 주소 자리는 그대로 쓰는 값이 아니에요. 앞 단계에서 제품 링크 관리에 등록해 둔 내 웹 도메인으로 바꿔야 해요. 등록하지 않은 도메인을 넣으면 문서가 적은 대로 연결이 허용되지 않아요.

n8n 쪽 설정에서 헷갈리는 자리는 본문 형식이에요. Send Body를 켜고 Body Content Type을 Form URLencoded로 고르세요. n8n 문서가 이 항목을 application/x-www-form-urlencoded 로 보내는 옵션으로 설명해요. JSON을 고르면 카카오가 요구하는 Content-Type과 어긋나요. 이름 칸에 template_object, 값 칸에 위 JSON 문자열을 넣는 구조예요.

성공 판정도 정해 두세요. 문서의 응답 본문 표에 result_code가 있고 설명이 "전송 성공 시 0"이에요. 워크플로에서 이 값을 검사하면 "요청은 200인데 메시지는 안 온" 상태를 걸러낼 수 있어요. 이렇게 조용히 실패하는 자동화를 잡아내는 방법은 자동화가 소리 없이 멈추는 자리 점검 체크리스트에 더 자세히 정리해 두었어요.

트리거를 어떻게 걸지는 이 글의 범위가 아니라 짧게만 짚을게요. 감시 대상이 가격이면 최저가 알림 자동화가, 웹페이지 변경이면 웹사이트 변경 감지 알림 자동화가 참고가 돼요. 주기를 얼마로 잡을지 고민된다면 웹훅과 폴링의 트리거 간격 비교도 함께 보세요.

AI 요약을 한 단계 끼워 읽히는 알림으로 바꾸기

원본 데이터를 그대로 밀어 넣은 알림은 며칠 지나면 안 읽게 돼요. 숫자와 로그가 뒤섞여 있으면 읽는 데 품이 들거든요. 텍스트 템플릿이 최대 200자라는 제약도 여기서 오히려 도움이 돼요. 200자에 맞추려면 결론부터 쓸 수밖에 없으니까요.

그래서 전송 앞에 요약 단계를 하나 끼우는 걸 권해요. 워크플로 순서는 감지 노드, 요약 노드, 전송 노드 셋이에요. 요약 노드에 넣을 지시문은 짧게 고정해 두세요. 예를 들면 "아래 내용을 한국어 두 문장으로 줄이되 첫 문장에 결론을 쓰고, 숫자는 원문 값을 그대로 유지해줘" 같은 식이에요.

숫자를 유지하라는 조건은 꼭 넣으세요. 요약 과정에서 금액이나 날짜가 반올림되거나 바뀌는 경우가 있어요. 알림은 판단의 근거로 쓰이니 숫자가 틀리면 알림 자체가 위험해져요. 대화 요약에서 같은 문제를 다룬 적이 있는데, 자세한 내용은 카카오톡 단톡방 대화 요약 자동화에 정리해 두었어요.

요약 결과가 200자를 넘길 가능성도 미리 막아 두세요. 요약 노드 뒤에 문자열을 자르는 단계를 하나 두거나, 지시문에 글자 수 상한을 못 박는 방법 둘 다 통해요. 기본 템플릿 문서는 text를 "텍스트 정보, 최대 200자"로 적고, 같은 문서의 예시 주석은 "최대 200자 표시 가능합니다"라고 써요. 상한을 넘겼을 때 뒤가 잘리는지 요청 자체가 거절되는지까지는 문서가 못 박아 두지 않았어요. 어느 쪽이든 내가 보낸 문장이 그대로 도착한다는 보장이 없으니, 넘기지 않도록 미리 자르는 쪽이 안전해요.

두 달 뒤 조용히 멈추는 자리 — 리프레시 토큰 자동 갱신 설계

여기가 이 글을 쓴 이유예요. 앞 단계까지만 해 두면 알림은 잘 와요. 그런데 6시간이 지나면 액세스 토큰이 만료되고, 그때부터는 갱신이 필요해요.

갱신 API는 POST https://kauth.kakao.com/oauth/token 이에요. 본문 필수 항목은 세 개예요. refresh_token으로 고정된 grant_type, REST API 키를 담은 client_id, 그리고 보관해 둔 refresh_token이에요. 클라이언트 시크릿이 ON 상태이면 client_secret도 필수로 포함해야 한다고 문서가 명시해요.

curl -v -X POST "https://kauth.kakao.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -d "grant_type=refresh_token" \
  -d "client_id=REST_API_KEY" \
  -d "refresh_token=USER_REFRESH_TOKEN" \
  -d "client_secret=CLIENT_SECRET"

이제 리프레시 토큰 쪽을 볼게요. 원문이 서로 다른 문서에 두 갈래로 적혀 있고, 이 둘을 붙여 읽으면 틀린 결론이 나와요.

첫째, 카카오 로그인 문서의 만료 시간 표는 리프레시 토큰을 "2달, 만료 시간 1달 남은 시점부터 갱신 가능"으로 적어요. 같은 칸에 "토큰 갱신 요청 시 새로운 리프레시 토큰을 발급하고 기존 리프레시 토큰은 폐기됨"이라는 안내가 별도로 붙어 있고요.

둘째, 갱신 API 문서의 참고 박스는 이렇게 적어요. "리프레시 토큰의 만료 시간이 1개월 미만인 경우에만 갱신된 refresh_token 과 refresh_token_expires_in 제공." 다음 줄은 "리프레시 토큰의 만료 시간이 1개월 이상 남은 경우 응답에 미포함"이고요. 응답 표에서도 refresh_token은 필수 항목이 아니에요.

두 갈래를 합쳐서 "부를 때마다 새 리프레시 토큰이 온다"고 읽으면 설계가 어긋나요. 실제 동작은 이래요. 남은 기간이 한 달 이상이면 응답에 refresh_token이 없고, 한 달 미만으로 내려가면 그때부터 응답에 들어와요.

그래서 워크플로가 해야 할 일은 딱 하나예요. 갱신 응답에 refresh_token이 들어 있을 때만 저장 값을 덮어쓰기. 값이 없다고 기존 것을 지우면 그 순간 채널이 죽어요. 반대로 새 값이 왔는데 안 받아 두면 기존 토큰은 폐기되므로 다음 갱신에서 막혀요. 두 달째에 조용히 멈추는 사고가 대부분 이 조건문을 안 넣어서 생겨요.

운영 형태는 두 가지 중에 고르면 돼요. 알림 워크플로 안에서 매번 갱신을 먼저 부르는 방식은 구조가 단순한 대신 호출이 늘어요. 하루 몇 번만 도는 갱신 전용 워크플로를 따로 두는 방식은 호출이 적은 대신 저장소가 필요해요. 갱신 API에는 요청 수 제한이 있고 초과 시 KOE237 에러가 난다고 문서에 적혀 있으니, 짧은 주기로 계속 부르는 구성은 피하는 게 좋아요.

이 판단의 근거는 쿼터 문서에 있어요. 일간 쿼터 표 아래에 "요청 수 제한"이라는 표가 따로 있고, 카카오 로그인의 토큰 요청 API와 토큰 갱신 API로 발급 가능한 토큰 수를 사용자 한 명 기준으로 액세스 토큰과 리프레시 토큰을 나눠 적어 두었어요. 표 아래에는 이 값이 추후 바뀔 수 있다는 주석도 붙어 있고요. 매번 갱신을 먼저 부르는 쪽을 고를 생각이라면, 트리거 주기를 정하기 전에 이 표를 먼저 열어 내 주기가 그 안에 들어오는지 확인하세요.

실패 처리도 같이 넣어 두세요. 갱신이 실패했는데 알림 워크플로만 계속 돌면 아무 일도 안 일어난 것처럼 보여요. 리프레시 토큰이 끝내 만료됐을 때 뜨는 코드도 미리 알아 두면 좋아요. 카카오 로그인 에러 코드 문서는 KOE322를 "refresh_token을 찾을 수 없거나 이미 만료된 리프레시 토큰을 사용한 경우"로 적고, 에러 메시지는 expired_or_invalid_refresh_token, 해결 방법은 "인가 코드를 사용하여 액세스 토큰과 리프레시 토큰을 새로 발급받습니다"로 적어요. 이 코드를 봤다면 갱신으로는 못 살리고 맨 처음의 인가 코드 단계로 돌아가야 한다는 뜻이에요. n8n에서 실패를 표면으로 끌어올리는 방법은 n8n 에러 처리 7가지 패턴에 정리해 두었으니 함께 붙여 두시면 좋아요.

내 카카오톡 알림 자동화가 살아 있는지 확인하는 자가진단 8문항

만들고 나서 한 달쯤 지났을 때 아래 여덟 개를 훑어보세요. 하나라도 아니오가 나오면 그 자리가 조용히 끊길 지점이에요.

• 1. 리프레시 토큰을 워크플로 밖의 읽고 쓸 수 있는 자리에 저장했나요? 노드 안에 붙여 넣기만 해 두었다면 갱신값을 받아도 저장할 곳이 없어요.
• 2. 갱신 응답에 refresh_token이 있을 때만 덮어쓰도록 조건을 걸었나요? 무조건 덮어쓰면 값이 없는 날 기존 토큰이 날아가요.
• 3. 액세스 토큰 만료를 6시간 기준으로 잡았나요? REST API로 부르면서 12시간으로 잡아 두면 중간이 비어요.
• 4. 전송 응답의 result_code가 0인지 검사하나요? 상태 코드만 보면 메시지가 안 간 경우를 못 잡아요.
• 5. 요약 결과가 200자를 넘지 않도록 자르거나 지시문에 상한을 넣었나요? 문서가 적은 상한을 넘겼을 때 어떻게 되는지는 문서에 나와 있지 않아요.
• 6. 갱신 실패를 알려 줄 별도 경로가 있나요? 카카오톡 하나에만 의존하면 카카오톡이 막혔을 때 알 방법이 없어요.
• 7. 클라이언트 시크릿 값을 요청에 포함하고 있나요? REST API 키는 시크릿이 켜진 상태로 추가된다고 문서에 적혀 있어요.
• 8. 최근 일주일 안에 알림이 실제로 도착한 기록이 있나요? 워크플로가 초록불이어도 메시지가 안 왔다면 그게 답이에요.

여덟 개 중 여섯 개 이상 예가 나오면 안정적인 편이에요. 특히 2번과 8번은 다른 항목이 다 통과해도 혼자 사고를 내는 자리라 우선순위를 높게 두세요.

흔한 실수와 문서에 적힌 제한 사항

첫째, 목적을 잘못 고르는 실수예요. 카카오 FAQ의 심사 반려 사유 표에 "기능 혼동"이라는 항목이 있고, 그 설명이 "카카오톡 메시지 API와 알림톡의 목적을 혼동한 경우"예요. 주문이나 배송처럼 서비스가 고객에게 보내는 메시지라면 카카오비즈니스의 알림톡을 쓰라는 안내가 함께 붙어 있고요. 나에게 보내기는 그 용도가 아니에요.

둘째, 쿼터를 안 보고 주기를 짧게 잡는 실수예요. 카카오디벨로퍼스 쿼터 문서의 일간 쿼터 표에는 "카카오톡 메시지 전송" 항목이 30,000건으로 적혀 있고, 그 아래에 발신자당 100건, 수신자당 100건, 발신자와 수신자 한 쌍당 20건이 함께 적혀 있어요. 다만 이 표는 카카오톡 메시지 전송이라는 항목 하나로 묶여 있고 나에게 보내기만 따로 떼어 수치를 적어 두지는 않았어요. 그래서 실제 소모량은 앱 관리 페이지의 쿼터 화면에서 확인하는 게 정확해요. 어느 쪽이든 1분 간격으로 계속 쏘는 설계는 피하는 편이 안전해요.

셋째, 실패 코드를 안 읽는 실수예요. 카카오톡 메시지 에러 코드 문서에 쿼터 관련 코드가 세 개 있어요. -532는 보내는 이가 하루 한도를 넘긴 경우, -533은 받는 이가 하루 한도를 넘긴 경우, -536은 보내는 이와 받는 이 한 쌍 기준 하루 한도를 넘긴 경우예요. 이 코드가 뜨면 워크플로를 고칠 게 아니라 주기를 줄여야 해요.

이 글이 다루는 두 축, 그러니까 동의항목과 리프레시 토큰에서 뜨는 코드는 따로 있어요. 동의를 받지 않은 상태로 부르면 -402가 나요. 카카오 로그인 에러 코드 문서는 이 코드를 "해당 API에서 접근하는 리소스에 대해 사용자의 동의를 받지 않은 경우"로 적고, 활용하기 문서는 응답 예시로 msg가 insufficient scopes, api_type이 TALK_MEMO_DEFAULT_SEND, required_scopes가 talk_message인 본문을 그대로 실어 두었어요. 나에게 보내기를 부르는 상황 그대로라 알아보기 쉬워요. 리프레시 토큰 쪽은 KOE322고, 에러 메시지가 expired_or_invalid_refresh_token이에요. 앞 절에서 본 대로 이때는 인가 코드부터 다시 받아야 해요.

넷째, 쿼터 한도를 올리면 된다고 생각하는 실수예요. 카카오톡 메시지 이용 정책에는 "카카오톡 메시지 API는 사용 권한 신청 전에는 쿼터 한도가 제한되며, 빈번한 메시지로부터 사용자를 보호하기 위해 쿼터 한도 상향이 불가능합니다"라고 적혀 있어요. 한도를 늘리는 방향이 아니라 보낼 것을 줄이는 방향으로 설계해야 해요.

다섯째, 링크와 이미지 도메인을 등록하지 않는 실수예요. 앞의 설정 순서에서 셋째로 둔 단계인데, 메시지가 안 오는 게 아니라 링크만 안 붙는 증상이라 원인을 늦게 찾아요. 기본 템플릿 문서는 웹 링크가 앱 관리 페이지의 제품 링크 관리에 등록된 웹 도메인 중 하나만 연결이 허용된다고 적어요. 이미지 쪽에는 별도 안내가 있는데, 서비스 서버 방화벽이 카카오 스크랩 서버 접근을 막으면 이미지가 아주 느리게 전송되거나 아예 표시되지 않을 수 있다고 해요.

오늘 바로 해 볼 한 가지

전부 한 번에 붙이려 하지 말고, 오늘은 토큰까지만 받아 보세요. 카카오디벨로퍼스에서 앱을 만들고, 카카오톡 메시지 전송 동의항목을 켜고, 인가 코드로 액세스 토큰과 리프레시 토큰을 한 번 받아 보는 데까지요. 여기까지 되면 나머지는 제품 링크 관리에 웹 도메인을 등록하고 HTTP 요청 노드를 붙이는 일이라 금방 끝나요.

그리고 리프레시 토큰을 받은 날짜를 어딘가에 적어 두세요. 두 달이라는 수명이 실제로 어디쯤 와 있는지 눈으로 보는 것만으로도 조용히 멈추는 사고를 크게 줄일 수 있어요. 알림이 끊기는 사고를 미리 잡아내는 점검 항목은 자동화가 소리 없이 멈추는 자리 점검 체크리스트에 이어서 정리해 두었어요.

이 글의 수치와 인용은 2026년 8월 초에 카카오디벨로퍼스 공식 문서에서 직접 확인한 내용이에요. 만료 시간이나 쿼터 값은 정책에 따라 바뀔 수 있으니, 실제로 붙이기 전에 해당 문서를 한 번 더 열어 보시는 걸 권해요.