알림톡 API

기본 정보

API URL

https://sens.apigw.gov-ntruss.com/alimtalk/v2

SENS 알림톡 API Swagger 바로가기

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 사용

NAVER CLOUD PLATFORM 인증키 및 Signature 생성 가이드 바로가기

메시지

메시지 발송

메시지를 발송합니다.

요청 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

API Header 바로가기

요청 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	메세지 수신 번호	붙임표 (-)를 제외한 번호
nextToken	Optional	String	다음 페이지 토큰	아래 참고 내용 참조
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는 필수입니다.
nextToken
- 이전 요청에서 nextToken 응답을 받은 경우에만 유효하며, 다음 페이지의 결과를 요청할 수 있음을 나타냅니다. 추가 결과가 있는 경우, 이전 응답의 nextToken 값을 이 Parameter에 설정하면 다음 페이지의 결과를 조회할 수 있습니다.

Headers

API Header 바로가기

요청 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",
    "nextToken": "string",
    "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	페이지 사이즈
nextToken	Optional	String	다음 페이지 토큰	아래 참고 내용 참조
itemCount	Mandatory	Integer	조회한 페이지 내의 메시지 수
hasMore	Mandatory	Boolean	다음 페이지 존재 여부

참고

조회 조건에 requestId가 포함되어있지않은 경우, requestId는 포함되지 않습니다.
nextToken
- 조회된 결과의 다음 페이지가 존재하는 경우에만 nextToken 이 응답에 포함됩니다. nextToken 값을 요청 조회 API Parameter에 설정하면 다음 페이지의 결과를 조회할 수 있습니다.

응답 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

API Header 바로가기

요청 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

API Header 바로가기

요청 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

API Header 바로가기

요청 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	서비스 아이디	프로젝트 등록 시 발급받은 서비스 아이디

Headers

API Header 바로가기

요청 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	Optional	String	템플릿 코드	`templateCode를 사용하여 조회 시 상세 조회 결과 반환` 등록된 템플릿 코드
templateName	Optional	String	템플릿 이름	`like` 조회 결과를 반환
pageSize	Optional	Integer	페이지 사이즈	default: 20 (1 ~ 100 사이의 숫자만 입력 가능)
pageIndex	Optional	Integer	페이지 인덱스	default: 0

Headers

API Header 바로가기

요청 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 으로 발송 불가)
1027	-	채널 메시지 제재 상태로 인한 메시지 전송 실패
1030	InvalidParameterException	잘못된 파라메터 요청
1033	-	템플릿 타입과 메시지 타입 불일치
2000	FailedToCheckFriendshipException	톡채널과 친구관계 확인시 에러 (시스템 에러)
2003	FailedToSendMessageByNoFriendshipException	메시지 전송 실패 (테스트 서버에서 카카오톡 채널을 추가하지 않은 경우)
2004	FailedToMatchTemplateException	템플릿 일치 확인 시 오류 발생 (카카오 내부 오류)
2005	FailedToReadImageException	카카오에서 이미지 메타 정보 읽어오는 중 에러
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	MessageNoUserException	톡유저가 아님
3020	MessageUserBlockedAlimTalkException	알림톡 차단
3021	MessageNotSupportedKakaotalkException	톡 최소 버전 미지원
3022	NoSendAvailableTimeException	메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시까지 발송 가능)
3023	MessageInvalidVideoException	메시지에 포함된 비디오를 전송할 수 없음 (비디오 주소 또는 썸네일 이미지 주소가 올바르지 않거나 썸네일 이미지가 규격에 맞지 않음)
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자)
~~3031~~	-	~~텍스트 유형 불일치~~
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	아이템 요약 정보의 디스크립션에 허용되지 않은 문자 포함(통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함)
3041	MessageInvalidWideItemListLengthException	와이드 아이템 리스트 갯수 최대 최소 갯수 불일치
3042	NoMatchedTemplateRepresentLinkException	대표링크가 템플릿과 일치하지 않음
3046	ExceedMaxAdditionalContentLengthException	부가 정보 최대 길이 제한 오류
3047	ExceedMaxCommerceTitleLengthException	커머스 정보 상품명 최대 길이 제한 오류
3050	MessageNotSupportedUnsubscribeException	수신동의거부 스펙 (N 타입) 미지원
3051	InvalidateCarouselItemMinException or InvalidateCarouselItemMaxException	캐러셀 아이템 리스트 갯수 최소, 최대 갯수 불일치
3052	CarouselMessageLengthOverLimitException	캐러셀 아이템 메시지 길이 초과
3056	WideItemListTitleLengthOverLimitException	와이드 아이템 리스트 타이틀 길이 제한 오류
3058	CarouselHeaderLengthOverLimitException	캐러셀 헤더 길이 제한 오류
3059	MessageNotSupportedCouponException	쿠폰 스펙 미지원
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	예기치 못한 에러