알림톡 API
  • PDF

알림톡 API

  • PDF

기본 정보

API URL

https://sens.apigw.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.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",
    "scheduleCode": "string"
}
항목 Mandatory Type 설명 비고
plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
templateCode Mandatory String 템플릿 코드
messages Mandatory Object 메시지 정보 - 아래 항목 참조 (messages.XXX)
- 최대 100개
messages.countryCode Optional String 수신자 국가번호
messages.to Mandatory String 수신자번호
messages.title Optional String 알림톡 강조표시 내용 강조 표기 유형의 템플릿에서만 사용 가능
messages.content Mandatory String 알림톡 메시지 내용
messages.headerContent Optional String 알림톡 헤더 내용 - 아이템 리스트 유형의 템플릿에서만 사용 가능
- 최대 16자까지 입력 가능
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.messages.item.list Mandatory Array of Object 아이템 리스트 - 아이템리스트 유형의 템플릿에서만 사용 가능
- 최소 2개 이상, 최대 10개
messages.messages.item.list.title Mandatory String 아이템 리스트 제목 - 아이템리스트 유형의 템플릿에서만 사용 가능
- 최대 6자까지 입력 가능
messages.messages.item.list.description Mandatory String 아이템 리스트 설명 - 아이템리스트 유형의 템플릿에서만 사용 가능
- 최대 23자까지 입력 가능
messages.messages.summary Optional Object 아이템 요약 정보 아이템리스트 유형의 템플릿에서만 사용 가능
messages.messages.summary.title Mandatory String 아이템 요약 제목 - 아이템리스트 유형의 템플릿에서만 사용 가능
- 최대 6자까지 입력 가능
messages.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 또는 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 값 사용
scheduleCode Optional String 스케줄 코드 등록하려는 스케줄 코드
주의
  • 내용(content), 버튼(buttons)는 등록 및 검수 완료된 템플릿 규격에 맞추어 입력해야 합니다.
  • 템플릿 규격에 맞지 않는 메시지 발송 요청 시 메시지 발송에 실패합니다.
참고
  • 템플릿에 이미지가 등록된 경우 별도로 메시지 발송 시, 요청 body에 해당 내용을 넣지 않아도 등록된 이미지가 발송됩니다.
  • reserveTime, scheduleCode를 모두 요청하는 경우 예약 발송으로 처리됩니다. (예약 발송이 우선 순위가 높음)
  • SMS Failover는 알림톡 수신 결과 코드를 기준으로 성공이 아닌 경우 동작합니다.

템플릿 등록 및 검수에 대한 가이드는 웹 콘솔 설명서(구, 사용자 가이드)에서 확인할 수 있습니다. 템플릿 등록 가이드 바로가기

템플릿 버튼 정보

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 발송 요청 시간
statusCode Mandatory String 요청 상태 코드 - 성공: 202
- 실패: 그 외
- HTTP Status 규격을 따름
statusName Mandatory String 요청 상태명 - 성공: success
- 처리 중: processing
- 예약 중: reserved
- 스케줄 중: scheduled
- 실패: 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.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 요청 아이디 발송 요청 아이디

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",
                "requestStatusCode":"string",
                "requestStatusName":"string",
                "requestStatusDesc":"string"
            }
        }
    ]
}
항목 Mandatory Type 설명 비고
requestId Mandatory String 발송 요청 아이디
statusCode Mandatory String 요청 상태 코드 202 - 성공
그외 - 실패
* HTTP Status 규격을 따름
statusName Mandatory String 요청 상태명 success - 성공
processing - 발송중
reserved - 예약중
scheduled - 스케줄중
fail - 실패
messages.requestTime Mandatory DateTime 발송 요청 시간
messages.messageId Mandatory String 메시지 아이디
messages.countryCode Optional String 수신자 국가번호
messages.to Mandatory String 수신자번호
messages.content Mandatory String 알림톡 메시지 내용
messages.plusFriendId Mandatory String 카카오톡 채널명 ((구)플러스친구 아이디)
messages.templateCode Mandatory String 템플릿 코드
messages.completeTime Optional DateTime 발송 리포트(처리 완료) 시간
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.requestStatusCode Optional String SMS Failover 발송 요청 상태 코드 202 - 성공
그외 - 실패
* HTTP Status 규격을 따름
messages.failover.requestStatusName Optional String SMS Failover 발송 요청 상태명 success - 성공
fail - 실패
messages.failover.requestStatusDesc Optional String SMS Failover 발송 요청 상태 내용

