알림톡 API
- 인쇄
- PDF
알림톡 API
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
기본 정보
API URL
https://sens.apigw.gov-ntruss.com/alimtalk/v2
API Header
항목 | Mandatory | 설명 |
---|---|---|
Content-Type | Mandatory | 요청 Body Content Type을 application/json으로 지정 (POST) |
x-ncp-apigw-timestamp | Mandatory | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것으로 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주 |
x-ncp-iam-access-key | Mandatory | 포탈이나 Sub Account에서 발급받은 Access Key ID |
x-ncp-apigw-signature-v2 | Mandatory | 위 예제의 Body를 Access Key Id와 맵핑되는 SecretKey로 암호화한 서명 HMAC 암호화 알고리즘은 HmacSHA256 사용 |
메시지
메시지 발송
메시지를 발송합니다.
요청 URL
POST https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/messages
Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Headers
요청 Body
{
"plusFriendId":"string",
"templateCode":"string",
"messages":[
{
"countryCode":"string",
"to":"string",
"title":"string",
"content":"string",
"headerContent":"string",
"itemHighlight":{
"title":"string",
"description":"string"
},
"item":{
"list":[
{
"title":"string",
"description":"string"
}
],
"summary":{
"title":"string",
"description":"string"
}
},
"buttons":[
{
"type":"string",
"name":"string",
"linkMobile":"string",
"linkPc":"string",
"schemeIos":"string",
"schemeAndroid":"string"
}
],
"useSmsFailover": "boolean",
"failoverConfig": {
"type": "string",
"from": "string",
"subject": "string",
"content": "string"
}
}
],
"reserveTime": "yyyy-MM-dd HH:mm",
"reserveTimeZone": "string"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
templateCode | Mandatory | String | 템플릿 코드 | |
messages | Mandatory | Object | 메시지 정보 | 아래 항목들 참조 (messages.XXX) 최대 100개 |
messages.countryCode | Optional | String | 수신자 국가번호 | default: 82 |
messages.to | Mandatory | String | 수신자번호 | |
messages.title | Optional | String | 알림톡 강조표시 내용 | 강조표기 유형의 템플릿에서만 사용 가능 |
messages.content | Mandatory | String | 알림톡 메시지 내용 | |
messages.headerContent | Optional | String | 알림톡 헤더 내용 | 아이템리스트 유형의 템플릿에서만 사용 가능 - 16 bytes 미만 까지 입력 가능 |
messages.itemHighlight | Optional | Object | 아이템 하이라이트 | 아이템리스트 유형의 템플릿에서만 사용 가능 |
messages.itemHighlight.title | Mandatory | String | 아이템 하이라이트 제목 | 아이템리스트 유형의 템플릿에서만 사용 가능 이미지가 없는 경우 - 최대 30자까지 입력 가능 (2줄) - 1줄은 15자까지 입력 가능 이미지가 있는 경우 - 최대 21자까지 입력 가능 (2줄) - 1줄은 10자까지 입력 가능 - 2줄 초과 시 말줄임 처리 |
messages.itemHighlight.description | Mandatory | String | 아이템 하이라이트 설명 | 아이템리스트 유형의 템플릿에서만 사용 가능 이미지가 없는 경우 - 최대 19자까지 입력 가능 (1줄) 이미지가 있는 경우 - 최대 13자까지 입력 가능 (1줄) - 1줄 초과 시 말줄임 처리 |
messages.item | Optional | Object | 아이템 리스트 | 아이템리스트 유형의 템플릿에서만 사용 가능 |
messages.item.list | Mandatory | Array of Object | 아이템 리스트 | 아이템리스트 유형의 템플릿에서만 사용 가능 - 최소 2개 이상, 최대 10개 |
messages.item.list.title | Mandatory | String | 아이템 리스트 제목 | 아이템리스트 유형의 템플릿에서만 사용 가능 - 최대 6자까지 입력 가능 |
messages.item.list.description | Mandatory | String | 아이템 리스트 설명 | 아이템리스트 유형의 템플릿에서만 사용 가능 - 최대 23자까지 입력 가능 |
messages.summary | Optional | Object | 아이템 요약 정보 | 아이템리스트 유형의 템플릿에서만 사용 가능 |
messages.summary.title | Mandatory | String | 아이템 요약 제목 | 아이템리스트 유형의 템플릿에서만 사용 가능 - 최대 6자까지 입력 가능 |
messages.summary.description | Mandatory | String | 아이템 요약 설명 | 아이템리스트 유형의 템플릿에서만 사용 가능 - 허용되는 문자: 통화기호(유니코드 통화기호, 元, 円, 원), 통화코드 (ISO 4217), 숫자, 콤마, 소수점, 공백 - 소수점 2자리까지 허용 - 최대 23자까지 입력 가능 |
messages.buttons | Optional | Array of Object | 알림톡 메시지 버튼 | 아래 템플릿 버튼 정보 참조 |
messages.buttons.type | Mandatory | String | 버튼 Type | 아래 템플릿 버튼 정보 참조 |
messages.buttons.name | Mandatory | String | 버튼명 | 아래 템플릿 버튼 정보 참조 |
messages.useSmsFailover | Optional | Boolean | SMS Failover 사용 여부 | Failover가 설정된 카카오톡 채널에서만 사용 가능 기본: 카카오톡 채널의 Failover 설정 여부를 따름 |
messages.failoverConfig | Optional | Object | Failover 설정 | 아래 항목들 참조 |
messages.failoverConfig.type | Optional | String | Failover SMS 메시지 Type | SMS or LMS 기본: content 길이에 따라 자동 적용 (90 bytes 이하 SMS, 초과 LMS) |
messages.failoverConfig.from | Optional | String | Failover SMS 발신번호 | 기본: Failover 설정 시 선택한 발신번호 승인되지 않은 발신번호 사용시, Failover 동작 안함 |
messages.failoverConfig.subject | Optional | String | Failover SMS 제목 | LMS type으로 동작할 때 사용 기본: 카카오톡 채널명 |
messages.failoverConfig.content | Optional | String | Failover SMS 내용 | 기본: 알림톡 메시지 내용 (버튼 제외) |
reserveTime | Optional | String | 예약 일시 | 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm) |
reserveTimeZone | Optional | String | 예약 일시 타임존 | 예약 일시 타임존 (기본: Asia/Seoul) * 지원 타임존 목록 * TZ database name 값 사용 |
주의
- 요청 Body의 Mandatory 필드를 사용하시는 경우, 공백은 허용되지않습니다. (추가하는 경우에만 해당)
- 내용(content), 버튼(buttons)는 등록 및 검수 완료된 템플릿 규격에 맞추어 입력해야 합니다.
- 템플릿 규격에 맞지 않는 메시지 발송 요청 시, 메시지 발송에 실패합니다.
참고
- 템플릿에 이미지가 등록된 경우, 별도로 메시지 발송 시, 요청 body에 해당 내용을 넣지 않아도 등록된 이미지가 발송됩니다.
- SMS Failover는 알림톡 수신 결과 코드 기준, 성공이 아닌 경우 동작하며, prefix로 B가 붙은 코드들에 대해서는 failover 기능을 통한 SMS 대체 발송이 이루어지지 않습니다.
템플릿 등록 및 검수에 대한 가이드는 웹 콘솔 설명서(구, 사용자 가이드)에서 확인할 수 있습니다. 템플릿 등록 가이드 바로가기
템플릿 버튼 정보
Type | Name | Mandatory 항목 |
---|---|---|
DS | 배송 조회 | |
WL | 웹 링크 | linkMobile, linkPc (http:// 또는 https://로 시작하는 URL) |
AL | 앱 링크 | schemeIos, schemeAndroid |
BK | 봇 키워드 | |
MD | 메시지 전달 | |
AC | 채널 추가 | 버튼 명은 채널 추가 로 고정 |
지원 택배사 목록
택배사 | 택배사명 | 송장번호 |
---|---|---|
우체국택배 | 우체국 | 숫자 13자리 또는 숫자 6자리 + 숫자 7자리 (구분자 '-' 또는 '_') |
로젠택배 | 로젠, 로잰 | 숫자 11자리 또는 숫자 3자리 + 숫자 4자리 + 숫자 4자리 (구분자 '-' 또는 '_') |
일양로지스 | 일양로지스택배 일양택배 일양로지스 | 숫자 9~11자리 |
FedEX | 페덱스 FedEx fedex | 숫자 12자리 |
한진택배 | 한진택배 | 숫자 10자리 또는 숫자 12자리 |
경동택배 | 경동택배 | 숫자 9~16자리 또는 숫자 4자리 + 숫자 3자리 + 숫자 6자리 (구분자 '-') |
합동택배 | 합동택배 | 숫자 9~16자리 |
롯데택배 | 롯데택배 롯데로지스틱스 현대택배 현대로지스틱스 | 숫자 12자리 또는 숫자 4자리 + 숫자 4자리 + 숫자 4자리 (구분자 '-') |
농협택배 | 농협택배 | 숫자 12자리 |
호남택배 | 호남택배 | 숫자 10자리 |
천일택배 | 천일택배 | 숫자 11자리 |
대신택배 | 대신택배 | 숫자 13자리 |
건영택배 | 건영택배 | 숫자 10자리 |
CU편의점택배 | CU편의점택배 CU 편의점택배 | 숫자 10자리 또는 숫자 12자리 또는 숫자 4자리 + 숫자 4자리 + 숫자 4자리 (구분자 '-' 또는 '_') |
CVSnet편의점택배 | GSPostbox택배 GS편의점택배 CVSnet편의점택배 | 숫자 10자리 또는 숫자 12자리 또는 숫자 4자리 + 숫자 4자리 + 숫자 4자리 (구분자 '-' 또는 '_') |
한덱스 | 한덱스 | 숫자 10자리 또는 숫자 14자리 |
TNT Express | TNTExpress TNT택배 TNT Express | 숫자 8~9자리 |
USPS | USPS | 숫자 10자리 또는 숫자 22자리 또는 대문자 알파벳 2자리 + 숫자 9자리 + 대문자 알파벳 2자리 (구분자 없음) |
EMS | EMS | 대문자 알파벳 2자리 + 숫자 9자리 + 대문자 알파벳 2자리 (구분자 없음) |
DHL | DHL | 숫자 10자리 |
굿투럭 | 굿투럭 | 숫자 4자리 + 숫자 4자리 + 숫자 4자리 (구분자 '-') |
- 미지원 택배사의 경우 버튼이 자동으로 추가되지 않습니다.
- 웹링크(WL) 버튼을 통해 배송조회 페이지에 연결하여 사용할 수 있습니다.
응답 Body
{
"requestId":"string",
"requestTime":"string",
"statusCode":"string",
"statusName":"string",
"messages":[
{
"messageId":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"useSmsFailover":"boolean"
}
]
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
requestId | Mandatory | String | 발송 요청 아이디 | |
requestTime | Mandatory | DateTime | 발송 요청 시간 | yyyy-MM-dd'T'HH:mm:ss.SSS |
statusCode | Mandatory | String | 요청 상태 코드 | 202 - 성공 그외 - 실패 * HTTP Status 규격을 따름 |
statusName | Mandatory | String | 요청 상태명 | success - 성공 processing - 처리중 reserved - 예약중 fail - 실패 |
messages.messageId | Mandatory | String | 메시지 아이디 | |
messages.countryCode | Optional | String | 수신자 국가번호 | |
messages.to | Mandatory | String | 수신자번호 | |
messages.content | Mandatory | String | 알림톡 메시지 내용 | |
messages.requestStatusCode | Mandatory | String | 발송요청 상태 코드 | A000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messages.requestStatusName | Mandatory | String | 발송요청 상태명 | success - 성공 fail - 실패 |
messages.requestStatusDesc | Mandatory | String | 발송요청 상태 내용 | |
messages.useSmsFailover | Mandatory | Boolean | SMS Failover 사용 여부 |
응답 Status
HTTP Status | Desc |
---|---|
202 | Accepted (발송 요청 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
메시지 발송 요청 조회
메시지 발송 요청을 조회합니다.
요청 URL
GET https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/messages?requestId=
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Parameters
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
requestId | Mandatory | String | 요청 아이디 | 발송 요청 아이디 |
plusFriendId | Mandatory | String | 카카오 채널 | 등록된 채널 명 |
requestStartTime | Mandatory | String | 조회 시간 시작 시각 | yyyy-MM-dd'T'HH:mm:ss |
requestEndTime | Mandatory | String | 조회 시간 종료 시각 | yyyy-MM-dd'T'HH:mm:ss |
completeStartTime | Mandatory | String | 발송 완료 시작 시간 | yyyy-MM-dd'T'HH:mm:ss |
completeEndTime | Mandatory | String | 발송 완료 종료 시간 | yyyy-MM-dd'T'HH:mm:ss |
messageId | Optional | String | 메시지 아이디 | |
requestStatusName | Optional | String | 요청 상태 | success, fail |
messageStatusName | Optional | String | 요청 상태 | success, processing, fail |
templateCode | Optional | String | 템플릿 코드 | 등록된 템플릿 코드 |
to | Optional | String | 메세지 수신 번호 | 붙임표 (-)를 제외한 번호 |
pageIndex | Optional | Integer | 페이지 번호 | default: 0 |
pageSize | Optional | Integer | 페이지 크기 | default: 20, max: 100 requestId를 포함한 조회시, default: 100 |
참고
- 메시지 발송 이력은 최근 30일 이내의 이력만 조회할 수 있습니다.
- requestId 또는 requestStartTime + requestEndTime 또는 completeStartTime + completeEndTime 중에 하나는 필수입니다.
- requestStartTime + requestEndTime과 completeStartTime + completeEndTime은 동시에 사용할 수 없습니다.
- requestStartTime ~ requestEndTime의 조회 범위는 최대 31일로 제한됩니다.
- completeStartTime ~ completeEndTime의 조회 범위는 최대 24시간으로 제한됩니다.
- 조회 조건에 requestId가 포함되어있지않은 경우, plusFriendId는 필수입니다.
Headers
요청 Body
없음
응답 Body
{
"requestId": "string",
"statusCode": "string",
"statusName": "string",
"messages": [
{
"requestTime": "string",
"messageId": "string",
"countryCode": "string",
"to": "string",
"content": "string",
"plusFriendId": "string",
"templateCode": "string",
"completeTime": "string",
"requestStatusCode": "string",
"requestStatusName": "string",
"requestStatusDesc": "string",
"messageStatusCode": "string",
"messageStatusName": "string",
"messageStatusDesc": "string",
"useSmsFailover": "boolean",
"failover": {
"smsServiceId": "string",
"requestId": "string",
"messageId": "string",
"requestStatusCode": "string",
"requestStatusName": "string",
"requestStatusDesc": "string",
"messageStatus": "string",
"messageStatusCode": "string",
"messageStatusName": "string",
"messageStatusDesc": "string"
}
}
],
"pageSize": "integer",
"pageIndex": "integer",
"itemCount": "integer",
"hasMore": "boolean"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
requestId | Optional | String | 발송 요청 아이디 | requestId로 조회하는 경우에만 노출됨 |
statusCode | Mandatory | String | 요청 상태 코드 | 202 - 성공 그외 - 실패 * HTTP Status 규격을 따름 |
statusName | Mandatory | String | 요청 상태명 | success - 성공 processing - 발송중 reserved - 예약중 fail - 실패 |
messages.requestTime | Mandatory | DateTime | 발송 요청 시간 | yyyy-MM-dd'T'HH:mm:ss.SSS |
messages.messageId | Mandatory | String | 메시지 아이디 | |
messages.countryCode | Optional | String | 수신자 국가번호 | default: 82 |
messages.to | Mandatory | String | 수신자번호 | |
messages.content | Mandatory | String | 알림톡 메시지 내용 | |
messages.plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
messages.templateCode | Mandatory | String | 템플릿 코드 | |
messages.completeTime | Optional | DateTime | 발송 리포트(처리 완료) 시간 | yyyy-MM-dd'T'HH:mm:ss |
messages.requestStatusCode | Mandatory | String | 발송요청 상태 코드 | A000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messages.requestStatusName | Mandatory | String | 발송요청 상태명 | success - 성공 fail - 실패 |
messages.requestStatusDesc | Mandatory | String | 발송요청 상태 내용 | |
messages.messageStatusCode | Mandatory | String | 발송결과 상태 코드 | 0000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messages.messageStatusName | Mandatory | String | 발송결과 상태명 | success - 성공 processing - 처리중 * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태 * messageCode, messageDesc가 조회되지 않음 fail - 실패 |
messages.messageStatusDesc | Mandatory | String | 발송결과 상태 내용 | |
messages.useSmsFailover | Mandatory | Boolean | SMS Failover 사용 여부 | |
messages.failover | Optional | Object | SMS Failover | |
messages.failover.smsServiceId | Optional | String | SMS Failover 서비스 아이디 | |
messages.failover.requestId | Optional | String | SMS Failover 발송 요청 아이디 | |
messages.failover.messageId | Optional | String | SMS Failover 발송 메시지 아이디 | |
messages.failover.requestStatusCode | Optional | String | SMS Failover 발송 요청 상태 코드 | 오류 코드 표 참고 |
messages.failover.requestStatusName | Optional | String | SMS Failover 발송 요청 상태명 | success - 성공 fail - 실패 |
messages.failover.requestStatusDesc | Optional | String | SMS Failover 발송 요청 상태 내용 | |
messages.failover.messageStatus | Optional | String | SMS Failover 발송 처리 상태 | READY: 대기 PROCESSING: 처리 중 COMPLETED: 처리 완료 |
messages.failover.messageStatusCode | Optional | String | SMS Failover 발송 단말 수신 상태 결과 코드 | 오류 코드 표 참고 |
messages.failover.messageStatusName | Optional | String | SMS Failover 발송 단말 수신 결과명 | |
messages.failover.messageStatusDesc | Optional | String | SMS Failover 발송 단말 수신 내용 | |
pageSize | Mandatory | Integer | 페이지 사이즈 | |
pageIndex | Mandatory | Integer | 페이지 인덱스 (0부터 시작) | |
itemCount | Mandatory | Integer | 조회한 페이지 내의 메시지 수 | |
hasMore | Mandatory | Boolean | 다음 페이지 존재 여부 |
참고
- 조회 조건에 requestId가 포함되어있지않은 경우, requestId는 포함되지 않습니다.
응답 Status
HTTP Status | Desc |
---|---|
200 | OK (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
메시지 발송 결과 조회
메시지 발송 결과를 조회합니다.
요청 URL
GET https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/messages/{messageId}
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
messageId | Mandatory | String | 메시지 아이디 | 메시지 발송시 반환되는 메시지 식별자 |
Headers
요청 Body
없음
응답 Body
{
"messageId":"string",
"requestId":"string",
"requestTime":"string",
"completeTime":"string",
"plusFriendId":"string",
"templateCode":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"messageStatusCode":"string",
"messageStatusName":"string",
"messageStatusDesc":"string",
"useSmsFailover":"boolean",
"failover": {
"smsServiceId":"string",
"requestId":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"messageId":"string",
"messageStatus":"string",
"messageStatusCode":"string",
"messageStatusName":"string",
"messageStatusDesc":"string"
}
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
messageId | Mandatory | String | 메시지 아이디 | |
requestId | Mandatory | String | 발송 요청 아이디 | |
requestTime | Mandatory | DateTime | 발송 요청 시간 | yyyy-MM-dd'T'HH:mm:ss.SSS |
completeTime | Optional | DateTime | 발송 리포트(처리 완료) 시간 | yyyy-MM-dd'T'HH:mm:ss |
plusFriendId | Mandatory | String | 카카오톡 채널명 ((구)플러스친구 아이디) | |
templateCode | Mandatory | String | 템플릿 코드 | |
countryCode | Optional | String | 수신자 국가번호 | |
to | Mandatory | String | 수신자번호 | |
content | Mandatory | String | 알림톡 메시지 내용 | |
requestStatusCode | Mandatory | String | 발송요청 상태 코드 | A000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
requestStatusName | Mandatory | String | 발송요청 상태명 | success - 성공 fail - 실패 |
requestStatusDesc | Mandatory | String | 발송요청 상태 내용 | |
messageStatusCode | Mandatory | String | 발송결과 상태 코드 | 0000 - 성공 그외 코드 - 실패(Desc 항목에 실패 사유가 명시) |
messageStatusName | Mandatory | String | 발송결과 상태명 | success - 성공 processing - 처리중 * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태 * messageCode, messageDesc가 조회되지 않음 fail - 실패 |
messageStatusDesc | Mandatory | String | 발송결과 상태 내용 | |
messages.useSmsFailover | Mandatory | Boolean | SMS Failover 사용 여부 | |
messages.failover | Optional | Object | SMS Failover 사용 여부 | |
messages.failover.smsServiceId | Optional | String | SMS Failover 서비스 아이디 | |
messages.failover.requestId | Optional | String | SMS Failover 발송 요청 아이디 | |
messages.failover.requestStatusCode | Optional | String | SMS Failover 발송 요청 상태 코드 | 오류 코드 표 참고 |
messages.failover.requestStatusName | Optional | String | SMS Failover 발송 요청 상태명 | success - 성공 fail - 실패 |
messages.failover.requestStatusDesc | Optional | String | SMS Failover 발송 요청 상태 내용 | |
messages.failover.messageId | Optional | String | SMS Failover 발송 메시지 아이디 | |
messages.failover.messageStatus | Optional | String | SMS Failover 발송 처리 상태 | READY: 대기 PROCESSING: 처리 중 COMPLETED: 처리 완료 |
messages.failover.messageStatusCode | Optional | String | SMS Failover 발송 단말 수신 상태 결과 코드 | 오류 코드 표 참고 |
messages.failover.messageStatusName | Optional | String | SMS Failover 발송 단말 수신 결과명 | |
messages.failover.messageStatusDesc | Optional | String | SMS Failover 발송 단말 수신 내용 |
Failover 요청 상태 코드
requestStatusCode | Desc |
---|---|
0 | 성공 |
E4000 | failover 설정이 유효하지 않음 |
E4001 | failover 설정 정보가 누락됨 |
E4002 | failover SMS 서비스가 설정되지 않음 |
E4003 | failover SMS type(SMS, LMS)이 설정되지 않음 |
E4004 | failover SMS 발신번호가 설정되지 않음 |
E4005 | failover SMS 제목이 설정되지 않음 |
E4006 | failover SMS 내용이 설정되지 않음 |
E4007 | failover SMS 수신번호가 설정되지 않음 |
E4008 | failover SMS 서비스가 사용 가능한 상태가 아님 |
E4009 | failover SMS 발신번호가 인증되지 않음 |
E4010 | failover SMS 080무료수신거부 서비스가 사용 가능한 상태가 아님 |
E4999 | failover 설정 파싱 오류 (고객 지원으로 문의 필요) |
E5000 | 내부 오류 (고객 지원으로 문의 필요) |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
예약 메시지
예약 메시지 상태 조회
메시지 발송 예약 상태를 조회합니다.
GET https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/reservations/{reserveId}/reserve-status
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
reserveId | Mandatory | String | 예약 메시지 아이디 | 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId) |
Headers
요청 Body
없음
응답 Body
{
"reserveId": "string",
"reserveTimeZone": "string",
"reserveTime": "string",
"reserveStatus": "string"
}
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
reserveId | Mandatory | String | 예약 메시지 아이디 | 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId) |
reserveTime | Mandatory | String | 예약 일시 | 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm) |
reserveTimeZone | Mandatory | String | 예약 일시 타임존 | 예약 일시 타임존 (기본: Asia/Seoul) * 지원 타임존 목록 * TZ database name 값 사용 |
reserveStatus | Mandatory | String | 예약 상태 | READY - 발송 대기 PROCESSING - 발송 요청중 CANCELED - 발송 취소 FAIL - 발송 요청 실패 DONE - 발송 요청 성공 STALE - 발송 요청 실패 (시간 초과) |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK (조회 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
예약 메시지 취소
메시지 발송 예약을 취소합니다.
DELETE https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/reservations/{reserveId}
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
reserveId | Mandatory | String | 예약 메시지 아이디 | 예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId) |
Headers
요청 Body
없음
응답 Body
없음
응답 Status
HTTP Status | Desc |
---|---|
204 | No Content (삭제 완료) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
카카오톡 채널
채널 조회
카카오톡 채널을 조회합니다.
GET https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/channels
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Parameters
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
pageSize | Optional | Integer | 페이지 사이즈 | default: 20 (1 ~ 100 사이의 숫자만 입력 가능) |
pageIndex | Optional | Integer | 페이지 인덱스 | default: 0 |
Headers
요청 Body
없음
응답 Body
[
{
"createTime": "string",
"updateTime": "string",
"serviceId": "string",
"channelId": "string",
"channelName": "string",
"channelStatus": "string",
"useSmsFailover": "boolean",
"failoverServiceId": "string",
"failoverTelNo": "string",
"isBlock": "boolean",
"isDormant": "boolean"
}
]
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
createTime | Mandatory | String | 생성 시간 | format: LocalDateTime |
updateTime | Optional | String | 수정 시간 | format: LocalDateTime |
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
channelId | Mandatory | String | 카카오톡 채널 아이디 | |
channelName | Mandatory | String | 카카오톡 채널 이름 | |
channelStatus | Mandatory | String | 카카오톡 채널 상태 | - 정상: ACTIVE - 삭제: DELETED - 영구 삭제 중: DELETING_PERMANENTLY - 영구 삭제: PERMANENTLY_DELETED - 차단: BLOCKED - 삭제 지연 중: PENDING_DELETE |
useSmsFailover | Mandatory | Boolean | SMS 대체 발송 사용 여부 | |
failoverServiceId | Optional | String | Failover SMS 서비스ID | |
failoverTelNo | Optional | String | Failover 발신번호 | |
isBlock | Mandatory | Boolean | 채널 차단 여부 | |
isDormant | Mandatory | Boolean | 채널 휴면 전환 여부 |
응답 Status
HTTP Status | Desc |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
알림톡 템플릿
템플릿 조회
카카오톡 채널에 등록된 알림톡 템플릿을 조회합니다.
GET https://sens.apigw.gov-ntruss.com/alimtalk/v2/services/{serviceId}/templates?channelId=
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
serviceId | Mandatory | String | 서비스 아이디 | 프로젝트 등록 시 발급받은 서비스 아이디 |
Parameters
- channelId는 필수 값이며, templateCode 사용 시 템플릿에 대한 상세정보를 반환합니다.
- comments를 비롯한 부가 정보들은 상세 조회시에만 노출됩니다.
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
channelId | Mandatory | String | 채널 아이디 | 카카오톡에 등록된 채널 아이디 |
templateCode | Mandatory | String | 템플릿 코드 | templateCode를 사용하여 조회 시 상세 조회 결과 반환 등록된 템플릿 코드 |
templateName | Optional | String | 템플릿 이름 | like 조회 결과를 반환 |
pageSize | Optional | Integer | 페이지 사이즈 | default: 20 (1 ~ 100 사이의 숫자만 입력 가능) |
pageIndex | Optional | Integer | 페이지 인덱스 | default: 0 |
Headers
요청 Body
없음
응답 Body
[
{
"createTime": "string",
"updateTime": "string",
"channelId": "string",
"templateCode": "string",
"templateName": "string",
"categoryCode": "string",
"categoryName": "string",
"messageType" : "string",
"emphasizeType" : "string",
"content": "string",
"adContent": "string",
"extraContent": "string",
"title": "string",
"additionalTitle": "string",
"comments": [
{
"commentId": "string",
"content": "string",
"status": "string",
"createTime": "string",
"attachment": [
{
"fileName": "string",
"fileUrl": "string"
}
]
}
],
"templateInspectionStatus": "string",
"templateStatus": "string",
"buttons":[
{
"order":"integer",
"type":"string",
"name":"string",
"linkMobile":"string",
"linkPc":"string",
"schemeIos":"string",
"schemeAndroid":"string"
}
],
"imageName": "string",
"imageUrl": "string",
"headerContent": "string",
"itemHighlight": {
"title": "string",
"description": "string",
"imageUrl": "string"
},
"item": {
"list": [
{
"title": "string",
"description": "string"
}
],
"summary": {
"title": "string",
"description": "string"
}
},
"securityFlag": "boolean",
"isBlock": "boolean",
"isDormant": "boolean"
}
]
항목 | Mandatory | Type | 설명 | 비고 |
---|---|---|---|---|
createTime | Mandatory | String | 생성 시간 | format: LocalDateTime |
updateTime | Optional | String | 수정 시간 | format: LocalDateTime |
channelId | Mandatory | String | 카카오톡 채널 아이디 | |
templateCode | Mandatory | String | 템플릿 코드 | |
templateName | Mandatory | String | 템플릿 이름 | |
categoryCode | Mandatory | String | 템플릿 카테고리 코드 | |
categoryName | Mandatory | String | 템플릿 카테고리 이름 | |
messageType | Mandatory | String | 템플릿 메시지 유형 | - BA: 기본형 - EX: 부가 정보형 - AD: 광고 추가형 - MI: 복합형 |
emphasizeType | Mandatory | String | 템플릿 강조 유형 | - NONE :기본형 - TEXT: 강조표기형 - IMAGE: 이미지형 - ITEM_LIST: 아이템리스트형 |
content | Mandatory | String | 템플릿 내용 | |
adContent | Optional | String | 광고성 메시지 | |
extraContent | Optional | String | 부가 정보 | |
title | Optional | String | 강조표기형 제목 | |
additionalTitle | Optional | String | 강조표기형 추가 제목 | |
comments.commentId | Mandatory | String | 검수 아이디 | |
comments.content | Mandatory | String | 검수 내용 | |
comments.status | Mandatory | String | 검수 상태 | - 검수 완료: APR - 검수 반려: REJ |
comments.create | Mandatory | String | 검수 시간 | |
comments.attachment | Optional | Object | 검수 문의하기 첨부파일 | |
comments.attachment.fileName | Mandatory | String | 파일 이름 | |
comments.attachment.fileUrl | Mandatory | String | 파일 URL | |
templateInspectionStatus | Mandatory | String | 템플릿 검수 상태 | - 수락: ACCEPT - 등록: REGISTER - 검수 중: INSPECT - 완료: COMPLETE - 반려: REJECT |
templateStatus | Mandatory | String | 템플릿 상태 | - 정상: ACTIVE - 대기: READY - 정지: STOP |
buttons | Optional | Array of Object | 알림톡 메시지 버튼 | 상위 템플릿 버튼 정보 참조 |
buttons.order | Mandatory | Integer | 버튼 순서 | 버튼 등록 순서 |
buttons.type | Mandatory | String | 버튼 Type | 상위 템플릿 버튼 정보 참조 |
buttons.name | Mandatory | String | 버튼명 | 상위 템플릿 버튼 정보 참조 |
buttons.linkMobile | Optional | String | 버튼 mobile link | 등록된 template button 정보 참고 |
buttons.linkPc | Optional | String | 버튼 pc link | 등록된 template button 정보 참고 |
buttons.schemeIos | Optional | String | 버튼 ios scheme | 등록된 template button 정보 참고 |
buttons.schemeAndroid | Optional | String | 버튼 adnroid scheme | 등록된 template button 정보 참고 |
title | Optional | String | 강조표시형 제목 | |
additionalTitle | Optional | String | 강조표시형 추가 제목 | |
useImage | Mandatory | Boolean | 이미지 사용 여부 | |
imageName | Optional | String | 이미지 이름 | |
imageUrl | Optional | String | 이미지 URL | |
useHeaderContent | Mandatory | Boolean | 헤더 사용 여부 | |
headerContent | Optional | String | 헤더 내용 | |
useItemHighlight | Mandatory | Boolean | 아이템 하이라이트 사용여부 | |
useItemHighlightImage | Mandatory | Boolean | 아이템 하이라이트 이미지 사용여부 | |
itemHighlight | Optional | Object | 아이템 하이라이트 | 아이템 하이라이트 사용시에만 노출 |
itemHighlight.title | Optional | String | 아이템 하이라이트 제목 | |
itemHighlight.description | Optional | String | 아이템 하이라이트 내용 | |
itemHighlight.imageUrl | Optional | String | 아이템 하이라이트 이미지 URL | |
item | Optional | Object | 아이템 | 아이템 사용시에만 노출 |
item.list | Optional | String | 아이템 리스트 | 아이템 리스트 사용시에만 노출 |
item.list.title | Optional | String | 아이템 명 | |
item.list.description | Optional | String | 아이템 내용 | |
item.summary | Optional | String | 아이템 요약 정보 | 아이템 요약정보 사용시에만 노출 |
item.summary.title | Optional | String | 아이템 요약정보 명 | |
item.summary.description | Optional | String | 아이템 요약정보 내용 | |
securityFlag | Mandatory | Boolean | 보안 설정 여부 | |
isBlock | Mandatory | Boolean | 템플릿 차단 여부 | |
isDormant | Mandatory | Boolean | 템플릿 휴면 전환 여부 |
참고
- channelId는 필수 값이며 templateCode 사용 시 템플릿에 대한 상세 정보를 반환합니다.
- comments를 비롯한 부가 정보는 상세 조회 시에만 노출됩니다.
응답 Status
HTTP Status | Desc |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
오류 코드
알림톡 수신 결과 코드
Status | Error text | Desc |
---|---|---|
0000 | - | 정상 발송 |
1001 | NoJsonBody | Request Body가 Json형식이 아님 |
1002 | InvalidHubPartnerKey | 파트너 키가 유효하지 않음 |
1003 | InvalidSenderKey | 발신 프로필 키가 유효하지 않음 |
1004 | NoValueJsonElement | Request BODY(Json)에서 name을 찾을 수 없음 |
1005 | SenderNotFound | 발신프로필을 찾을 수 없음 |
1006 | DeletedSender | 삭제된 발신 프로필 |
1007 | StoppedSender | 차단 상태의 발신 프로필 |
1011 | ContractNotFound | 계약 정보를 찾을 수 없음 |
1012 | InvalidUserKeyException | 잘못된 형식의 유저 키 요청 |
1013 | InvalidAppLink | 유효하지 않은 app연결 |
1014 | InvalidBizNum | 유효하지 않은 사업자번호 |
1015 | TalkUserIdNotFonud | 유효하지 않은 app user id 요청 |
1016 | BizNumNotEqual | 사업자등록번호 불일치 |
1020 | InvalidReceiveUserException | 올바른 유저 식별자 값이 하나도 없는 경우 |
1021 | BlockedProfile | 차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1022 | DeactivatedProfile | 닫힘 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1023 | DeletedProfile | 삭제된 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1024 | DeletingProfile | 삭제대기 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1025 | SpammedProfile | 메시지차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인) |
1026 | UnableUseMessageType | 해당 msg_type 에서 사용할 수 없는 response_method 로 요청 (이미지알림톡(AI)는 realtime 으로 발송 불가) |
1030 | InvalidParameterException | 잘못된 파라메터 요청 |
1033 | - | 템플릿 타입과 메시지타입 불일치 |
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 | 메시지를 전송할 수 없음 |
3020 | SeenInfoNotFoundException | 메시지 확인 정보를 찾을 수 없음 |
3022 | NoSendAvailableTimeException | 메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시까지 발송 가능) |
3024 | MessageInvaildImageException | 메시지에 포함된 이미지를 전송할 수 없음 |
3025 | ExceedMaxVariableLengthException | 변수 글자수 제한 초과 |
3026 | Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' | 상담/봇 전환 버튼 extra, event 글자수 제한 초과 |
3027 | NoMatchedTemplateButtonException | 버튼 내용이 템플릿과 일치 하지 않음 |
3028 | NoMatchedTemplateTitleException | 메시지 강조 표기 타이틀이 템플릿과 일치하지 않음 |
3029 | ExceedMaxTitleLengthException | 메시지 강조 표기 타이틀 길이 제한 초과 (50자) |
- | ||
3030 | NoMatchedTemplateWithMessageTypeException | 메시지 타입과 템플릿 강조유형이 일치하지 않음 |
3031 | NoMatchedTemplateHeaderException | 헤더가 템플릿과 일치하지 않음 |
3032 | ExceedMaxHeaderLengthException | 헤더 길이 제한 초과(16 자) |
3033 | NoMatchedTemplateItemHighlightException | 아이템 하이라이트가 템플릿과 일치하지 않음 |
3034 | ExceedMaxItemHighlightTitleLengthException | 아이템 하이라이트 타이틀 길이 제한 초과(이미지 없는 경우 30 자, 이미지 있는 경우 21 자) |
3035 | ExceedMaxItemHighlightDescriptionLengthException | 아이템 하이라이트 디스크립션 길이 제한 초과(이미지 없는 경우 19 자, 이미지 있는 경우 14 자) |
3036 | NoMatchedTemplateItemListException | 아이템 리스트가 템플릿과 일치하지 않음 |
3037 | ExceedMaxItemDescriptionLengthException | 아이템 리스트의 아이템의 디스크립션 길이 제한 초과(23 자) |
3038 | NoMatchedTemplateItemSummaryException | 아이템 요약정보가 템플릿과 일치하지 않음 |
3039 | ExceedMaxItemSummaryDescriptionLengthException | 아이템 요약정보의 디스크립션 길이 제한 초과(14 자) |
3040 | InvalidItemSummaryDescriptionException | 아이템 요약정보의 디스크립션에 허용되지 않은 문자 포함(통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함) |
4000 | ResponseHistoryNotFoundException | 메시지 전송 결과를 찾을 수 없음 |
4001 | UnKnownMessageStatusError | 알수 없는 메시지 상태 |
7011 | - | 시리얼 넘버 패턴 에러 |
7014 | - | 메시지 유효 시간 초과 에러 |
8512 | - | 수신자 타입 찾을 수 없음 |
8514 | - | request_id 찾을 수 없음 |
8520 | - | 지원하지 않는상품 타입 오류 |
8521 | - | 지원하지 않는 메시지 타입 오류 |
8522 | - | 지원하지 않는 텍스트 유형 오류 |
8523 | - | 지원하지 않는 response method 오류 |
8530 | - | 수신자 목록 사이즈 오류 |
8999 | - | 내부 서버 오류 |
9998 | 현재 서비스를 제공하고 있지 않습니다. | 시스템에 문제가 발생하여 담당자가 확인하고 있는 경우 |
9999 | 시스템에 알수 없는 문제 발생, 담당자 확인중 | 시스템에 문제가 발생하여 담당자 확인중 |
B000 | Prepare to relay failed | 중계사 발송을 위한 사전 작업 실패 |
B001 | Request to relay failed | 중계사 발송 실패 |
B002 | Filtering for request to relay failed | 잘못된 요청으로 인해 필터링됨 |
B003 | Invalid phone number format | 올바르지 않은 발신번호 포멧 |
B004 | Quota Exceed | 쿼터 초과 |
B005 | Message processing timeout exceed | 메시지 요청 시간과 처리 시간의 차이가 허용 범위를 벗어남 |
B400 | Invalid Request | 메시지 형식 오류 |
B999 | Unexpected server error | 예기치 못한 에러 |
이 문서가 도움이 되었습니까?