메시지 API 연동의 전체 흐름

메시지 API 연동은 크게 4단계로 이루어집니다. 

[1단계] 사전 준비 발송 서비스에 가입하고 발신번호, 카카오톡 채널, RCS 브랜드 등 채널별 발신 정보를 등록합니다.

[2단계] 인증 API Key를 발급받고 허용 IP를 등록합니다. 비즈고 기준으로는 통합 KEY 하나로 모든 채널의 API를 이용할 수 있어요.

[3단계] 발송 수신자 번호와 메시지 내용을 담은 요청을 API 서버에 보냅니다.

[4단계] 결과 확인 메시지가 실제로 단말기에 도달했는지 발송 결과 리포트를 수신합니다.

비즈고 API의 핵심 구조

비즈고(인포뱅크)는 통신 3사 직연결 문자 중계사이자 카카오톡 비즈메시지 공식 딜러사로 SMS, LMS, MMS, RCS, 카카오톡 알림톡, 브랜드 메시지를 모두 지원합니다. 이 채널들을 하나의 API Key와 하나의 엔드포인트로 발송할 수 있는 것이 비즈고 API의 핵심이에요.

발송 요청 하나에 여러 채널의 메시지를 순서대로 담을 수 있고 앞 순서 채널이 실패하면 다음 채널로 자동 전환됩니다. 알림톡을 보냈는데 수신자가 카카오톡을 쓰지 않으면 RCS로 전환하고 그것도 실패하면 LMS로 보내는 식이에요. 이 전체 흐름이 한 번의 API 호출로 처리됩니다. 

AI 코딩 도구로 연동 시작하기

메시지 API를 연동할 때 인증 헤더 구성, 요청 본문 작성, 에러 핸들링 같은 반복적인 코드 작업에 시간이 많이 들어갑니다. 비즈고 개발자센터는 Cursor, Claude, ChatGPT 같은 AI 코딩 도구에서 바로 참조할 수 있도록 llms.txt 파일을 제공하고 있어요. 

llms.txt로 AI에 비즈고 문서 연결하기

llms.txt는 AI 모델이 문서 구조를 효율적으로 파악할 수 있도록 만든 표준 포맷입니다. 각 페이지의 제목, URL, 설명이 정리되어 있어서 AI 도구에 컨텍스트로 추가하기 좋아요.

도구별 활용 방법

1) Cursor 대화창에 @Docs https://developers.bizgo.io/llms.txt를 입력하면 비즈고 API 문서를 즉시 참조합니다. 프로젝트 설정의 Docs에 등록해두면 이후에는 @Bizgo Docs로 언제든 불러올 수 있어요.

2) Claude Code 프로젝트의 .claude/CLAUDE.md 파일에 비즈고 문서 URL을 추가해 두면 됩니다. 이후 ‘SMS 발송 코드 작성해줘’처럼 요청하면 비즈고 API 스펙에 맞는 코드를 바로 생성할 수 있어요.

3) ChatGPT 프롬프트에 llms-full.txt URL을 붙여넣고 질문하면 됩니다. 전체 문서 내용이 포함된 llms-full.txt를 사용하면 더 정확한 결과를 얻을 수 있어요.

이 가이드에서 전체 흐름과 핵심 개념을 파악한 뒤 실제 코드 작성은 AI 도구와 비즈고 개발자센터를 함께 활용하면 연동 시간을 크게 줄일 수 있습니다.

알아두면 연동이 빨라지는 핵심 개념

API 문서를 처음 열면 messageFlow, 대체발송, 멱등성 키 같은 용어가 나옵니다. 이 개념들을 미리 파악해두면 코드를 읽고 설계하는 속도가 확 달라져요. 

1. messageFlow와 대체발송

messageFlow는 발송 요청에서 메시지를 담는 배열입니다. 배열의 순서가 곧 발송 우선순위예요. 첫 번째 메시지가 실패하면 두 번째 메시지로 자동 전환되고 그것도 실패하면 세 번째로 넘어가는 구조입니다. 이 동작을 대체발송 또는 폴백(fallback)이라고 부릅니다.

예를 들어 알림톡 → RCS → LMS 순서로 messageFlow에 담으면 카카오톡을 쓰지 않는 수신자에게는 자동으로 RCS가 발송되고 RCS 수신이 불가능한 단말에는 LMS가 전달돼요. 채널별로 메시지 내용을 다르게 구성할 수도 있습니다.

대체발송의 상세 동작과 비즈고에서의 설정 방법은 알림톡 발송 실패 시 폴백 활용 가이드에서 확인할 수 있습니다.

2. 치환메시지와 멱등성 키

치환메시지는 메시지 본문에 변수를 넣고 수신자별로 다른 값을 적용하는 기능입니다. #{name}님, #{orderName} 주문이 완료되었습니다처럼 작성하면 발송 시 수신자별 값으로 자동 치환돼요.

멱등성 키는 같은 요청을 여러 번 보내도 결과가 한 번만 반영되도록 보장하는 식별값입니다. 네트워크 타임아웃으로 응답을 못 받아서 같은 요청을 재전송할 때 주문번호 같은 업무 단위 값을 멱등성 키로 설정해두면 중복 발송을 방지할 수 있어요. 대량 발송 환경에서 특히 중요한 개념입니다.

3. 발송 결과 확인 방식

메시지 발송 후에는 실제 도달 여부를 확인하는 리포트를 수신해야 합니다. 

4. 동보발송과 Rate Limit

대량 발송을 설계한다면 두 가지를 더 알아 두면 좋아요