응답 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.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 발송 요청 시간
completeTime Optional DateTime 발송 리포트(처리 완료) 시간
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 발송 요청 상태 코드 202 - 성공
그외 - 실패
* HTTP Status 규격을 따름
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.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

예약 메시지 취소

메시지 발송 예약을 취소합니다.

DELETE https://sens.apigw.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

스케줄 메시지

스케줄 메시지 취소

메시지 발송 스케줄을 취소합니다.

DELETE https://sens.apigw.ntruss.com/alimtalk/v2/services/{serviceId}/schedules/{scheduleCode}/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 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디
scheduleCode Mandatory String 스케줄 코드 스케줄 등록 시 사용한 코드
messageId 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.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: 100 (1 ~ 100 사이의 숫자만 입력 가능)
pageIndex Optional Integer 페이지 인덱스 default: 0

Headers

API Header 바로가기

요청 Body

없음

응답 Body

[
    {
        "createTime": "string",
        "updateTime": "string",
        "serviceId": "string",
        "channelId": "string",
        "channelName": "string",
        "channelStatus": "string",
        "useSmsFailover": "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 대체 발송 사용 여부

응답 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.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: 100 (1 ~ 100 사이의 숫자만 입력 가능)
pageIndex Optional Integer 페이지 인덱스 default: 0

Headers

API Header 바로가기

요청 Body

없음

응답 Body

[
    {
        "createTime": "string",
        "updateTime": "string",
        "channelId": "string",
        "templateCode": "string",
        "templateName": "string",
        "content": "string",
        "comments": [
            {
                "commentId": "string",
                "content": "string",
                "status": "string",
                "createTime": "string"
            }
        ],
        "templateInspectionStatus": "string",
        "templateStatus": "string",
        "buttons":[
                {
                    "order":"integer",
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string"
                }
            ]
    }
]
항목 Mandatory Type 설명 비고
createTime Mandatory String 생성 시간 format: LocalDateTime
updateTime Optional String 수정 시간 format: LocalDateTime
channelId Mandatory String 카카오톡 채널 아이디
templateCode Mandatory String 템플릿 코드
templateName Mandatory String 템플릿 이름
content Mandatory String 템플릿 내용
comments.commentId Mandatory String 검수 아이디
comments.content Mandatory String 검수 내용
comments.status Mandatory String 검수 상태 - 검수 완료: APR
- 검수 반려: REJ
comments.create Mandatory String 검수 시간
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 정보 참고
참고
  • 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자)
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 아이템 요약 정보의 디스크립션에 허용되지 않은 문자 포함(통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함)
4000 ResponseHistoryNotFoundException 메시지 전송 결과를 찾을 수 없음
4001 UnKnownMessageStatusError 알수 없는 메시지 상태
7011 - 시리얼 넘버 패턴 에러
7014 - 메시지 유효 시간 초과 에러
8512 - 수신자 타입 찾을 수 없음
8514 - request_id 찾을 수 없음
8520 - 지원하지 않는 상품 타입 오류
8521 - 지원하지 않는 메시지 타입 오류
8522 - 지원하지 않는 텍스트 유형 오류
8523 - 지원하지 않는 response method 오류
8530 - 수신자 목록 사이즈 오류
8999 - 내부 서버 오류
9998 현재 서비스를 제공하고 있지 않습니다. 시스템에 문제가 발생하여 담당자 확인 중
9999 시스템에 알 수 없는 문제 발생, 담당자 확인 중 시스템에 문제가 발생하여 담당자 확인 중

이 문서가 도움이 되었습니까?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.