초보자도 10분 만에 끝내는 카카오톡 API 연동, 가장 쉬운 방법 총정리!
목차
- 카카오톡 API가 뭐길래? 왜 필요할까?
- 딱 3단계! 카카오톡 API 연동 준비하기
- 핵심! 10분 만에 따라하는 카카오톡 메시지 보내기
- 자주 묻는 질문(FAQ) 및 문제 해결 팁
1. 카카오톡 API가 뭐길래? 왜 필요할까?
개발을 하다 보면 사용자에게 중요한 알림이나 정보를 실시간으로 보내야 할 때가 많습니다. 회원가입을 축하하는 메시지, 주문 완료 알림, 이벤트 소식, 긴급 공지 등 그 종류는 무궁무진하죠. 이때 가장 효과적인 채널 중 하나가 바로 카카오톡입니다. 대한민국 국민 대다수가 사용하는 메신저이기 때문이죠. 하지만 일일이 손으로 메시지를 보내는 건 불가능합니다. 그래서 우리는 카카오톡 API(Application Programming Interface)를 사용합니다.
API는 프로그램과 프로그램이 서로 소통할 수 있게 해주는 다리 역할을 합니다. 쉽게 말해, 우리가 만든 프로그램이 카카오톡이라는 거대한 서비스에 “나 대신 이 사람에게 이런 메시지를 보내줘!”라고 요청할 수 있도록 길을 열어주는 거죠. 카카오톡 API를 사용하면 우리 서비스에서 일어나는 특정 이벤트에 맞춰 자동으로 메시지를 보낼 수 있게 됩니다. 이를 통해 사용자의 편의성을 높이고, 서비스에 대한 참여율을 끌어올릴 수 있습니다.
예를 들어, 쇼핑몰 앱을 만들었다고 가정해 봅시다. 고객이 상품을 주문하면, 주문 내역을 자동으로 카카오톡으로 보내주는 기능을 만들 수 있습니다. 챗봇과 연동하여 자주 묻는 질문에 자동으로 답변하게 할 수도 있고요. 이 모든 것이 바로 카카오톡 API를 통해 가능합니다. 복잡하게 생각할 필요 없습니다. 마치 레고 블록을 조립하듯, 카카오에서 제공하는 기능들을 하나씩 가져와서 우리 서비스에 딱 맞게 끼워 넣는 과정이라고 생각하면 아주 쉽습니다.
2. 딱 3단계! 카카오톡 API 연동 준비하기
카카오톡 API를 사용하기 위해선 몇 가지 준비 과정이 필요합니다. 걱정 마세요, 생각보다 훨씬 간단합니다. 단 3단계만 거치면 됩니다.
1단계: 카카오 개발자 계정 생성 및 애플리케이션 등록
가장 먼저 카카오 개발자 사이트에 접속하여 회원가입을 해야 합니다. 이미 카카오 계정이 있다면 추가적인 가입 절차 없이 바로 로그인할 수 있습니다. 로그인 후, 메인 화면에서 “내 애플리케이션”으로 이동해 새로운 애플리케이션을 생성합니다. 애플리케이션의 이름과 회사명을 입력하면 아주 쉽게 등록이 완료됩니다. 이때 입력하는 애플리케이션 이름은 사용자에게 노출되므로, 서비스의 성격에 맞는 이름을 정하는 것이 좋습니다.
2단계: 애플리케이션 설정 및 API 키 확인
애플리케이션을 등록했다면, 이제 몇 가지 설정을 해줘야 합니다. 생성된 애플리케이션을 클릭하면 “요약 정보” 페이지가 나타납니다. 여기서 가장 중요한 것이 바로 “앱 키”입니다. REST API 키, JavaScript 키, Admin 키 등 여러 종류의 키가 있는데, 우리는 주로 REST API 키를 사용하게 됩니다. 이 키는 우리 애플리케이션을 식별하는 고유한 ID 역할을 합니다. 이 키를 통해 우리 애플리케이션이 카카오 API를 사용할 자격이 있음을 증명하게 됩니다. 마치 은행에 갈 때 신분증을 제시하는 것과 같습니다. 이 키는 외부에 노출되지 않도록 잘 관리해야 합니다.
3단계: 카카오 로그인 활성화 및 Redirect URI 등록
카카오톡 메시지를 보내기 위해서는 사용자의 동의를 얻는 과정이 필요합니다. 이를 위해 카카오 로그인 기능을 활성화해야 합니다. 애플리케이션 설정의 “카카오 로그인” 메뉴로 이동하여 “활성화 설정”을 ‘ON’으로 변경합니다. 그리고 Redirect URI를 등록해야 합니다. Redirect URI는 사용자가 카카오 로그인을 마친 후 우리 서비스로 다시 돌아올 주소를 지정하는 것입니다. 예를 들어, http://localhost:3000/callback과 같이 개발 환경에 맞는 주소를 등록해줍니다. 이 주소는 여러 개 등록할 수 있으며, 개발 단계에서는 로컬 주소를, 실제 서비스에서는 도메인 주소를 추가로 등록하면 됩니다.
3. 핵심! 10분 만에 따라하는 카카오톡 메시지 보내기
이제 모든 준비가 끝났습니다. 본격적으로 카카오톡 메시지를 보내는 코드를 작성해 보겠습니다. 이 과정은 크게 토큰 발급과 메시지 전송 두 단계로 나뉩니다.
1단계: 인증 코드 발급
가장 먼저 사용자의 동의를 받기 위해 아래와 같은 형식의 URL로 사용자를 이동시켜야 합니다.
https://kauth.kakao.com/oauth/authorize?client_id={REST_API_KEY}&redirect_uri={REDIRECT_URI}&response_type=code
위 URL의 {REST_API_KEY}와 {REDIRECT_URI} 부분에 앞서 확인했던 키와 주소를 입력합니다. 사용자가 이 URL에 접속하면 카카오 로그인 페이지가 나타나고, “카카오톡으로 로그인”을 누르면 우리 서비스에 대한 동의 페이지가 뜹니다. 사용자가 동의를 완료하면, 지정된 {REDIRECT_URI}로 인증 코드(code)가 포함된 URL과 함께 리다이렉트됩니다. 이 코드는 일회용이며, 매우 중요한 정보이므로 URL에서 잘 추출해야 합니다.
2단계: 토큰 발급 (Access Token & Refresh Token)
받은 인증 코드를 가지고 이제 토큰을 발급받아야 합니다. 토큰은 앞으로 카카오 API를 호출할 때마다 우리 애플리케이션이 유효한 접근 권한을 가졌음을 증명하는 열쇠 역할을 합니다. 아래와 같은 형식으로 POST 요청을 보냅니다.
https://kauth.kakao.com/oauth/token
요청 헤더: Content-type: application/x-www-form-urlencoded;charset=utf-8
요청 바디:
grant_type:authorization_codeclient_id:{REST_API_KEY}redirect_uri:{REDIRECT_URI}code:{인증 코드}
이 요청이 성공하면 JSON 형식의 응답으로 access_token과 refresh_token을 받게 됩니다. access_token은 실제 API를 호출할 때 사용하는 토큰이며, refresh_token은 access_token이 만료되었을 때 새로운 access_token을 발급받기 위해 사용됩니다. access_token은 보통 몇 시간 후에 만료되므로, refresh_token을 잘 저장해두고 필요할 때마다 재발급 받는 로직을 구현해야 합니다.
3단계: 나에게 메시지 보내기
이제 발급받은 access_token을 사용하여 메시지를 보내봅시다. 카카오에서는 다양한 메시지 템플릿을 제공하지만, 가장 간단한 “나에게 메시지 보내기” 기능을 사용해 보겠습니다. 이 기능은 개발자가 테스트 목적으로 자신의 카카오톡으로 메시지를 보낼 때 유용합니다.
https://kapi.kakao.com/v2/api/talk/memo/default/send
요청 헤더:
Authorization:Bearer {ACCESS_TOKEN}Content-type:application/x-www-form-urlencoded;charset=utf-8
요청 바디:
template_object: JSON 형식의 메시지 내용
template_object는 메시지의 제목, 내용, 링크 등을 담는 중요한 부분입니다. 아래는 간단한 텍스트 메시지를 보내는 예시입니다.
{
"object_type": "text",
"text": "안녕하세요! 카카오톡 API 연동 테스트 메시지입니다.",
"link": {
"web_url": "https://developers.kakao.com"
},
"button_title": "자세히 보기"
}
위 예시처럼 object_type을 text로 지정하고, text 부분에 원하는 메시지 내용을 담으면 됩니다. link나 button_title은 선택 사항입니다. 이 요청을 보내면, access_token을 발급받은 사용자의 카카오톡으로 메시지가 전송됩니다. 🎉 정말 간단하죠?
4. 자주 묻는 질문(FAQ) 및 문제 해결 팁
카카오톡 API를 처음 사용하면서 흔히 겪는 문제와 해결책을 정리해 봤습니다.
Q1. access_token이 만료되었다고 에러가 납니다.
A. access_token은 만료 시간이 있습니다. 이럴 땐 앞서 발급받았던 refresh_token을 사용해 새로운 access_token을 재발급받아야 합니다. 재발급 요청은 grant_type을 refresh_token으로 지정하고, refresh_token 값을 포함하여 https://kauth.kakao.com/oauth/token에 POST 요청을 보내면 됩니다.
Q2. “invalid grant” 에러가 발생합니다.
A. 이 에러는 주로 인증 코드(code)가 만료되었거나 이미 사용되었을 때 발생합니다. 인증 코드는 한 번 사용하면 무효화되므로, 매번 새로운 코드를 받아와야 합니다. 또한, 인증 코드는 발급 후 10분 이내에 사용해야 합니다.
Q3. Redirect URI를 잘못 설정했습니다.
A. Redirect URI는 카카오 개발자 사이트에서 설정한 값과 요청 시 보낸 값이 정확히 일치해야 합니다. 오타나 http, https 여부, 포트 번호 등을 꼼꼼히 확인하세요.
Q4. 카카오톡 API를 통해 친구에게 메시지를 보내고 싶습니다.
A. 친구에게 메시지를 보내는 기능은 “카카오톡 소셜” API를 사용해야 합니다. 이 기능은 access_token 외에 추가적인 권한 동의(친구 목록 조회 등)가 필요하며, 더 복잡한 과정을 거쳐야 합니다. “나에게 메시지 보내기”와는 다른 API를 호출해야 하므로, 카카오 개발자 문서를 참고하여 추가 설정을 진행해야 합니다.
💡 팁: 개발 초기에는 Postman이나 Insomnia와 같은 API 테스트 도구를 사용하면 코드 작성 없이도 각 단계의 요청과 응답을 직접 확인하며 쉽게 테스트할 수 있습니다. 카카오 개발자 문서는 매우 상세하게 잘 정리되어 있으니, 막히는 부분이 있다면 가장 먼저 공식 문서를 참고하는 것이 좋습니다.