1) 동보발송은 1회 API 호출로 여러 수신자에게 동시에 발송하는 방식입니다. 비즈고 API 기준 최대 200명까지 한 번에 발송할 수 있어요. 10만 건을 1건씩 호출하면 10만 번 요청이 필요하지만 200건씩 동보발송하면 500번이면 됩니다.

2) Rate Limit은 API 제공자가 허용하는 초당 최대 호출 횟수입니다. 비즈고 기준 발송 API는 200 TPS(Transactions Per Second)이고 이를 초과하면 429 응답이 반환돼요. 기본 TPS가 부족한 경우 영업 담당자에게 한도 상향을 요청할 수 있습니다. 대량 발송에서는 429 응답이나 네트워크 타임아웃으로 재시도가 발생할 수 있기 때문에 멱등성 키를 설정해서 중복 발송을 방지하는 것도 함께 설계해야 합니다. 구체적인 대량 발송 설계 방법은 알림톡 API 대량 발송, TPS와 Rate Limit 설계 가이드에서 코드 수준까지 다루고 있습니다.

채널별 사전 준비와 연동 일정 계산

메시지 API 연동 일정을 산정할 때 개발 기간만 고려하면 안 됩니다. 채널마다 사전 준비에 필요한 절차와 소요 기간이 다르기 때문이에요. 특히 카카오톡 알림톡은 비즈니스 채널 심사와 템플릿 검수에 각각 영업일이 소요되어 준비 기간이 길어질 수 있습니다.

문자는 발신번호 등록만 완료되면 발송이 가능해서 가장 빠르게 연동할 수 있습니다. 반면 알림톡은 카카오톡 채널 개설부터 템플릿 검수까지 여러 단계의 대기 시간이 있어요. 처음 연동한다면 문자부터 시작해서 알림톡, RCS 순서로 확장하는 방식이 일반적입니다.

채널별 사전 준비 항목을 기획자나 PM이 미리 챙겨야 할 체크리스트로 정리한 글도 있습니다. 개발팀에 연동 요청을 넘기기 전에 메시지 API 연동 전 체크리스트를 함께 공유하면 커뮤니케이션 비용을 줄일 수 있어요. 알림톡 연동의 전체 절차가 궁금하다면 알림톡 API 연동 가이드에서 발신 프로필 준비부터 테스트 발송까지 단계별로 확인할 수 있습니다.

비즈고(인포뱅크)는 통신 3사 직연결 문자 중계사이자 카카오톡 비즈메시지 공식 딜러사로 SMS, LMS, MMS, RCS, 알림톡, 브랜드 메시지를 하나의 API로 연동할 수 있습니다. 비즈고 개발자센터에서 API 레퍼런스와 SDK를 확인하고 샌드박스에서 테스트 발송을 시작해보세요.

이번 글에서는 비즈고 알림톡 API에서 템플릿을 조회, 등록, 수정하는 방법을 중심으로 정리했습니다. 실제 요청 방식과 세부 값은 알림톡 API 문서에서 확인할 수 있습니다.

비즈고 알림톡 API가 제공하는 템플릿 관리 기능

비즈고 알림톡 API는 메시지 발송 외에도 템플릿을 조회하고, 새로 등록하고, 수정하고, 검수 요청까지 보낼 수 있는 기능을 함께 제공합니다. 작업별로 필요한 API를 먼저 정리하면 이렇습니다.

조회 API로 확인할 수 있는 템플릿 정보

이미 등록된 템플릿을 확인할 때는 템플릿 조회 API를 사용합니다. 기준이 되는 값은 senderKey와 templateCode입니다. senderKey는 카카오톡 비즈메시지 발신프로필 키이고, templateCode는 알림톡 템플릿을 구분하는 코드예요.

조회 API에서는 템플릿 이름, 본문은 물론 검수 상태나 버튼 정보처럼 운영 중에 필요한 값까지 함께 확인할 수 있어요. 

알림톡 API를 사용할 때 특히 자주 보게 되는 값은 inspectionStatus입니다. 등록 직후에는 아직 발송에 사용할 수 없거든요. 알림톡 템플릿은 카카오 검수 승인 이후 사용할 수 있으므로, 등록 후에는 조회 API로 검수 상태를 다시 확인해야 합니다.

등록 API에서 꼭 보내야 하는 값

새 알림톡 템플릿을 만들 때는 템플릿 등록 API를 사용합니다. 등록 요청에서 핵심이 되는 값은 다음과 같아요. 

여기서 가장 먼저 정해야 할 값은 templateCode입니다. 등록 후 조회, 수정, 검수 요청, 발송 단계에서 계속 사용되는 값이기 때문이에요. 이후 알림톡 템플릿 자동치환 발송을 사용할 때도 템플릿 코드를 기준으로 본문을 불러와 변수 값을 치환합니다.

본문에는 #{name}, #{orderNo}처럼 변수 자리를 넣을 수 있습니다. 다만 알림톡은 변수를 제외한 본문이 고정되는 구조예요. 따라서 실제 고객별로 달라지는 이름, 주문번호, 날짜 같은 값은 변수로 분리하고, 승인받아야 하는 문구는 템플릿 본문에 정확히 넣어야 합니다.

버튼이나 링크가 필요한 경우에는 attachment 또는 link 구조를 함께 사용합니다. 예를 들어 주문 조회, 배송 조회, 예약 확인 버튼을 붙이는 템플릿이라면 버튼명과 모바일 URL, PC URL 등을 함께 넘기게 됩니다.

이미지 템플릿 등록 전에 필요한 업로드 API

