알림톡
카카오에서 제공하는, 카카오톡 채널을 추가하지 않은 이용자에게도 발송 가능한 정보성 메시지 API
서비스를 이용하시려면 [서비스 콘솔 / 발신번호]에서 발신번호 등록을 수행해야 합니다.
서비스를 이용하시려면 [서비스 콘솔 / 템플릿 관리]에서 신규 등록을 수행해야 합니다.
해당 API는 메세지 발송 결과(WebHook)으로 결과를 전달할 수 있습니다.
알림톡 API
Path variable
Path variable(각 URI 내 중괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.
service_id
서비스 유형 id
at-standard : 스탠다드 알림톡
at-bulk : 대량 알림톡
at-finance : 금융 알림톡
at-verify : 인증 알림톡
Kakao 알림톡 API
POST https://27ep4ci1w0.apigw.ntruss.com/{service_id}/v2/send
Headers
Authorization*
string
사용자ID;secret_key
Content-Type*
string
application/json;charset=utf-8
Request Body
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
메시지내 포함된 가격정보
echo_to_webhook
string
사용자가 API PLEX로부터 webhook을 받을 때 함께 받을 string (최대 256 byte)
failback_data
object
발송 실패 시 대체 발송 데이터
secret_key
string
failback service의 sub_account의 secret_key ( failback 사용 시 필수)
attachment 상세
button
array
N
버튼 속성 데이터 (최대 5개)
name
string
Y
버튼 제목 (112 byte)
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)
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
{
"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
메시지 고유 키
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 응답 코드
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회 발송 최대 수 초과
Last updated
Was this helpful?