카카오알림톡 - kth-apistore/docs GitHub Wiki
카카오 알림톡 API 사용자 가이드
1 범위(Scope)
- 본 규격서는 HTTP 프로토콜을 기반으로 작성되었습니다.
- 본 규격서는 Message 전송에 대한 규격을 정의하고 있습니다.
2 개요
2.1 API 목록
| 종류 | API | 기능 |
|---|---|---|
| 발송 | /kko/{v1}/msg/{client_id} | 카카오 알림톡 발송 기능 |
| 결과조회 | /kko/{v1}/report/{client_id} | 결과 조회 기능 |
| 템플릿 조회 | /kko/{v1}/template/list/{client_id} | 등록된 템플릿 조회 |
| 발신번호 | /kko/{v1}/sendnumber/save/{client_id} | 발신번호 등록 |
| 발신번호 | /kko/{v1}/sendnumber/list/{client_id} | 등록된 발신번호 리스트 조회 |
2.2 인증
- 구매 시 발급받은 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: MS0xMzY1NjY2MTAyDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ==
3 API 정의
3.1 카카오 알림톡 API
기본정보 / msg/{client_id} * 기능: 카카오 알림톡 전송 기능
- 방식: POST
- 호출 URL: http://api.apistore.co.kr/kko/{v1}/msg/{client_id} 요청 파라미터
| Element | Type | Optional | Description |
|---|---|---|---|
| PHONE | String | No | 수신할 핸드폰번호 |
| CALLBACK | String | Yes | 발신자 전화번호(“-“제외/숫자만 입력) “01012345678” |
| REQDATE | String | Yes | 발송시간(없을 경우 즉시발송) |
| “20130529171111”(2013-05-29-17:11:11) | |||
| MSG | String | No | 전송할 메시지 |
| (승인된 템플릿의 내용과 동일하게 작성) | |||
| TEMPLATE_CODE | String | No | 카카오 알림톡 템플릿코드 |
| FAILED_TYPE | String | No | 카카오알림톡 전송 실패 시 전송할 메시지 타입 ( SMS, LMS, N(전송안함) ) |
| FAILED_SUBJECT | String | Yes | 카카오알림톡 전송 실패 시 전송할 제목 |
| (SMS 미사용) | |||
| FAILED_MSG | String | Yes | 카카오알림톡 전송 실패 시 전송할 내용 |
| BTN_TYPES | String | No | 카카오 알림톡 버튼타입 (웹링크, 앱링크, 봇키워드, 메시지전달, 배송조회), 최대 5개까지 추가 가능하며 타입별 콤마로 구분함. |
| (승인된 템플릿과 불일치시 전송실패) | |||
| BTN_TXTS | String | No | 카카오 알림톡 버튼이름 (BNT_TYPES 입력 순으로 버튼이름 TEXT 입력, 승인된 템플릿과 불일치시 전송실패), TEXT별 콤마로 구분함. |
| (승인된 템플릿과 불일치시 전송실패) | |||
| BTN_URLS1 | String | No | 알림톡 버튼링크주소 URL. 버튼 URL 버튼이2개 이상일 경우 콤마로 구분함. |
| 웹링크, 앱링크는 URL이 필수이며, 기타(배송조회, 봇키워드, 메시지전달)은 null 값임. | |||
| (승인된 템플릿과 불일치시 전송실패) | |||
| BTN_URLS2 | String | No | 알림톡 버튼링크주소 URL. 버튼 1개에 링크가2개인 경우 BTN_URLS2 파라미터 사용. 버튼이 2개 이상일 경우 콤마로 구분함. |
| (승인된 템플릿과 불일치시 전송실패) |
FAILED_TYPE Element Type Optional Description result_code String No 처리 결과 코드 100 : User Error 200 : OK 300 : Parameter Error 301 : failed_type 이 "N" 이 아닌 경우에 실패SMS 제목과 내용이 없으면 에러 400 : Etc Error 500 : 발신번호 사전 등록제에 의한 미등록 차단 ( 3.4 발신번호 인증/등록 참조) 600 : 충전요금 부족 700 : 템플릿코드 사전 승인제에 의한 미승인 차단 800 : 템플릿코드에러 900 : 프로파일이 존재하지 않음 result_message String No 잔금 부족[미발송 목록] 01012345678 cmid 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 FAILED_TYPE=LMS FAILED_SUBJECT=테스트 FAILED_MSG=테스트 BTN_TYPES=웹링크,웹링크 BTN_TXTS=홈페이지1,홈페이지2 BTN_URLS1= https://www.apistore1.co.kr, https://www.apistore2.co.kr
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} 요청 파라미터 Element Type Optional Description cmid(소문자) String No 서버에서 생성한 request를 식별할 수 있는 유일한 키 반환값 Element Type Optional Description STATUS String No 발송상태 1: 발송대기 2: 전송완료 3: 알림톡 결과수신완료 4: Failback 결과수신완료 PHONE String No 수신한 핸드폰번호 CALLBACK String No 발신자 전화번호 RSLT String Yes 카카오알림톡 결과수신 (6.1 Appendix Report Code 참조)
MSG_RSLT String Yes 카카오알림톡 실패 시 메시지 결과수신 (6.1 Appendix Report Code 참조)
사용 예제 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 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} 요청 파라미터 Element Type Optional Description TEMPLATE_CODE String Yes 템플릿코드 – 입력 안 할경우 전체 리스트 반환 STATUS String Yes 검수상태 – 입력 안 할경우 전체 리스트 반환 등록(1) / 검수요청(2) 승인(3) / 반려(4) / 승인중단(5) 반환값 Element Type Optional Description TEMPLATE_CODE String No 템플릿코드 TEMPLATE_NAME String No 템플릿명 TEMPLATE_MSG String No 템플릿 내용 STATUS String No 등록상태(등록,검수요청,승인,반려) BTNLIST String No 버튼 리스트 TEMPLATE_BTN_URL String No 버튼 URL TEMPLATE_BTN_NAME String No 버튼이름 TEMPLATE_BTN_TYPE String No 버튼 타입 사용 예제 REQUEST 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} 요청 파라미터 Element Type Optional Description sendnumber String No 발신번호(“-“ 제외) (발신번호 등록 규칙 참조)
comment String No 코멘트(200자) pintype String Yes 인증방법 (SMS. VMS(음성) 중 1개 선택) pincode String Yes 인증번호-인증번호 받은 후, pincode 파라미터 사용 (SMS 인증번호(6자리), VMS인증번호 (2자리)) 반환값 Element Type Optional Description 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자리))
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} 요청 파라미터 Element Type Optional Description sendnumber String Yes 발신번호(“-“제외) – 입력 안 할경우 전체 리스트 반환 반환값 Element Type Optional Description 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 등록한 번호 사용 예제 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
RSLT
| 결과코드 | 코드 | Description |
|---|---|---|
| 0 | SUCCESS | 성공 |
| 1 | INVALID_SENDER_KEY | 발신 프로필 키가 유효하지않음 |
| 2 | NOT_CONNECTED_USER | 서버와 연결되어있지않은 사용자 |
| 5 | ACK_TIMEOUT | 메시지 발송 후 수신여부 불투명 |
| 6 | RESPONSE_HISTORY_NOTFOUND | 메시지 전송결과를 찾을 수 없음 |
| 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 | 메시지가 템플릿과 비교 실패 |
MSG_RSLT
| 결과코드 | 코드 | Description |
|---|---|---|
| 0 | E_OK | 성공 |
| 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 내부) / 메시지 본문 중복 차단(Agent 내부) |
| p | E_DUPLICATE_PHONE_MSG | TIME OUT 처리(Agent 내부) / 메시지 본문 중복 차단(Agent 내부) |
| q | E_DUPLICATE_KEY | 메시지 중복키 체크(Agent 내부) |
| t | E_TOGETHER_COUNT | 잘못된 동보 전송 수신번호 리스트 / 카운트 |
| 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 | 잘못된 컨텐츠 |