이미지형, 와이드 이미지형, 아이템리스트형 템플릿은 이미지를 먼저 올린 뒤 등록하는 구조입니다.

템플릿 이미지 업로드 API에 이미지 파일을 FORM-DATA로 업로드하면 응답으로 imgUrl, fileName을 받아요. 이후 템플릿 등록 요청에서 imgUrl은 그대로, fileName은 imgName 필드에 넣어 함께 보내면 됩니다.

알림톡 이미지를 어떻게 준비해야 하는지 궁금하다면 준비된 이미지 없이도, 알림톡 이미지 바로 완성하는 법에서 확인해 보세요. 

등록한 템플릿을 검수 요청하는 법

등록한 템플릿을 카카오 검수로 넘기려면 템플릿 검수 요청 API를 호출합니다. 검수 요청에서 필요한 핵심 값은 senderKey와 templateCode예요. 검수 의견이나 문의 사항이 있다면 comment 값을 함께 보낼 수 있습니다. 템플릿 상태가 대기이고 검수 상태가 등록인 경우 검수 요청을 보낼 수 있어요. 검수 요청을 이미 보낸 뒤 취소해야 한다면 검수 요청 취소 API를 사용할 수 있습니다. 

수정 API로 바꿀 수 있는 항목과 주의할 점

등록된 템플릿 정보를 수정할 때는 템플릿 수정 API를 사용합니다. 수정 요청에 들어가는 구조는 등록 API와 비슷합니다. senderKey, templateCode, templateName, templateMessageType, templateEmphasizeType, text 같은 값을 기준으로 템플릿 정보를 다시 보냅니다. 

다만 수정이 가능한 건 등록만 하고 아직 검수를 요청하지 않은 템플릿입니다. 승인된 템플릿은 수정이나 삭제가 되지 않아요. 승인된 템플릿의 내용을 바꿔야 한다면 새 템플릿을 등록한 뒤 검수를 다시 진행해야 합니다. 

자체 시스템에서 알림톡 템플릿을 관리하려면 등록, 조회, 수정, 검수 요청 API를 순서대로 연결하는 흐름이 필요합니다. 각 API의 상세 파라미터와 응답 구조는 알림톡 API 문서에서 확인할 수 있고, 샌드박스에서 실제 요청을 테스트해볼 수도 있어요. 알림톡 API 연동을 검토하고 있다면 언제든 비즈고에 도입 문의를 남겨주세요.

FAQ

Q. 알림톡 템플릿을 API로 등록하면 바로 발송할 수 있나요?

아니요. 알림톡 템플릿은 카카오 검수 승인 이후 사용할 수 있습니다. 등록 API 호출 후에는 검수 요청 API를 호출하고, 조회 API로 검수 상태를 확인해야 합니다.

Q. 승인 여부는 어떤 API로 확인하나요?

템플릿 조회 API에서 inspectionStatus 값으로 검수 상태를 확인합니다. 운영 중인 템플릿이라면 차단 여부나 휴면 여부도 함께 보면 돼요. 

Q. 자동치환 발송과 템플릿 등록 API는 어떤 관계인가요?

템플릿 등록 API는 발송 전에 템플릿 자체를 만드는 API입니다. 자동치환 발송은 이미 등록된 템플릿의 templateCode와 변수 값만으로 알림톡을 보내는 발송 방식이에요. 템플릿을 먼저 등록하고 승인받아야 자동치환 발송에서도 해당 코드를 사용할 수 있습니다.

첫째, 원하는 메시지를 알림톡으로 보낼 수 있을까?

알림톡은 광고 메시지가 아니라 정보성 메시지를 보내는 채널입니다. 주문, 결제, 배송, 예약, 인증, 계약, 이용 안내처럼 사용자가 이미 한 행동이나 서비스 이용 과정과 직접 연결된 내용에 적합해요.

반대로 할인 행사, 신상품 안내, 쿠폰 사용 유도처럼 구매를 유도하는 내용은 알림톡보다 브랜드 메시지나 문자 채널을 검토해야 합니다. 

둘째, 발송 시나리오를 정리하세요 

보낼 수 있는 메시지가 정리되었다면 다음은 발송 시나리오입니다. 누가, 어떤 상황에서, 어떤 고객에게, 어떤 내용을 보내는지가 정리되어야 합니다. 예를 들어, ‘주문 완료 알림톡을 보냅니다’라고만 쓰면 운영 범위가 모호해요. 아래처럼 이벤트 단위로 쪼개면 개발, 운영, CS가 확인해야 할 내용이 분명해집니다.

예시 시나리오

• 발송 이벤트: 고객이 결제를 완료했을 때
• 발송 대상: 결제 완료 고객
• 메시지 목적: 주문번호, 결제금액, 배송 예정일 안내
• 필수 변수: 고객명, 주문번호, 상품명, 결제금액, 배송 예정일
• 후속 처리: 발송 실패 시 문자로 대체발송

이 정도만 정리해도 도입 논의가 훨씬 빨라집니다. 개발팀은 필요한 데이터와 연동 범위를 확인할 수 있고, 운영팀은 템플릿 문구와 고객 문의 흐름을 미리 볼 수 있어요. 

셋째, 예상 발송량과 비용을 확인하세요

월 예상 발송 건수, 피크 시간대, 특정 시즌에 발송량이 몰리는지를 정리해두면 비용과 시스템 부담을 같이 판단할 수 있습니다.

