카카오알림톡 API 사용자가이드 2017.11 Copyright 2015 KTH Corp. All Rights Reserved 1
변경내역 작성일자버전변경사항 2017.05.15 1.0 배포 2017.05.24 1.1 사용예제업데이트 2017.06.15 1.2 템플릿조회 API 업데이트 2017.07.05 1.3 발신번호등록 / 인증 API 업데이트 2017.08.16 1.4 오류코드추가 2017.11.09 1.5 템플릿버튼 5 개추가. 템플릿조회 API, Response 추가 2
[ 목차 ] 1 범위 (Scope)... 4 2 개요... 5 2.1 API 목록... 5 2.2 인증... 5 2.3 공통정의사항... 5 3 API 정의... 6 3.1 카카오알림톡 API... 6 3.2 Report 조회... 8 3.3 template 조회... 9 3.4 발신번호인증 / 등록... 10 3.5 발신번호리스트조회.11 4 Test Summary... 12 5 발신번호등록규칙... 12 6 코드및메시지정의... 13 6.1 Appendix Report Code... 13 3
1 범위 (Scope) 본규격서는 HTTP 프로토콜을기반으로작성되었습니다. 본규격서는 Message 전송에대한규격을정의하고있습니다. 4
2 개요 2.1 API 목록 종류 API 기능 발송 /kko/{v1}/msg/{client_id} 카카오알림톡발송기능 결과조회 /kko/{v1}/report/{client_id} 결과조회기능 템플릿조회발신번호 2.2 인증 /kko/{v1}/template/list/{client_id} /kko/{v1}/sendernumber/save/{client_id} /kko/{v1}/sendernumber/list/{client_id} 등록된템플릿조회 발신번호등록 등록된발신번호리스트조회 구매시발급받은 Key 의코드값을헤더 x-waple-authorization 의값으로설정 x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== 2.3 공통정의사항 공통URL http://api.apistore.co.kr/kko/{v1}/{type}/{client_id} {client_id} 는 API스토어에가입한후해당 API를사용 ( 구매 ) 신청한 ID. {apiversion} : 1 {type}: 은 msg, report 중택1 공통헤더 Content-Type: application/x-www-form-urlencoded; charset=utf-8 x-waple-authorization: MS0xMzY1NjY2MTAyDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZ Q== 5
3 API 정의 3.1 카카오알림톡 API / msg/{client_id} 기본정보 기능 : 카카오알림톡전송기능 방식 : POST 호출 URL: http://api.apistore.co.kr/kko/{v1}/msg/{client_id} 요청파라미터 PHONE String Yes 수신할핸드폰번호 CALLBACK String Yes 발신자전화번호 ( - 제외 / 숫자만입력 ) 01012345678 REQDATE String Yes 발송시간 ( 없을경우즉시발송 ) 20130529171111 (2013-05-29-17:11:11) MSG String Yes 전송할메시지 TEMPLATE_CODE String Yes 카카오알림톡템플릿코드 FAILED_TYPE String No 카카오알림톡전송실패시전송할메시지타입 ( SMS, LMS, N ) URL String No 알림톡버튼타입 URL ( 승인된 template 과불일치시전송실패 ), (2017-11-09 업데이트이전버튼 1 개템플릿호환 ) URL_BUTTON_TXT String No 알림톡버튼타입버튼 TEXT ( 승인된 template 과불일치시전송실패 ), (2017-11-09 업데이트이전버튼 1개템플릿호환 ) FAILED_SUBJECT String No 카카오알림톡전송실패시전송할제목 (SMS 미사용 ) FAILED_MSG String No 카카오알림톡전송실패시전송할 내용 BTN_TYPES String No 카카오알림톡버튼타입 ( 웹링크, 앱링크, 봇키워드, 메시지전달, 배송조회 ), 최대 5개까지추가가능하며타입별콤마로구분함. BTN_TXTS String No 카카오알림톡버튼 TEXT ( BNT_TYPES 입력순으로버튼 TEXT 입력, 승인된템플릿과불일치시전송실패 ), TEXT별콤마로구분함. BTN_URLS1 String No 알림톡버튼타입 URL (2017-11-09 업데이트이후버튼 5개추가시필수 ) 버튼 URL 링크가 2개이상일경우 ( 예제 : BTN_URLS1, BTN_URLS2 6
로파라미터추가 ), 콤마로구분하며웹링크, 앱링크는 URL이필수이며, 기타 ( 배송조회, 봇키 워드, 메시지전달 ) 은 null 값임. FAILED_TYPE No 처리결과코드 RESULT_CODE String 100 : User Error 200 : OK 300 : Parameter Error 301 : failed_type 이 "N" 이아닌경우에실패SMS 제목과내용이없으면에러 302 : 버튼 2개이상발송시에버튼정보가없는템플릿에대한에러 400 : Etc Error 500 : 발신번호사전등록제에의한미등록차단 600 : 충전요금부족 700 : 템플릿코드사전승인제에의한미승인차단 800 : 템플릿코드에러 900 : 프로파일이존재하지않음 No 잔금부족 [ 미발송목록 ] RESULT_MSG String 01012345678 SERIAL_NUM String No 서버에서생성한 request 를식별할수있는 유일한키 사용예제 REQUEST URL http://api.apistore.co.kr/kko/1/msg/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter PHONE=01011112222 CALLBACK=0211112222 MSG= 테스트 TEMPLATE_CODE=A1111 7
BTN_TYPES= 웹링크, 배송조회, 웹링크 BTN_TXTS= 홈페이지, 배송조회, 홈페이지 BTN_URLS1= https://www.apistore.co.kr,,https://www.apistore.co.kr ( 버튼링크가 1 개일경우 ) FAILED_SUBJECT= 테스트 FAILED_MSG= 테스트 RESONSE 200 Access-Control-Allow-Origin Content-Type: application/json { result_code : 200, cmid : 2017052411064978 } 3.2 Report 조회 /report/{client_id} 기본정보 기능 : report 조회기능 방식 : GET 호출 URL: http://api.apistore.co.kr/kko/{v1}/report/{client_id} 요청파라미터 CMID String No 서버에서생성한 request를식별할수있는유일한키 반환값 STATUS String No 발송상태 1: 발송대기 2: 전송완료 3: 결과수신완료 PHONE String No 수신한핸드폰번호 CALLBACK String No 발신자전화번호 RSLT String Yes 카카오알림톡결과수신 (Appendix 참조 ) MSG_RSLT String Yes 카카오알림톡실패시메시지결과수신 (Appendix 참조 ) 사용예제 REQUEST URL http://api.apistore.co.kr/kko/1/report/{client_id}?cmid=2017052411064978 GET Content-Type: application/x-www-form-urlencoded; charset=utf-8 8
Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== RESONSE 200 Access-Control-Allow-Origin: * Content-Type: application/json {"PHONE":"01011112222","RSLT":"0","CALLBACK":"0232894122","MSG_RSLT":"00"," STATUS":"3","CMID":"2017052411064978"} 3.3 Template 조회 /template/list/{client_id} 기본정보 기능 : template 조회기능 방식 : GET 호출 URL: http://api.apistore.co.kr/kko/{v1}/template/list/{client_id} 요청파라미터 TEMPLATE_CO Yes 템플릿코드 입력안할경우전체리스트 String DE 반환 검수상태 입력안할경우전체리스트반 환 STATUS String Yes 등록 (1) / 검수요청 (2) 승인 (3) / 반려 (4) / 승인중단 (5) 반환값 TEMPLATE_CO DE String No 템플릿코드 TEMPLATE_NA ME String No 템플릿명 TEMPLATE_MS G String No 템플릿내용 STATUS String No 등록상태 ( 등록, 검수요청, 승인, 반려 ) BTNLIST String No 버튼리스트 TEMPLATE_BTN _URL String No 버튼 URL 9
TEMPLATE_BTN _NAME TEMPLATE_BTN _TYPE 사용예제 REQUEST String No 버튼이름 String No 버튼타입 URL http://api.apistore.co.kr/kko/1/template/list/{client_id} GET Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter TEMPLATE_CODE=api123&status=1 RESONSE 200 Access-Control-Allow-Origin: * Content-Type: application/json {"template_code : test1","template_name":"test1","template_msg":" 메시지내용 ","status": " 등록 ","btnlist": "template_btn_url2": null,"template_btn_name": " 홈페이지 ",template_btn_url":"https://www.apistore.co.kr","template_btn_type : 웹링크 } 3.4 발신번호인증 / 등록 /sendnumber/save/{client_id} 기능 : 발신번호인증 / 등록 API (apiversion = 2) 기본정보 인증방법 : SMS, VMS 중 1 개선택 방식 : POST 호출 URL: http://api.apistore.co.kr/kko/{apiversion}/sendnumber/save/{client_id} 요청파라미터 sendnumber String No 발신번호 ( - 제외 ) * 발신번호등록규칙참조 10
comment String No 코멘트 (200자) pintype String Yes 인증방법 (SMS. VMS 중 1개선택 ) pincode String Yes 인증번호 (SMS 인증번호 (6자리), VMS인증번호 (2자리)) 반환값 result_code String No 처리결과코드 200 : 성공 300 : 파라메터에러 400 : 인증업데이트중에러 500 : 이미등록된번호 600 : 일치하지않는인증번호 700 : 핀코드인증시간만료 (3분이후만료이며재등록요청해야함.) sendnumber String No 등록한번호 사용예제 REQUEST < 요청 > URL http://api.apistore.co.kr/kko/2/sendnumber/save/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter sendnumber=0232894122&comment= 케이티하이텔대표번호 &pintype=sms 또는 VMS < 인증 > URL http://api.apistore.co.kr/kko/2/sendnumber/save/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter sendnumber=0232894122&comment= 케이티하이텔대표번호 &pintype=sms&pincode=123456(6자리) (pintype=vms 일경우 pincode=12(2자리 )) 11
RESONSE [ 요청 ] 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200","sendnumber":"0232894122"} [ 인증 ] 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200","sendnumber":"0232894122"} 3.5 발신번호리스트조회 /sendnumber/list/{client_id} 기본정보 기능 : list 조회기능 방식 : GET 호출 URL: http://api.apistore.co.kr/kko/{v1}/sendnumber/list/{client_id} 요청파라미터 sendnumber String Yes 발신번호 ( - 제외 ) 입력안할경우전체리스트반환 반환값 result_code String No 처리결과코드 100 : User Error 200 : OK 300 : Parameter Error 400 : Etc Error USE_YN : Y 값은정상등록된번호. N 값은요청후미인증번호. client_id String No API스토어계정 comment String No 등록내용 sendnumber String No 등록한번호 사용예제 12
REQUEST URL http://api.apistore.co.kr/kko/1/sendnumber/list/{client_id} GET Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== RESONSE 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200", numberlist": [{ client_id : {client_id}, comment : null, sendnumber":"0232892888"}, { client_id : {client_id}, comment : null, sendnumber":"0212345678"} 4 Test Summary TEST는실제로메시지전송은되지않으며, 요청한데이터에대한처리결과만확인가능. URL을제외한파라미터및리턴데이터는위와동일. URL POST 카카오알림톡 http://api.apistore.co.kr/kko/1/msg_test/{client_id} 5 발신번호등록규칙 - 기본 : 8자리 ~ 11자리발신번호 - 유선전화번호 : 지역번호를포함 - 이동통신전화번호 - 대표전화번호 : 15xx, 16xx, 18xx( 번호앞에지역번호사용금지 ) 6 코드및메시지정의 6.1 Appendix Report Code 구분 결과코드 코드 Description 0 SUCCESS 성공 1 INVALID_SENDER_KEY 발신프로필키가유효하지않음 RSLT 2 NOT_CONNECTED_USER 서버와연결되어있지않은사용자 5 ACK_TIMEOUT 메시지발송후수신여부불투명 6 RESPONSE_HISTORY_NOTFOUND 메시지전송결과를찾을수없음 13
8 NO_SEND_AVALIABLE_STATUS 메시지를전송할수없는상태 9 NO_VISIT_USER 최근카카오톡을미사용자 a E_INSUFFICIENT 건수부족 b E_REJECT_ITER 전송권한없음 c E_DUP_KEY 중복된키접수차단 d E_DUP_PHONE 중복된수신번호접수차단 e E_SERVER_ERROR 서버내부에러 f E_FORMAT_ERR 메시지포맷에러 k MESSAGE_NOT_FOUND 메시지가존재하지않음 o E_TIMEOUT_AGENT TIME OUT 처리 (Agent 내부 ) p E_DUPLICATE_PHONE_MSG 메시지본문중복차단 (Agent 내부 ) t MESSAGE_EMPTY 메시지가비어있음 A NO_USER 카카오톡을미사용자 B USER_BLOCKED_DELIVERY 알림톡차단을선택한사용자 C SERIAL_NUMBER_DUPLICATED 메시지일련번호중복 D DUPLICATED 5 초이내메시지중복발송 E UNSUPPORTED_CLIENT 미지원클라이언트버전 F ETC 기타오류 H FAILED_TO_SEND_MESSAGE 카카오시스템오류 I INVALID_PHONE_NUMBER 전화번호오류 J SAFETY_PHONE_NUMBER 050 안심번호발송불가 L MESSAGE_LENGTH_OVER_LIMIT 메시지길이제한오류 M TEMPLATE_NOT_FOUND 템플릿을찾을수없음 S SPAM 발신번호검증오류 U NO_MATCHED_TEMPLATE 메시지가템플릿과일치하지않음 V FAILED_TO_MATCH_TEMPLATE 메시지가템플릿과비교실패 0 E_OK 성공 MSG_RSLT 1 E_TIMEOUT 전송시간초과 2 E_INVALID_PHONE 잘못된전화번호 / 비가입자 5 E_NOT_ACK 통신사결과미수신 8 E_PHONE_BUSY 단말기 BUSY 9 E_SHADOW_REGION 음영지역 a E_INSUFFICIENT 건수부족 b E_REJECT_ITER 전송권한없음 c E_DUP_KEY 중복된키접수차단 d E_DUP_PHONE 중복된수신번호접수차단 e E_SERVER_ERROR 서버내부에러 o E_TIMEOUT_AGENT TIME OUT 처리 (Agent 내부 ) p E_DUPLICATE_PHONE_MSG 메시지본문중복차단 (Agent 내부 ) q E_DUPLICATE_KEY 메시지중복키체크 (Agent 내부 ) t E_TOGETHER_COUNT 잘못된동보전송수신번호리스트 14
카운트 (Agent 내부 ) A E_MSG_FULL 단말기메시지저장개수초과 B E_SERVICE_STOP 단말기일시서비스정지 C E_ETC_PHONE 기타단말기문제 D E_DENY 착신거절 E E_POWER_OFF 전원꺼짐 F E_ETC 기타 G E_INNER_FORMAT_ERR 내부포맷에러 H E_TELCO_FORMAT_ERR 통신사포맷에러 I E_UNACCEPTED_PHONE SMS/MMS 서비스불가단말기 J E_MSG_FAIL 착신측호불가상태 K E_TELCO_MSG_DEL 통신사에서메시지삭제처리 L E_TELCO_QUE_FULL 통신사메시지처리불가상태 M E_WIRELESS_FAIL 무선망단전송실패 S E_SPAM 스팸 V E_CONTENTS_SIZE_ERR 컨텐츠사이즈초과 U E_CONTENTS_ERR 잘못된컨텐츠 15