메시지 발송 결과 확인하는 방법, 조회 방식부터 로그 관리까지

📡 발송 결과를 수신하는 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 레퍼런스와 샌드박스를 직접 확인해보세요.