발송량에 따라 비용 구조가 달라지는 경우도 있기 때문에 품의 단계에서 대략적인 규모라도 파악해두는 것이 좋아요. 발송량 구간별 비용 시뮬레이션은 알림톡 가격, 우리 회사 발송량이면 얼마일까? 글을 참고하세요.

넷째, 카카오톡 채널 상태를 확인하세요

알림톡을 보내려면 카카오톡 비즈니스 채널이 필요합니다.

• 사용할 카카오톡 채널이 이미 있는가?
• 채널 관리자 권한을 가진 담당자가 정해져 있는가?
• 채널 프로필에 고객센터 연락처가 등록되어 있는가?

 카카오톡 채널 정보를 등록할 때 고객센터 연락처 등 필수 정보를 꼼꼼히 입력해야 알림톡 발송이 가능한 채널이 됩니다. 카카오톡 채널은 여러 명의 매니저를 등록해서 운영할 수 있으니 도입을 담당하는 실무자가 채널 관리 매니저 권한을 부여받아두면 이후 진행이 수월해요.

채널 개설부터 비즈니스 채널 심사까지 전체 과정은 카카오톡 비즈니스 채널 만들기 가이드를 참고하세요.

다섯째, 운영 방식을 고르세요

알림톡 도입 방식은 크게 세 가지로 나눠볼 수 있습니다.  카카오톡 딜러사에서 제공하는 웹페이지에서 직접 보내는 웹발송, 업무 자동화를 지원하는 노코드 서비스와 연결하는 노코드 방식, 내부 시스템과 연동하는 API 방식입니다. 

처음부터 API 연동이 필요한 것은 아닙니다. 발송 건수가 적고 담당자가 직접 관리해도 되는 업무라면 웹발송으로 시작할 수 있어요. 반대로 주문, 결제, 배송처럼 시스템 이벤트와 즉시 연결되어야 하는 메시지라면 API 연동이 적합합니다. 세 가지 방식의 차이와 선택 기준은 자동 문자 발송 방법 비교 가이드에서 확인할 수 있습니다.  비즈고는 웹발송, 노코드 자동화(Make, n8n 등), API 연동을 모두 지원합니다.

여섯째, 대체발송 기준을 정하세요

카카오톡 비즈메시지(알림톡, 브랜드 메시지)는 수신 환경이나 템플릿 불일치 등으로 발송 실패가 발생할 수 있습니다. 실패 시 문자로 대체발송할지 여부를 미리 정해두세요.

한 가지 주의할 점은 대체발송을 설정하기 전에 알림톡 발송을 충분히 테스트해야 한다는 점입니다 템플릿 변수를 잘못 넣거나 시스템에서 호출할 때 공백이 들어가는 등의 실수로 알림톡이 대량 실패하면 전부 문자로 대체발송되어 예상치 못한 비용이 발생할 수 있어요. 테스트를 거친 뒤에 대체발송을 활성화하는 것이 안전합니다.

비즈고에서는 웹 콘솔에서 카카오톡 비즈메시지 실패 시 문자 대체발송을 설정할 수 있고, API를 사용하면 RCS까지 포함한 다단계 대체발송도 구현할 수 있습니다. 

자주 묻는 질문

Q. 왜 문자 대신 알림톡을 쓰나요?

고객이 카카오톡에서 바로 확인할 수 있고, 주문, 예약, 배송처럼 서비스 이용 과정의 정보성 안내에 적합하기 때문입니다. 광고성 메시지는 알림톡 대상이 아니므로 브랜드 메시지나 문자 채널을 별도로 검토합니다.

Q. 개발이 꼭 필요한가요?

업무 방식에 따라 다릅니다. 소규모 수동 발송은 웹발송으로, 외부 서비스와 자동 연결이 필요하면 노코드 자동화로, 시스템 이벤트와 실시간 연동해야 하면 API 연동으로 시작할 수 있어요.

Q. 템플릿이 반려되면 어떻게 하나요?

반려 사유에 맞춰 문구나 변수 구조를 수정한 뒤 다시 검수를 받아야 합니다. 오픈 일정에는 템플릿 수정 시간을 포함하는 것이 좋습니다. 비즈고에서는 카카오와 사전 승인을 마친 검수패스 템플릿을 제공하고 있어 검수 대기 없이 바로 발송을 시작할 수도 있어요.

Q. 발송 실패는 어떻게 처리하나요?

카카오톡 비즈메시지(알림톡, 브랜드 메시지)가 실패한 경우 문자로 대체발송되도록 설정할 수 있습니다. API를 사용하면 RCS를 포함한 다단계 대체발송도 가능해요.    

알림톡 도입 전 최종 체크리스트

아래 항목에 답할 수 있다면 알림톡 도입 논의를 시작할 준비가 된 상태입니다.

□ 발송하려는 메시지가 정보성 메시지인지 확인했다
□ 광고성 표현이나 구매 유도 문구가 섞여 있지 않은지 점검했다
□ 발송 이벤트, 대상, 목적, 필수 변수를 정리했다
□ 월 예상 발송량과 피크 시간대를 확인했다
□ 사용할 카카오톡 채널과 관리자 권한을 확인했다
□ 웹발송, 노코드, API 중 운영 방식을 선택했다
□ 알림톡 발송 실패 시 대체발송 여부를 결정했다
□ 발송 결과와 리포트를 확인할 담당자와 기준을 정했다

처음부터 완벽할 필요는 없습니다

알림톡 도입은 한 번에 모든 시나리오를 자동화하는 프로젝트로 시작하지 않아도 됩니다. 오히려 가장 명확한 업무 이벤트 하나를 정해 먼저 운영해보는 편이 안정적입니다. 

