알림톡

카카오에서 제공하는, 카카오톡 채널을 추가하지 않은 이용자에게도 발송 가능한 정보성 메시지 API

서비스를 이용하시려면 [서비스 콘솔 / 발신번호]에서 발신번호 등록을 수행해야 합니다.

서비스를 이용하시려면 [서비스 콘솔 / 템플릿 관리]에서 신규 등록을 수행해야 합니다.

모든 알림톡 API의 인코딩은 UTF-8 을 기본으로 합니다.

해당 API는 메세지 발송 결과(WebHook)으로 결과를 전달할 수 있습니다.

알림톡 API

Path variable

Path variable(각 URI 내 중괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.

code	설명
service_id	서비스 유형 id at-standard : 스탠다드 알림톡 at-bulk : 대량 알림톡 at-finance : 금융 알림톡 at-verify : 인증 알림톡

Kakao 알림톡 API

POST https://27ep4ci1w0.apigw.ntruss.com/{service_id}/v2/send

Headers

Name	Type	Description
Authorization*	string	사용자ID;secret_key
Content-Type*	string	application/json;charset=utf-8

Request Body

Name	Type	Description
msg_type*	string	메시지타입 ("AT" | “AI”) AT: 알림톡 (강조유형이 이미지형을 제외한 모든 경우) AI: 이미지 알림톡
msg_data*	array	메시지 발송 상세 데이터 (최대 10건)
sender_number*	string	발신자 전화번호
msg_key*	string	사용자가 관리하는 메시지 고유 키 (null 또는 공백일 경우 자동 부여)
header	string	메시지 상단 표기 제목 (64byte)
msg*	string	전송 메시지 (공백 포함 1000자 제한)
receiver_number*	string	수신자 휴대폰 번호
title	string	알림톡 강조 정보 (200byte)
template_code*	string	알림톡 템플릿 코드 [서비스 콘솔 / 템플릿 관리]에서 등록 필요
sender_key*	string	카카오 비즈메시지 발신 프로필키 [서비스 콘솔 / 발신프로필 등록] 에서 등록 필요
currency_type	string	모먼트 광고 전환 최적화 전용 message 내 포함된 가격/금액/결제금액의 통화단위 (12 byte) KRW, USD, EUR 등 국제 통화 코드 사용
price	number	메시지내 포함된 가격정보
attachment	object	버튼 혹은 이미지 데이터 (attachment 상세 참조)
supplement	object	링크 바로연결 데이터 (supplement 상세 참조)
echo_to_webhook	string	사용자가 API PLEX로부터 webhook을 받을 때 함께 받을 string (최대 256 byte)
failback_data	object	발송 실패 시 대체 발송 데이터
api_unique_id	string	failback service의 고유 id (failback 사용 시 필수) (failback 참조)
secret_key	string	failback service의 sub_account의 secret_key ( failback 사용 시 필수)
	String	failback service의 본문에서 사용할 payload 해당 service의 본문에서 필요로 하는 내용을 기재 (예시 참조)

200: OK 응답 반환 완료

attachment 상세

키	타입	필수	설명
button	array	N	버튼 속성 데이터 (최대 5개)
name	string	Y	버튼 제목 (112 byte)
type	string	Y	버튼 타입 (하단 버튼 타입 참조)
url_pc	string	N	PC환경에서 버튼 클릭 시 이동할 URL
url_mobile	string	N	Mobile 환경에서 버튼 클릭 시 이동할 URL
scheme_android	string	N	Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios	string	N	Mobile ios환경에서 버튼 클릭 시 실행 할 Application custom scheme
chat_extra	string	N	봇 전환 시 전달할 메타정보 (50 byte)
chat_event	string	N	봇 전환 시 연결할 봇 이벤트명 (50 byte)
item_highlight	object	N	아이템 하이라이트
title	string	Y	타이틀 (120 byte, 이미지가 있는 경우 최대 21자)
description	string	Y	부가정보 (76 byte, 이미지가 있는 경우 최대 13자)
item	object	N	아이템 리스트와 아이템 요약 정보
list	array	Y	아이템 리스트
title	string	Y	타이틀 (24 byte)
description	string	Y	가격 정보 (92 byte)
summary	object	N	아이템 요약 정보
title	string	Y	타이틀 (24 byte)
description	string	Y	가격 정보 (56 byte)

supplement 상세

키	타입	필수	설명
quick_reply	array	N	바로 연결 목록
name	string	Y	바로 연결 제목 (54 byte)
type	string	Y	바로 연결 타입 (하단 바로연결 타입 참조)
scheme_android	string	N	Mobile android 환경에서 버튼 클릭 시 실행할 Application custom scheme
scheme_ios	string	N	Mobile ios환경에서 버튼 클릭 시 실행 할 Application custom scheme
url_mobile	string	N	Mobile 환경에서 버튼 클릭 시 이동할 URL
url_pc	string	N	PC환경에서 버튼 클릭 시 이동할 URL
chat_extra	string	N	봇 전환 시 전달할 메타 정보 (200 byte)
chat_event	string	N	봇 전환 시 연결할 봇 이벤트 명 (200 byte)

버튼 타입

버튼타입	속성	타입	필수	설명
WL	url_mobile	string	Y	[웹링크] 바로 연결 클릭 시 이동할 pc/mobile 환경별 web url
	url_pc	string	N	위와 동일
AL	scheme_android	string	Y	[앱링크] scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력 mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme mobile 환경에서 버튼 클릭 시 이동할 url
	scheme_ios	string	Y	위와 동일
	url_mobile	string	Y	위와 동일
	url_pc	string	-	pc 환경에서 버튼 클릭 시 이동할 url
DS	-	-	-	버튼 클릭 시 배송조회 페이지로 이동
BK	-	-	-	해당 버튼 텍스트 전송
MD	-	-	-	해당 버튼 텍스트 + 메시지 본문 전송
BC	-	-	-	상담톡을 이용하는 카카오톡 채널만 이용가능
	chat_extra	string	N	상담톡 전환 시 전달할 메타정보
BT	-	-	-	카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능
	chat_extra	string	N	봇 전환 시 전달할 메타정보
	chat_event	string	N	봇 전환 시 연결할 봇 이벤트명
AC	-	-	-	버튼 클릭 시 카카오톡 채널 추가
P1	-	-	-	이미지 보안 전송 플러그인
P2	-	-	-	개인정보이용 플러그인
P3	-	-	-	원클릭 결제 플러그인 (발송시 oneclick_id 또는 product_id를 필수로 전달해아 함)

바로 연결 타입

버튼타입	속성	타입	필수	설명
WL	url_mobile	string	Y	[웹링크] 바로연결 클릭 시 이동할 pc/mobile 환경별 web url
	url_pc	string	N	위와 동일
AL	scheme_android	string	Y	[앱링크] scheme_ios, scheme_android, url_mobile 중 2가지 필수 입력 mobile android 환경에서 버튼 클릭 시 실행할 application custom scheme mobile ios 환경에서 버튼 클릭 시 실행할 application custom scheme mobile 환경에서 버튼 클릭 시 이동할 url
	scheme_ios	string	Y	위와 동일
	url_mobile	string	Y	위와 동일
	url_pc	string	-	pc 환경에서 버튼 클릭 시 이동할 url
BK	-	-	-	해당 버튼 텍스트 전송
MD	-	-	-	해당 버튼 텍스트 + 메시지 본문 전송
BC	-	-	-	상담톡을 이용하는 카카오톡 채널만 이용가능
	chat_extra	string	N	상담톡 전환 시 전달할 메타정보
BT	-	-	-	카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용가능
	chat_extra	string	N	봇 전환 시 전달할 메타정보
	chat_event	string	N	봇 전환 시 연결할 봇 이벤트명

Request Body 예시

{
    "msg_type": "AT",
    "msg_data": [
        {
            "msg_key": "user_key_1",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "기본형 선택안함 TEST 메세지 입니다.",
            "sender_key": "user_sender_key_001",
            "template_code": "user_template_code_001"
        },
        {
            "msg_key": "",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "title": "강조표기 테스트 제목입니다.",
            "msg": "강조표기 테스트 본문입니다.",
            "sender_key": "user_sender_key_001",
            "template_code": "user_template_code_002",
            "attachment": {
                "button": [
                    {
                        "name": "강조표기",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    }
                ]
            },
            "echo_to_webhook": "echo test",
            "failback_data": {
                "api_unique_id": "sms-standard",
                "secret_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "sender_number": "010xxxxxxxx",
                "receiver_number": "010xxxxxxxx",
                "origin_cid": "0123456789",
                "msg": "failback 본문입니다."
            }
        }
    ]
}

Response Body

응답 http status가 200으로 return되어도 모든 요청의 정상 접수를 의미하지 않습니다.

(발송 건 별 접수 결과 코드(code 필드)로 정상 접수 여부를 확인할 수 있습니다.)

{
    "results": [
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "user_key_1"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "11520199-f289-4681-b0e3-354393a4b041"
        }
    ]
}

키		타입	설명
results		array	메시지 수신 데이터
	msg_key	string	메시지 고유 키
	code	string	접수 결과 코드 (문서 하단 API PLEX 응답 코드 참조)
	desc	string	접수 결과 코드 상세

잘못된 요청 또는 에러

{
    "code": "C400_2",
    "name": "Invalid Parameter",
    "description": "사용자 인증 실패"
}

잘못된 list 내부 요청

{
    "results": [
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "user_key_101"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "0e826855-299f-4328-82a1-d33720dcca23"
        }
    ]
}

API PLEX 응답 코드

code	설명	상세 설명
C100	성공
C400_1	잘못된 데이터 타입	response body의 description 참조
C400_2	잘못된 요청 파라미터	response body의 description 참조
C400_3	필수 파라미터 누락	response body의 description 참조
C404_1	데이터를 찾을 수 없음	response body의 description 참조
C500_1	서버 내부 에러	response body의 description 참조
G110	API UNIQUE ID 예외 (잘못된 URL)
G140	발신번호 예외
G141	수신번호 예외
G142	잘못된 echo_to_webhook	256 byte 초과 또는 type error
G150	여신 부족
G160	1회 발송 최대 수 초과