주문 확인, 인증번호, 배송 안내, 프로모션 알림. 고객에게 메시지를 보내는 시스템을 직접 구축하려면 메시지 API를 연동해야 합니다. 문자(SMS, LMS, MMS) 발송만 필요한 초기에는 문자 API 하나만 붙이면 되지만 서비스가 커지면서 카카오톡 알림톡을 추가하고 RCS까지 확장하는 경우가 많죠.
이때 업체에 따라 지원하는 채널 범위가 다를 수 있습니다. 문자와 알림톡은 되는데 RCS는 지원하지 않는다면 채널을 확장할 때마다 새 업체를 찾고 별도 연동을 해야 하는 상황이 생겨요. 이 가이드에서는 연동 전에 알아두면 설계가 빨라지는 메시지 API 연동의 전체 흐름과 핵심 개념을 정리합니다.
🔄 메시지 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를 확인하고 샌드박스에서 테스트 발송을 시작해보세요.