예를 들어 주문 완료, 예약 확정, 배송 안내처럼 고객 문의를 줄이고 업무 효율을 바로 확인할 수 있는 메시지부터 시작할 수 있어요. 이후 발송 결과와 고객 반응을 보면서 템플릿을 정리하고, 필요한 시나리오를 단계적으로 늘리면 됩니다.

비즈고(인포뱅크)는 통신 3사 직연결 중계사이자 카카오톡 비즈메시지 공식 딜러사로, 알림톡을 포함한 카카오톡 비즈니스 채널과 문자 채널을 함께 운영할 수 있는 메시징 환경을 제공합니다. 알림톡 도입을 검토하고 있다면 먼저 위의 체크리스트를 기준으로 정리해보세요. 

과금 없이 API를 테스트하는 샌드박스

샌드박스는 실제 메시지를 발송하지 않고 API 요청과 응답 흐름을 확인할 수 있는 테스트 환경이에요. 운영 환경과 동일한 API 규격을 사용하되 Base URI만 샌드박스 주소로 변경하면 됩니다. 과금이 발생하지 않아서 연동 초기에 반복 호출하며 코드를 검증하기 좋습니다. 비즈고 개발자센터(developers.bizgo.io)의 샌드박스 페이지에서 별도 설치 없이 바로 테스트할 수 있어요.

샌드박스에서 할 수 있는 것

비즈고 샌드박스에서는 문자(SMS, LMS, MMS), 카카오톡 알림톡, 브랜드 메시지, 상담톡, 소셜 로그인 등 비즈고에서 제공하는 서비스를 모두 테스트할 수 있습니다. 개발자센터 샌드박스 페이지에서는 두 가지 모드를 제공해요.

• FORM 모드: 입력 필드에 값을 채워 바로 API를 호출해볼 수 있습니다. 코드를 작성하기 전에 API 스펙을 빠르게 탐색할 때 유용해요.
• JSON 모드: 실제 페이로드 구조를 그대로 확인하며 테스트할 수 있습니다.

발송 성공 응답뿐 아니라 실패 응답도 시뮬레이션할 수 있어서 에러 처리 코드를 미리 작성하기 좋습니다. 운영 중에 처음 보는 실패 케이스를 마주치는 일을 줄일 수 있죠.

운영 환경과 샌드박스 환경 비교

이처럼 환경에 따라 Base URI만 달라질 뿐 API 규격과 인증은 동일해서, 주소 한 줄만 바꾸면 샌드박스에서 검증한 코드를 운영에 그대로 사용할 수 있어요.

샌드박스 테스트 시 주의할 점 

샌드박스는 요청 전문 규격과 API 응답 흐름을 사전에 검증하기 위한 환경입니다. 실제 단말기로 메시지가 전송되지 않기 때문에 수신자가 메시지를 실제로 받았는지는 확인할 수 없어요.

카카오톡 알림톡이나 브랜드 메시지의 API 요청 규격은 샌드박스에서 정상적으로 검증할 수 있어요. 다만 카카오 채널 연동이 포함된 전체 흐름을 테스트하려면 운영 환경에서 진행하면 됩니다. 이 서비스들은 발신프로필 키(senderKey)라는 고유 식별값으로 발송 채널을 인증하는데 이 키가 운영 환경에서만 동작하기 때문이에요.

참고로 IP ACL을 등록한 뒤 샌드박스 계정에 반영되기까지 약 1시간정도 소요될 수 있습니다. 등록 직후에 테스트하면 ACL 오류가 발생할 수 있으니 시간을 두고 시도해 보세요.

알림톡 API 연동의 전체 프로세스가 궁금하다면 알림톡 API 연동 가이드를 참고해 보세요.

SDK로 반복 코드 없이 연동하기

샌드박스에서 API 스펙을 확인했다면 다음은 코드를 작성하는 단계입니다. 메시지 API를 직접 HTTP로 호출하면 인증 헤더 구성, 요청 본문 조립, 응답 파싱 같은 코드를 매번 작성해야 하는데 비즈고 SDK를 사용하면 이런 반복 작업을 줄이고 발송 로직에 집중할 수 있어요. 작성한 코드는 샌드박스에서 검증한 뒤 운영 환경으로 전환하면 됩니다.

지원 언어와 설치

비즈고는 Java, Node.js, Python 세 가지 언어의 공식 SDK를 제공합니다. 모두 오픈소스(Apache 2.0 라이선스)이고 GitHub에서 소스코드와 예제를 확인할 수 있어요.

설치 후 메시지를 발송하는 기본 흐름은 세 언어 모두 비슷합니다. Java의 경우 API Key로 클라이언트를 초기화하고 메시지 객체를 만들어 발송 메서드를 호출하면 돼요.

어떤 SDK를 선택할까

세 SDK 모두 비즈고 통합 메시지 API를 지원하고 대체 발송, 동보 발송, 리포트 조회 같은 핵심 기능을 동일하게 사용할 수 있어요. 개발 환경에 맞춰 선택하면 됩니다.

• Java: Spring Boot 기반 백엔드에서 안정적인 서버 연동이 필요할 때 적합합니다. Spring Boot 3.x와 4.x를 모두 지원해요.
• Node.js: JavaScript나 TypeScript 환경에서 빠른 개발과 배포가 우선일 때 적합합니다.
• Python: 기존 파이썬 운영 환경에 맞추거나 스크립트 기반 자동화를 구성할 때 적합해요.

샌드박스에서 바로 시작해보세요

