알림톡 개요

알림톡 API 의 인증·스코프와 공통 응답 형식을 정리합니다.

AI 에이전트(Claude Code·Codex·Cursor 등)로 연동할 때는 다음과 같이 요청합니다. 에이전트가 Bootpay MCP 를 설치한 뒤 채널 연결·템플릿 준비·발송·결과 확인을 연동합니다.

https://github.com/bootpay/bootpay-mcp 참조해서 mcp 설치해주고, 알림톡 연동해줘.
MCP 는 새 세션부터 인식됩니다

설치가 끝나면 세션을 새로 시작한 뒤 다시 연동을 요청합니다.

샌드박스가 없습니다

알림톡을 발송하면 실제 메시지가 나가고 요금이 청구됩니다.

인증과 스코프

서버에서 프로젝트의 Client Key·Secret Key 로 Basic Auth 를 보냅니다. 그 키로 발급한 Bearer 토큰도 받지만, 새로 연동할 때는 Basic Auth 를 사용합니다.

전체 권한(supervisor) 키는 모든 알림톡 API 를 호출할 수 있습니다. 범위 키는 아래 스코프가 있어야 합니다.

스코프 API
user:alimtalk_send 단건·벌크 발송, 예약 취소
user:alimtalk_list 채널 목록, 공식 템플릿 검색, 템플릿 목록, 발송내역 목록, 기간 집계
user:alimtalk_detail 채널 상세, 공식 템플릿 상세, 템플릿 상세, 발송 결과 조회, 웹훅 설정 조회, 전송 이력
user:alimtalk_categories 카테고리 조회
user:alimtalk_otp 채널 인증번호 받기
user:alimtalk_create 발신프로필 등록, 템플릿 만들기
user:alimtalk_update 템플릿 수정, 웹훅 저장·테스트·시크릿 재발급
user:alimtalk_delete 연동 해지, 템플릿 삭제
user:alimtalk_variable_examples 변수 예문 사전
user:alimtalk_recommend 공식 템플릿 추천
user:alimtalk_image 템플릿 이미지 올리기
user:alimtalk_export 템플릿 목록 내보내기
user:alimtalk_register 템플릿 등록
user:alimtalk_inspect 검수 요청
user:alimtalk_optout 발송 제외 목록

스코프가 없으면 -47 API_SCOPE_INVALID(HTTP 401), 그 API 의 스코프가 아직 준비되지 않았으면 -50 API_ROLE_NOT_SUPPORT(HTTP 401)입니다.

응답의 시각 형식

알림톡 REST 응답의 시각 필드(created_at·synced_at·delivered_at 등)는 ISO8601 이 아니라 2026-08-27 10:00:00 +0900 형식으로 옵니다. 웹훅 본문은 ISO8601 이므로, 두 형식을 모두 받도록 파서를 구성합니다.

함께 보기