알림톡 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 이므로, 두 형식을 모두 받도록 파서를 구성합니다.