비즈고 개발자센터에서 샌드박스에 접속하면 회원가입만으로 바로 API를 호출해볼 수 있습니다. SDK로 코드를 작성하면서 샌드박스에서 검증하고, 준비가 되면 Base URI만 운영 환경으로 전환하면 됩니다. 연동 중 궁금한 점은 개발자 커뮤니티에서 질문할 수 있어요.

이메일과 전화로 돌리던 안내, 어디서부터 밀리기 시작했을까요

학회·협회 사무국의 회원 안내 업무는 크게 연회비 납부 안내, 학술대회 등 행사 안내, 취소·환불 사후 처리 세 가지로 나뉘는데, 공통점이 있어요. 셋 다 건건이 수작업이라는 점입니다.

• 이메일 열람률이 낮아서 안내를 보내도 못 본 회원이 ‘결제했는데 확인이 안 됐다’고 전화를 하면 같은 내용을 다시 안내해야 합니다
• 학술대회 시즌에 업무가 몰려서 등록 확인, 결제 안내, 일정 변경 공지가 한꺼번에 쏟아지면 사무국의 다른 업무가 멈추게 되죠
• 단체 문자 발송도 한계가 있어서 SMS는 한글 45자로 정보가 부족하고, LMS로 전환하면 비용이 올라가고, 읽었는지 확인하기도 어려워요

회원 수는 수천에서 수만 명인데 사무국 인력은 몇 명 안 되는 경우가 대부분이에요. 발송 채널의 문제라기보다 ‘같은 안내를 반복하는 구조’ 자체가 사무국의 병목이 됩니다.

알림톡으로 보낼 수 있는 안내와 보낼 수 없는 안내

카카오톡 알림톡은 ‘정보성 메시지’만 발송 가능하고, 그 기준도 명확해요. 카카오 공식 가이드 기준으로 정보성 메시지에 해당하는 경우는 세 가지입니다.

• 수신자의 요청에 기반한 정보: 회원이 신청, 결제, 등록 등 행동을 한 뒤 그 확인·결과를 알려주는 메시지
• 법령·약관에 따라 고지 의무가 있는 정보: 정관이나 회원 약관에서 납부 안내, 자격 변경 등의 고지를 규정한 경우
• 고객의 안전, 생명, 재산 보호 목적의 안내

학회·협회 사무국 업무에 이 기준을 적용하면 이렇게 나뉩니다.

이 구분이 중요한 이유는 알림톡 템플릿을 카카오에 검수 요청할 때 반려되는 가장 흔한 원인이 바로 ‘정보성 메시지’ 기준 미충족이기 때문이에요. 연회비 납부 안내처럼 약관상 고지 의무가 있는 메시지는 알림톡으로 발송할 수 있지만, 정보성 기준에 해당하지 않는 메시지는 알림톡이 아닌 다른 채널을 사용해야 합니다.

정리하면 회원의 행동에 대한 확인이나 약관상 고지 의무가 있는 안내는 알림톡, 정보성 기준에 해당하지 않는 광고성 메시지는 문자(SMS, LMS)나 브랜드 메시지를 활용하는 구조예요. 두 채널을 함께 쓰면 학회·협회의 회원 안내 업무 대부분을 커버할 수 있습니다.

학회·협회 실무에서 바로 쓸 수 있는 알림톡 템플릿 예시

알림톡 템플릿은 변수를 제외한 본문이 고정되어 있어요. #{회원명}, #{납부금액}처럼 회원마다 달라지는 정보만 변수로 처리하고, 나머지 문구는 사전에 카카오 검수를 받아 승인된 그대로 발송됩니다.

학회·협회에서 자주 쓰게 될 시나리오별로 템플릿 구성 예시를 정리했습니다.

1) 연회비 납부 안내

이 템플릿은 정관·약관상 고지 의무에 해당하는 안내예요. 기본형으로 구성하고, 홈페이지 바로가기 버튼을 추가하면 회원이 직접 납부 페이지로 이동할 수 있어서 사무국에 전화 문의가 줄어듭니다. 본문에서 납부 방법(계좌이체, 카드결제 등)을 안내하는 건 가능하지만, 카카오페이를 제외한 특정 결제 서비스를 통한 납부를 직접 유도하는 표현은 제한될 수 있어요.

2) 연회비 납부 완료 확인

이 템플릿은 정관·약관상 고지 의무에 해당하는 안내예요. 기본형으로 구성하고, 홈페이지 바로가기 버튼을 추가하면 회원이 직접 납부 페이지로 이동할 수 있어서 사무국에 전화 문의가 줄어듭니다. 본문에서 납부 방법(계좌이체, 카드결제 등)을 안내하는 건 가능하지만, 카카오페이를 제외한 특정 결제 서비스를 통한 납부를 직접 유도하는 표현은 제한될 수 있어요.

3) 학술대회 참가 등록 확인

학술대회 등록 확인은 전달할 정보가 많기 때문에 아이템리스트형 템플릿을 활용하면 정보가 깔끔하게 정리돼요. 일시, 장소, 등록 유형, 등록번호를 리스트로 구성하고, 하단에 홈페이지 바로가기 버튼을 넣으면 회원이 필요한 정보를 한눈에 확인할 수 있습니다.

4) 참가 취소·환불 안내

취소·환불 안내는 회원이 가장 빨리 확인하고 싶어하는 메시지예요. 환불 금액과 예상 환불일을 명시하면 ‘언제 돈이 돌아오나요?’라는 후속 문의가 줄어들어요.

템플릿 설계 시 유의할 점

