KAKAO Messaging Service REST API Specification V0.2.2 Last Modified: 2018.08. 1
변경이력 버전 일자 내용 작성자 0.1.0 2017.11.13 최초작성 한은경 0.1.1 2017.12.08 초안수정및에러코드추가 한은경 0.1.2 2018.01.08 리포트연동 API 변경, 메일주소추가 송준민 0.1.3 2018.01.16 EUC-KR 설명수정 송준민 리포트수신시간포맷변경 (yyyy-mm-dd HH:mm:ss) 0.1.4 2018.01.17 user_key 필드설명변경 송준민 템플릿관련리포트코드추가 0.1.5 2018.01.24 mt_failover 필드 optional로변경 송재혁 API Response 코드추가 0.1.6 2018.02.02 Senderid 필드 ( 발신번호 ) optional로변경 송준민 content 기준길이변경 failover_content 추가 (failover 시 MT 메시지내용지정 ) 0.1.7 2018.02.23 발송샘플수정 송준민 0.1.8 2018.04.17 챗버블샘플추가 송준민 messageid size 변경 (40) 0.1.9 2018.05.25 카카오 v2 API 적용 송준민 > 리포트코드추가 (1021,1022,1023,1024,1025,2006) 0.2.0 삭제 송준민 0.2.1 2018.08.16 메시지전송도메인및리포트발송 IP 변경 송준민 A201 접수코드추가 ( json 형식오류 ) Timeout 필드및설명추가 ad_flag 설명변경 0.2.2 2018.08.24 친구톡일경우 push 만허용 송준민 2 / 20
목차 1. 개요... 4 2. 선결조건... 4 3. 개발환경구성... 4 4. 전문규격... 4 4.1. API 리스트... 5 4.1.1. API 설명... 5 4.1.2. API URL 정보... 5 4.2. API 상세... 5 4.2.1. 메시지전송요청 API... 5 4.2.2. 리포트 API(PUSH)... 11 5. 응답및결과코드...14 5.1. API RESPONSE 코드... 14 5.2. 공통내부실패결과코드... 15 5.3. KAKAO 전송결과코드... 15 5.4. MT FAILOVER 접수실패코드... 17 5.5. MT FAILOVER 코드... 17 6. 부록...18 6.1. 메시지타입및 TIMEOUT 설정... 18 6.2. 버튼타입... 18 6.3. 챗버블샘플... 19 7. 발송테스트...20 8. 문의...20 3 / 20
1. 개요 인포뱅크에서제공하는 REST API를통해, JSON형식으로메시지전송규격입니다. 본규격을이용하여카카오비즈메시지서비스중알림톡, 친구톡 1 을이용할수있습니다. 본서비스를이용하기위해서인포뱅크담당자로부터접속정보와발송계정, 권한을제공받아야합니다. 2. 선결조건 메시지발송주체인플러스친구 2 를카카오메시지센터에등록후, 발신프로필키 (Sender Key) 을발급, 해당키를메시지에같이전송해야합니다.. 알림톡의경우, 메시지발송을위해, 템플릿과템플릿코드를 카카오메시지센터에등록해야합니다. 3. 개발환경구성 REST API는 HTTPS 요청을보낼수있는환경이라면어디에서든이용할수있습니다. 모바일 /PC 웹환경에서 Javascript를활용다양한환경의웹서버에서의활용 (Java, Ruby, Python 등 ) ios, Android 등다양한모바일환경에서활용 4. 전문규격 HTTPS METHOD - 전송요청을위해 HTTPS POST 방식을제공하며전송응답은 JSON 방식을사용합니다. 1 알림톡 : 주문, 예약, 배송, 결제내역등정보성메시지전송친구톡 : 카카오플러스친구와친구관계인경우에한하여마케팅메시지전송 2 카카오계정을기반으로한비즈니스용카카오톡아이디. 플러스친구홈페이지 (https://center-pf.kakao.com/login) 통해개설 4 / 20
ENCODING - UTF-8 encoding을기본으로제공합니다. TIMEZONE - 본 API에대한기준시간은한국표준시 KST(UTC+9) 를사용합니다. 4.1. API 리스트 4.1.1. API 설명 메시지전송 API - 메시지발송을요청하는 API 입니다. 리포트 API - 메시지전송결과를확인할수있는 API 입니다. * 리포트를수신하기위해서는인포뱅크에서제공하는서버 IP 에대한접근을허용해야합니다. 결과송신서버 IP 정보 : 211.233.70.224, 211.233.70.225 4.1.2. API URL 정보 메시지전송 API 리포트 API (PUSH) https://msggw.supersms.co:9443/v1/send/kko 인포뱅크에등록한리포트 URL 정보 4.2. API 상세 다국어를지원위해 UTF-8 인코딩을사용합니다. 4.2.1. 메시지전송요청 API 발급받은 ID/Password을 HTTP Header에등록하여사용해야합니다. X-IB-Client-Id : 인포뱅크를통해발급받은 ID X-IB-Client-Passwd : 인포뱅크를통해발급받은 Password 5 / 20
수신번호형식은국제표준 3 을따릅니다. 예 ) 8210123456478 MT Failover(mt_failover) 를선택하면, 카카오메시지발송실패시자동으로길이에따라 SMS/LMS 4 로메시지전송됩니다. (* 단, MT Failover 권한은, 담당영업매니저에게권한을획득시사용가능합니다.) EUC-KR에서제공하지않는글자가포함될경우국내메시지발송이실패할수있습니다. [Request] path : /v1/send/kko method : POST header - X-IB-Client-Id : ID - X-IB-Client-Passwd : Password - Content-Type : application/json;charset=utf-8 - Accept : application/json 기본 body Name Type 필수 Desc msg_type Varchar(32) Y 메시지타입 (FT: 친구톡, AL: 알림톡 ) mt_failover Varchar(1) N 문자로 Failover 여부 (Y/N) msg_data Json Y 메시지발송필수데이터 msg_attr Json Y 메시지타입별속성데이터알림톡 / 친구톡메시지타입별따라, 메시지발송시필요한데이터가상이 Request Sample (curl) curl -X POST -H 'X-IB-Client-Id: < 발급받은ID>' -H 'X-IB-Client-Passwd: < 발급받은 PASSWORD>' -H 'Content-type: application/json' -d ' "msg_type": "AL", "mt_failover": "N", "msg_data": "senderid": "15881234", "to": "821012345678", "content": "TEST MESSAGE" 3 [ 국가번호 ][ 수신번호 ] 예 ) 821012341234 4 SMS: 최대 90byte 까지발송되는단문메시지 LMS: 최대 2000byte 까지발송가능한첨부파일없는장문문자메시지 6 / 20
, "msg_attr": "sender_key": "< 플러스친구발송키 >", "template_code" : "1234", "response_method": "push", "ad_flag": "Y", "attachment": "button": [ "name": "BUTTON1", "type": "WL", "url_pc": "http://www.kakao.com", "url_mobile": "http://www.kakao.com", "name": " BUTTON2", "type": "MD", "name": " BUTTON3", "type": "AL", "scheme_ios": "daumapps://open", "scheme_android": "daumapps://open" ], "image": "img_url": "http://mudkage.kakao.com/dn/6q8v8/btqg8nla99s/qft1cahh7eqa44hrysdk70/img_l.png", "img_link": "http://bizmessage.kakao.com/" ' 'https://msg.supersms.co:9443/v1/send/kko' msg_data Json body 7 / 20
메시지발송에필수로필요한, 발신자, 수신자, 메시지내용이포함되어있는 JSON Name Type 필수 Desc senderid Varchar(16) N MT Failover 사용시발신자번호 * MT Failover 발송시필수사항 to Varchar(16) Y 수신자번호국제전화번호표준적용발송 (i.e, 82101231234) content Varchar(1000) Y 메시지내용 failover_content Varchar(2000) N MT Failover 사용시별도메시지내용지정미입력시 content 내용으로 MT 발송 msg_data Sample (JSON) "msg_data": "senderid": "15881234", "to": "821012345678", "content": "( 광고 ) 테스트예시 " msg_attr Json body 메시지타입별, 셋팅이필요한메시지데이터속성 JSON Name Type 필수 Desc sender_key Varchar(40) Y 플러스친구발송키 user_key Varchar(30) N 옐로아이디봇을이용해받은옐로아이디사용자식별키 * 친구톡연동시사용 response_method Varchar(10) Y 요청응답수신방식 (push, realtime) * 부록참고 * 친구톡일경우 push 만허용 timeout int N Timeout * 부록참고 ad_flag Varchar(1) - 최종고객광고거부사용여부 (Y/N) * 친구톡발송시선택사항 template_code Varchar(30) - 템플릿코드실제발송할메시지유형으로등록된템플릿코드 * 알림톡발송시필수사항 attachment Json N 버튼, 이미지첨부시속성데이터 8 / 20
attachment Json body 메시지에버튼, 이미지삽입시속성값지정 JSON Name Type 필수 Desc button Json N 버튼속성데이터버튼이름, 타입, 버튼클릭시연결 URL 등지정 image Json N 친구톡이미지속성데이터친구톡이미지 URL, 이미지등록링크지정 button Json body 버튼타입에따라, 속성값의필수 / 속성값이달라지므로, 반드시 * 부록참고필요 웹링크 / 앱링크 / 봇키워드 / 메시지전달 / 배송조회 5가지버튼타입제공하며, 배송조회타입은알림톡만이용가능합니다. - 버튼은최대 5개까지첨부및여러가지타입으로혼합사용가능 Name Type 필수 Desc name Varchar Y 발신자번호최대 28 자까지입력가능 (14 자권장 ) type Varchar(2) Y 버튼타입 (WL, AL, BK, MD, DS) * 부록참고 url_pc Varchar PC 환경에서버튼클릭시이동할 URL url_mobile Varchar - Mobile 환경에서버튼클릭시이동할 URL scheme_ios Varchar - Mobile ios 환경에서버튼클릭시실행할, Application custom scheme scheme_android Varchar - Mobile android 환경에서버튼클릭시실행할 Application custom scheme button Sample (JSON) "button": [ "name": " 미리주문하기 ", "type": "WL", "url_pc": "http://www.kakao.com", "url_mobile": "http://www.kakao.com", 9 / 20
], "name": " 상담원연결하기 ", "type": "MD" image Json body 이미지는친구톡에서만이용가능하며 1개의이미지만등록사용가능 이미지타입에따라, 속성값의필수 / 속성값이달라지므로, 반드시 * 부록참고필요 Name Type 필수 Desc img_url Varchar Y 발신자번호 img_link Varchar Y 이미지클릭시이동할 URL 미설정시카카오톡내이미지뷰어사용 url_pc Varchar PC 환경에서버튼클릭시이동할 URL url_mobile Varchar - Mobile 환경에서버튼클릭시이동할 URL image Sample (JSON) "image": "img_url": "http://mudkage.kakao.com/dn/6q8v8/btqg8nla99s/qft1cahh7eqa44hrysdk70/img_l.png", "img_link": "http://bizmessage.kakao.com/" [Response] header - HTTP 응답코드를통해, 메시지정상접수여부를우선확인할수있다. i.e) HTTP/1.1 200 OK : 정상접수 HTTP/1.1 401 : 권한없음 - Content-Type: application/json; charset=utf-8 body Name Type 필수 Desc 10 / 20
messageid Varchar(40) Y 메시지키 to Varchar(16) N 수신번호 status Char(4) Y 처리상태 text Varchar(255) N 접수결과메시지 - 처리결과에따라수신번호가포함되지않을수있습니다. 성공일경우, Response Sample (JSON) < ------- HEADER ------- > HTTP/1.1 200 OK date: Thu, 26 Oct 2017 10:43:55 GMT transfer-encoding: chunked content-type: application/json;charset=utf-8 < -------- BODY ---------> "messageid": "e7fd2b6124aa4630b5592463595c1e5c", "to": "821012345678", "status": "A000", "text": "Success" 실패일경우, Response Sample (JSON) < ------- HEADER ------- > HTTP/1.1 400 date: Thu, 26 Oct 2017 10:43:55 GMT transfer-encoding: chunked content-type: application/json;charset=utf-8 < -------- BODY ---------> "messageid": "e3095a37b25243a29ab8a5dd3b225f62", "to": "821012345678", "status": "A102", "text": "senderkey is null or Empty " 4.2.2. 리포트 API(PUSH) 11 / 20
PUSH 방식 - 메시지전송요청을하고, 전송결과를비동기로응답받는방식입니다. 리포트수신을위해인포뱅크에서제공하는서버 IP에대한접근을허용해야하며리포트를수신할고객사측 IP/PORT 에대한정보는영업담당자에게접수해야합니다. 수신받을서버네트워크구간에방화벽허용이필요합니다. 리포트는아래와같이총 3가지로분류됩니다. KAKAO 리포트카카오메시지최종고객수신결과 MT 발송접수실패 MT Failover 전환발송시접수실패사유 MT 발송결과리포트 MT Failover 발송후, 최종고객수신결과 전송 API를통해발송한메시지에대해 messageid기준으로사용자가제공한접속정보로결과값을전달합니다. 인포뱅크가등록된 URL을통해하단규격과같은 Request를보냅니다. 리포트정보를수신하면하단규격과같은 Response를주어야합니다. 리포트전송실패시, 재전송없이해당리포트는전송실패처리합니다. 1. KAKAO 리포트, MT 발송접수실패 API [Request] method : POST path : 인포뱅크에등록한 URL 정보 content-type: application/json;charset=utf-8 X-MessageType: [AL/FT/MT] : 리포트메시지타입, 알림톡, 친구톡, MT접수실패유형으로구분 URL parameter Name Type 필수 Desc messageid Varchar(40) Y 메시지아이디 resultcode Char(4) Y 발송결과코드 errortext Varchar(255) N 에러내용 reporttime datetime Y 리포트수신시간 (yyyy-mm-dd HH:mm:ss) Request Sample POST http://[client URL] :[Client Port] Host: [Client URL]:[Client Port] X-MessageType: [AL/FT/MT] content-type: application/json;charset=utf-8 12 / 20
"messageid": "e7fd2b6124aa4630b5592463595c1e5c", "resultcode": "0000", "reporttime": "2018-01-16 15:22:56", "errortext": null [Response] header - Content-Type: application/json; charset=utf-8 body Name Type 필수 Desc messageid Varchar(40) Y 메시지아이디 Response Sample (JSON) "messageid":"e7fd2b6124aa4630b5592463595c1e5c", 2. MT 발송결과리포트 API http://www.ibizplus.co.kr/technical/datacenter/rest#api02 리포트 API(PUSH) 참고 URL parameter 재정의 ( 나머지값은링크참고 ) Name Type 필수 Desc ref Varchar(200) Y 카카오메시지로최초접수한 messageid [ 리포트 API 연동가이드 ] - KAKAO 리포트및 MT 접수실패리포트는 POST 방식으로수신 URL 을구성합니다. - 리포트는 Header:X-MessageType 으로구분할수있습니다. - MT 발송결과리포트는 GET 방식으로수신 URL 을구성합니다. - MT 발송결과리포트의경우 ref 값에접수된 messageid 값이저장됩니다. 13 / 20
5. 응답및결과코드 API Response 코드 : REQUEST 후, 바로응답으로수신하는코드 KAKAO 결과코드 : 알림톡, 친구톡발송시, 응답받는코드. MT Failover 결과코드 : MT Failover 적용시, 수신받을수있는접수실패, 리포트응답코드 5.1. API Response 코드 구분 Http Status Error Error Text Desc 성공 200 A000 Success 성공 401 A001 Unauthorized client ID 인가되지않는계정 인증 401 A002 Not Existing client ID 존재하지않는계정 401 A003 Not allow MT failover MT Failover 불가한계정 404 - No message available 잘못된 URI 접근 400 A100 response_method is null or Empty response_method 값이 null 400 A101 response_method is wrong 잘못된 response_method 값 400 A102 400 A103 400 A104 senderkey is null or Empty or exceeded max senderkey-length Button's mandotory[name/type] is not included Button's mandotory is Empty or exceeded max button_name-length senderkey 가빈값 버튼의필수이름, 타입누락 버튼누락 400 A105 Button Type is not inappropriate 잘못된버튼타입 형식오류 400 A106 WL Button Type must have url_mobile WL 버튼타입에필요한 url_mobile 누락 400 A107 AL Button Type must have Scheme_android AL 버튼타입에필요한 Scheme_android 누락 400 A108 AL Button Type must have Scheme_ios AL 버튼타입에필요한 Scheme_ios 누락 400 A109 senderid is null or Empty 수신자누락 400 A110 To Field is null or Empty 송신자누락 400 A111 content is null or Empty 빈메시지내용 400 A112 Image must have img_url 이미지사용시 img_url 누락 400 A113 msgtype is Empty msgtype 누락 400 A114 msgtype is wrong 잘못된 MsgType 14 / 20
400 A115 template_code is null or empty or exceeded max template_code-length 템플릿코드누락 400 A116 Exceeded max content-length 최대메시지길이초과 400 A117 Exceeded max senderid length 최대송신자번호길이초과 400 A118 Exceeded max To length 최대수신자번호길이초과 400 A119 exceeded max ad_flag-length ad_flag 길이초과 400 A120 exceeded max user_key-length user_key 길이초과 400 A121 mt_failover is invalid mt_failover 값오류 400 A122 exceeded max mt failover content-length MT Failover 메시지길이제한 오류 400 A201 invalid json format Json 형식오류 여신 401 A200 Exceeded the maximum number of messages that can be sent 발송가능건수초과 기타 500 A999 Unknown error 알려지지않은에러 5.2. 공통내부실패결과코드 - 아래코드는내부실패에의한결과코드로공통코드입니다. 발생구분 Status Error text Desc 공통 T900 알수없는에러코드 알수없는에러코드수신 공통 T997 내부파싱에러 시스템내부원인으로파싱에러 공통 T998 내부발송취소 시스템내부원인으로발송취소 공통 T999 내부발송실패 시스템내부원인으로발송실패 공통 T910 내부 FAILOVER 처리 실패 내부 FAILOVER 처리실패 5.3. KAKAO 전송결과코드 Status Error text Desc 0000 정상발송 1001 NoJsonBody Request Body 가 Json 형식이아님 1002 InvalidHubPartnerKey 파트너키가유효하지않음 1003 InvalidSenderKey 발신프로필키가유효하지않음 1004 NoValueJsonElement Request BODY(Json) 에서 name 을찾을수없음 1005 SenderNotFound 발신프로필을찾을수없음 15 / 20
1006 DeletedSender 삭제된발신프로필 1007 StoppedSender 차단상태의발신프로필 1011 ContractNotFound 계약정보를찾을수없음 1012 InvalidUserKeyException 잘못된형식의유저키요청 1021 BlockedProfile 1022 DeactivatedProfile 1023 DeletedProfile 1024 DeletingProfile 1025 SpammedProfile 차단상태의플러스친구 ( 플러스친구운영툴에서확인 ) 닫힘상태의플러스친구 ( 플러스친구운영툴에서확인 ) 삭제된플러스친구 ( 플러스친구운영툴에서확인 ) 삭제대기상태의플러스친구 ( 플러스친구운영툴에서확인 ) 메시지차단상태의플러스친구 ( 플러스친구운영툴에서확인 ) 1030 InvalidParameterException 잘못된파라메터요청 2003 FailedToSendMessageByNoFriendshipException 메시지전송실패 ( 테스트서버에서친구관계가아닌경우 ) 2004 FailedToMatchTemplateException 템플릿일치확인시오류발생 ( 카카오내부오류 ) 2006 FailedToMatchSerialNumberPrefixPattern 시리얼넘버형식불일치 3000 UnexceptedExcetpion 예기치않은오류발생 3005 AckTimeoutException 메시지를발송했으나, 수신확인안됨 ( 성공불확실 ) 3006 FailedToSendMessageException 카카오내부시스템오류로메시지전송실패 3008 InvalidPhoneNumberException 전화번호오류 3010 JsonParsseExcetpion Json 파싱오류 3011 MessageNotFoundException 메시지가존재하지않음 3012 SerialNumberDuplicatedException 메시지일련번호가중복됨 - 메시지일련번호는고유의값이부여되어야함 3013 MessageEmptyException 빈메시지 3014 MessageLengthOverLimitException 메시지길이제한오류 ( 텍스트타입 1000 자초과, 이미지타입 400 자초과 ) 3015 TemplateNotFoundException 템플릿을찾을수없음 3016 NoMatchedTemplateException 메시지내용이템플릿과일치하지않음 3018 NoSendAvailableException 메시지를전송할수없음 3019 MessageNotSentException 메시지가발송되지않은상태 3020 SeenInfoNotFoundException 메시지확인정보를찾을수없음 16 / 20
메시지발송가능한시간이아님 3022 NoSendAvailableTimeException ( 친구톡 / 마케팅메시지는 08 시 ~ 20 시까지발송 가능 ) 3024 MessageInvaildImageException 메시지에포함된이미지를전송할수없음 4000 ResponseHistoryNotFoundException 메시지전송결과를찾을수없음 4001 UnKnownMessageStatusError 알수없는메시지상태 9998 현재서비스를제공하고있지않습니다. 시스템에문제가발생하여담당자가확인하고있는 경우 9999 시스템에알수없는문제발생, 담당자확인중시스템에문제가발생하여. 담당자확인중 5.4. MT Failover 접수실패코드 http://www.ibizplus.co.kr/technical/datacenter/rest#api03 API Response 결과코드및 API Response 수신 번호별결과코드참고 5.5. MT Failover 코드 http://www.ibizplus.co.kr/technical/datacenter/rest#api03 Report 전송결과코드참고 17 / 20
6. 부록 6.1. 메시지타입및 Timeout 설정 타입 Push Realtime 설명서버에연결되어있는카카오톡사용자, 최근 7일간카카오톡사용한사용자즉, 활성사용자에게메시지전송처리하는방식, Timeout 값은설정하지않음메시지전송요청시결과를실시간확인하는방식 Timeout 내전송이되지않으면실패처리되며, Timeout 값은 5~30초 ( 기본값 : 10초 ) 6.2. 버튼타입 버튼은최대 5개까지첨부가능, 배송조회 / 웹링크 / 앱링크 / 봇키워드 / 메시지전달기능버튼 타입제공 5개버튼타입은믹스해서사용가능 버튼명은 14자를권장하며최대 28자까지입력가능 버튼 2개이하일경우, 버튼명은가운데정렬되며, 3개이상일경우좌측정렬 버튼 버튼기능 속성 타입 필수 설명 타입 WL 웹링크 url_mobile Varchar Y Mobile 환경에서버튼클릭시이동할 URL url_pc Varchar N PC환경에서버튼클릭시이동할 URL AL 앱링크 scheme_ios Varchar Y Mobile ios환경에서버튼클릭시실행할, Application custom scheme scheme_android Varchar Y Mobile android 환경에서버튼클릭시실행할 Application custom scheme BK 봇키워드 - 해당버튼텍스트전송 MD 메시지 전달 - 해당버튼텍스트 + 메시지본문전송 DS 배송조회 - 버튼클릭시배송조회페이지로이동 * 알림톡만이용가능 18 / 20
6.3. 챗버블샘플 msg_attr Sample (JSON) "msg_attr": "attachment": "image": "img_link":"http://www.ibizplus.co.kr/", "img_url":"http://mudkage.kakao.com/dn/6q8v8/btqg8nla99s/qft1cahh7eqa44hrysdk70/img_l.png", "button":[ "type":"wl", "name":" 미리주문하기 ", "url_mobile":"http://www.kakao.com", "url_pc":"http://www.kakao.com", "type":"md", "name":" 상담원연결하기 ", "type":"al", "name":" 방송알림설정보기 ", "scheme_android":"daumapps://open", "scheme_ios":"daumapps://open" ] 수신화면 19 / 20
7. 발송테스트 테스트를위하여, 발신프로필과친구관계인경우에만, 알림톡테스트메시지를발송할수있습니다. 8. 문의 본문서와관련된기술문의는아래메일주소로연락주시면됩니다. Email : ottmsg@infobank.net 20 / 20