알림톡 템플릿은 카카오에 검수 요청 후 영업일 기준 2~3일 정도 소요됩니다. 반려 없이 승인받으려면 몇 가지를 신경 써야 해요.

먼저 본문에 광고성 표현이 들어가면 안 됩니다. ‘지금 등록하시면 할인!’ 같은 문구가 들어가면 정보성 메시지 기준에 맞지 않아 반려돼요. 버튼명에 ‘결제’, ‘납부’ 같은 단어를 포함하는 건 가능합니다. 세부 심사 기준과 반려 사유는 카카오 알림톡 심사 가이드에서 확인할 수 있어요.

도입 절차, 어디서부터 시작하면 되나요

알림톡 도입은 세 단계로 진행됩니다.

1단계. 카카오톡 비즈니스 채널 개설 (필수)

어떤 발송 방식을 선택하든 가장 먼저 해야 할 일이에요. 학회·협회 명의로 카카오톡 채널을 만들고 비즈니스 채널 심사를 받아야 합니다. 채널 프로필에 사무국 전화번호를 등록해야 발신 프로필 키를 생성할 수 있다는 점만 기억해 두세요. 상세 절차는 카카오톡 비즈니스 채널 개설 가이드에서 확인할 수 있습니다.

2단계. 발송 방식 선택 (3가지 중 택 1)

사무국 환경에 맞는 방식을 하나 고르면 돼요. 자동 문자 발송 방법 비교 가이드에서 세 가지 방식의 차이를 자세히 비교할 수 있습니다.

• 웹발송: 비즈고 콘솔에서 직접 수신자를 입력하고 보내는 방식. 개발이 필요 없어서 바로 시작할 수 있어요. 발송 빈도가 낮은 학회에 적합합니다.
• 노코드 자동화: Make, n8n 같은 도구를 활용해서 회원 가입이나 결제 이벤트에 맞춰 자동 발송하는 방식. 개발자 없이도 자동화를 구축할 수 있어요.
• API 연동: 회원관리 시스템에 직접 연동해서 완전한 자동화를 구현하는 방식. 초기 개발이 필요하지만 한 번 구축하면 수작업이 사라집니다.

노코드 자동화를 선택했다면 노코드 자동 발송 가이드, API 연동을 선택했다면 알림톡 API 연동 가이드를 참고하세요.

3단계. 템플릿 검수 및 대체 발송 설정

앞서 정리한 시나리오별 템플릿을 카카오에 검수 요청하고, 대체 발송을 함께 설정하면 됩니다. 알림톡 발송이 실패하면(수신자가 카카오톡을 사용하지 않는 경우 등) 자동으로 문자(SMS, LMS)로 같은 내용이 발송돼요. 

비즈고는 통신 3사 직연결 문자 중계사이자 카카오톡 비즈메시지 공식 딜러사여서 알림톡과 문자 대체 발송을 하나의 플랫폼에서 운영할 수 있습니다. 학회·협회 사무국의 안내 업무는 대부분 정해진 시나리오의 반복이에요. 연회비 납부, 학술대회 등록, 취소·환불 같은 안내를 자동화하면 사무국이 매번 같은 연락을 돌리는 시간을 줄이고, 회원은 필요한 정보를 카카오톡으로 바로 받아볼 수 있습니다. 웹발송을 선택하면 개발 없이도 시작할 수 있으니 부담 없이 살펴보세요.

발송 결과를 수신하는 3가지 방식

메시지 API로 발송을 요청하면 즉시 돌아오는 응답은 ‘접수 결과’입니다. 비즈고 시스템에 정상적으로 접수됐는지만 알려주죠. 실제로 수신자 단말기에 메시지가 도착했는지는 별도로 ‘메시지 리포트’를 수신해야 알 수 있어요. 비즈고에서 제공하는 리포트 수신 방식은 세 가지입니다.

① 폴링으로 주기적으로 가져오기

폴링(Polling)은 일정 간격으로 비즈고 서버에 요청해서 결과를 가져오는 방식이에요.

GET/api/comm/v1/report/polling으로 처리 완료된 리포트를 조회하고, 수신한 리포트는 DELETE/api/comm/v1/report/polling/{reportId}로 수신 확인 처리합니다.

웹훅 수신 서버를 별도로 구축하지 않아도 돼서 인프라가 단순한 환경에서 도입이 수월해요. 다만 호출 주기 사이에 시간차가 생기기 때문에 실시간 확인이 필요하면 웹훅 방식이 더 적합합니다.

② 웹훅으로 실시간 수신받기

웹훅(Webhook)은 발송 결과가 확정되는 즉시 비즈고 서버가 등록된 URL로 결과를 보내주는 방식이에요. 별도 요청 없이 결과가 자동 전달되기 때문에 실시간 처리에 유리합니다.

비즈고 웹훅은 HMAC 서명 검증을 지원해요. 수신할 때 X-IB-Timestamp와 X-IB-Signature 헤더를 확인하면 요청이 비즈고에서 온 것인지 검증할 수 있습니다. 타임아웃은 5초이고 최대 3회까지 재시도해요.

③ 개별조회로 누락분 보완하기

개별조회(Inquiry)는 특정 메시지 한 건의 결과를 메시지 키(msgKey)로 직접 조회하는 방식입니다. GET/api/comm/v1/report/inquiry/{msgKey}로 최대 30일 이전의 리포트까지 조회할 수 있어요.

폴링이나 웹훅에서 일부 건의 결과가 누락됐거나 특정 건의 상태를 즉시 확인해야 할 때 보완 수단으로 씁니다.

세 방식 모두 비즈고 개발자센터 메시지 리포트 페이지에서 상세 스펙과 요청, 응답 예시를 확인할 수 있어요. 샌드박스에서 실제 발송 없이 응답 흐름을 미리 테스트해볼 수도 있습니다.

카카오톡 비즈메시지는 응답방식 설정도 확인하세요

카카오톡 알림톡이나 브랜드 메시지를 발송할 때는 responseMethod 설정에 따라 발송 성공 판단 기준이 달라집니다.

Push 방식 (권장)

수신자가 활성 사용자 조건에 해당하면 ACK 여부를 기다리지 않고 바로 발송 성공으로 처리해요. 성공 판단이 빠르기 때문에 대체 발송(Fallback) 시 메시지 중복 수신을 줄일 수 있습니다. 활성 사용자란 최근 7일(168시간) 안에 카카오톡을 사용한 사용자이고 발송 당일 가입자는 제외돼요.

Polling 방식

설정한 timeout 안에 수신 결과가 돌아오면 성공(MS03), 미도착이면 ‘성공불확실'(ME09)로 분류합니다. timeout 범위는 10초에서 86,400초(1일)까지 설정할 수 있고 기본값은 180초(3분)이에요.

발송 결과를 조회하고 분석하는 법

리포트로 성공, 실패 여부를 수신했다면 다음은 발송 데이터를 조회하고 분석하는 단계예요.

1) 개별 건 추적

특정 수신자에게 보낸 메시지가 실패했는지 확인하거나 CS 문의에 대응해야 할 때 사용합니다.

비즈고 웹 콘솔의 [통계/내역 – 시스템 발송 – 발송내역] 메뉴에서는 수신자 정보, 발송 채널과 메시지 유형, 발송 상태, 날짜와 시간 범위, 발신번호, 템플릿 등 다양한 조건을 조합해서 검색할 수 있어요.

• Raw Data 확인: 단건 상세 화면에서 API 호출 당시 전달된 원본 데이터를 그대로 확인할 수 있어요. 발송 실패 원인 파악 시 요청 전문을 직접 볼 수 있어서 개발팀과 운영팀 사이의 커뮤니케이션 비용이 줄어듭니다.
• 발송 상태 타임라인: 접수부터 발송, 결과 수신까지 메시지가 거친 단계를 시간순 로그로 보여줘요. 어느 구간에서 지연이나 실패가 발생했는지 한눈에 파악할 수 있습니다.

API로는 메시지 인사이트 API의 상태 조회를 사용합니다. 단건은 msgKey, 여러 건은 requestId 기준으로 조회하고, GET/api/comm/v1/message/history로 발송 이력 전체를 조회할 수도 있어요.

2) 템플릿별 성과 분석

템플릿 단위의 전체 성과를 파악할 때 사용합니다.

비즈고 웹 콘솔의 [통계/내역 – 통계 – 템플릿별 통계] 메뉴에서는 카카오톡 알림톡과 브랜드 메시지의 템플릿별 발송 결과를 조회할 수 있어요. 성공 건수, 발송률, 유효 읽음수, 총클릭수, 버튼별 클릭수까지 확인 가능하고 엑셀 파일로 다운로드도 돼요. 이 통계는 2025년 7월 1일 발송분부터 제공되며 최대 6개월 전 데이터까지 조회할 수 있습니다.

API로 전체 데이터를 조회할 때는 GET/api/comm/v1/message/statistics로 기간별, 채널별 접수와 리포트 통계를 가져올 수 있습니다. 카카오톡 채널 기반의 더 세분화된 데이터가 필요하면 알림톡 인사이트 API와 브랜드메시지 인사이트 API로 발송 성공률, 읽음률, CTR은 물론 시간대별 반응 지표와 템플릿별 성과까지 확인할 수 있어요.

이 API들은 비즈고 개발자센터 메시지 인사이트 페이지에서 스펙을 확인할 수 있습니다.

발송 로그 보관 기간, 미리 알아두면 좋은 이유

발송 결과 데이터는 무한정 보관되지 않습니다. 조회 방법에 따라 보관 기간이 다르기 때문에 미리 파악해두는 게 좋아요. 

• API 메시지 리포트 개별조회: 기본 30일, 비즈고에 별도 요청 시 최대 90일까지 연장 가능
• 웹 콘솔 발송내역: 발송 요청 시점 기준 최대 180일 전 데이터까지 조회 가능

API로 연동한 시스템에서 30일이 지난 발송 건의 상태를 확인해야 한다면 웹 콘솔 발송내역에서 180일 범위 안에서 조회할 수 있어요. 다만 API 기반으로 자동화된 조회가 필요한 경우에는 기간 제한이 걸리기 때문에 장기 보관이 필요하면 웹훅이나 폴링으로 수신한 리포트를 자체 데이터베이스에 저장해두는 방법을 권합니다. 웹훅 수신 시점에 결과 데이터를 DB에 적재하는 로직을 추가하면 보관 기간 제한 없이 발송 이력을 관리할 수 있어요. 

비즈고는 통신 3사 직연결 문자중계사이자 카카오톡 비즈메시지 공식 딜러사로, SMS, LMS, MMS, RCS, 카카오톡 알림톡, 브랜드 메시지를 하나의 API로 통합 발송하고 결과까지 통합 관리할 수 있습니다. 발송 결과 확인부터 통계 분석까지의 전체 흐름이 궁금하다면 비즈고 개발자센터에서 API 레퍼런스와 샌드박스를 직접 확인해보세요.