알림톡 API
    • PDF

    알림톡 API

    • PDF

    기사 요약

    기본 정보

    API URL

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

    API Header

    항목Mandatory설명
    Content-TypeMandatory요청 Body Content Type을 application/json으로 지정 (POST)
    x-ncp-apigw-timestampMandatory1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타낸 것으로 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
    x-ncp-iam-access-keyMandatory포탈이나 Sub Account에서 발급받은 Access Key ID
    x-ncp-apigw-signature-v2Mandatory위 예제의 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

    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"
    }
    
    항목MandatoryType설명비고
    plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
    templateCodeMandatoryString템플릿 코드
    messagesMandatoryObject메시지 정보아래 항목들 참조 (messages.XXX)
    최대 100개
    messages.countryCodeOptionalString수신자 국가번호default: 82
    messages.toMandatoryString수신자번호
    messages.titleOptionalString알림톡 강조표시 내용강조표기 유형의 템플릿에서만 사용 가능
    messages.contentMandatoryString알림톡 메시지 내용
    messages.headerContentOptionalString알림톡 헤더 내용아이템리스트 유형의 템플릿에서만 사용 가능
    - 16 bytes 미만 까지 입력 가능
    messages.itemHighlightOptionalObject아이템 하이라이트아이템리스트 유형의 템플릿에서만 사용 가능
    messages.itemHighlight.titleMandatoryString아이템 하이라이트 제목아이템리스트 유형의 템플릿에서만 사용 가능
    이미지가 없는 경우
    - 최대 30자까지 입력 가능 (2줄)
    - 1줄은 15자까지 입력 가능
    이미지가 있는 경우
    - 최대 21자까지 입력 가능 (2줄)
    - 1줄은 10자까지 입력 가능
    - 2줄 초과 시 말줄임 처리
    messages.itemHighlight.descriptionMandatoryString아이템 하이라이트 설명아이템리스트 유형의 템플릿에서만 사용 가능
    이미지가 없는 경우
    - 최대 19자까지 입력 가능 (1줄)
    이미지가 있는 경우
    - 최대 13자까지 입력 가능 (1줄)
    - 1줄 초과 시 말줄임 처리
    messages.itemOptionalObject아이템 리스트아이템리스트 유형의 템플릿에서만 사용 가능
    messages.item.listMandatoryArray of Object아이템 리스트아이템리스트 유형의 템플릿에서만 사용 가능
    - 최소 2개 이상, 최대 10개
    messages.item.list.titleMandatoryString아이템 리스트 제목아이템리스트 유형의 템플릿에서만 사용 가능
    - 최대 6자까지 입력 가능
    messages.item.list.descriptionMandatoryString아이템 리스트 설명아이템리스트 유형의 템플릿에서만 사용 가능
    - 최대 23자까지 입력 가능
    messages.summaryOptionalObject아이템 요약 정보아이템리스트 유형의 템플릿에서만 사용 가능
    messages.summary.titleMandatoryString아이템 요약 제목아이템리스트 유형의 템플릿에서만 사용 가능
    - 최대 6자까지 입력 가능
    messages.summary.descriptionMandatoryString아이템 요약 설명아이템리스트 유형의 템플릿에서만 사용 가능
    - 허용되는 문자: 통화기호(유니코드 통화기호, 元, 円, 원), 통화코드 (ISO 4217), 숫자, 콤마, 소수점, 공백
    - 소수점 2자리까지 허용
    - 최대 23자까지 입력 가능
    messages.buttonsOptionalArray of Object알림톡 메시지 버튼아래 템플릿 버튼 정보 참조
    messages.buttons.typeMandatoryString버튼 Type아래 템플릿 버튼 정보 참조
    messages.buttons.nameMandatoryString버튼명아래 템플릿 버튼 정보 참조
    messages.useSmsFailoverOptionalBooleanSMS Failover 사용 여부Failover가 설정된 카카오톡 채널에서만 사용 가능
    기본: 카카오톡 채널의 Failover 설정 여부를 따름
    messages.failoverConfigOptionalObjectFailover 설정아래 항목들 참조
    messages.failoverConfig.typeOptionalStringFailover SMS 메시지 TypeSMS or LMS
    기본: content 길이에 따라 자동 적용 (90 bytes 이하 SMS, 초과 LMS)
    messages.failoverConfig.fromOptionalStringFailover SMS 발신번호기본: Failover 설정 시 선택한 발신번호
    승인되지 않은 발신번호 사용시, Failover 동작 안함
    messages.failoverConfig.subjectOptionalStringFailover SMS 제목LMS type으로 동작할 때 사용
    기본: 카카오톡 채널명
    messages.failoverConfig.contentOptionalStringFailover SMS 내용기본: 알림톡 메시지 내용 (버튼 제외)
    reserveTimeOptionalString예약 일시메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
    reserveTimeZoneOptionalString예약 일시 타임존예약 일시 타임존 (기본: Asia/Seoul)
    * 지원 타임존 목록
    * TZ database name 값 사용
    주의
    • 요청 Body의 Mandatory 필드를 사용하시는 경우, 공백은 허용되지않습니다. (추가하는 경우에만 해당)
    • 내용(content), 버튼(buttons)는 등록 및 검수 완료된 템플릿 규격에 맞추어 입력해야 합니다.
    • 템플릿 규격에 맞지 않는 메시지 발송 요청 시, 메시지 발송에 실패합니다.
    참고
    • 템플릿에 이미지가 등록된 경우, 별도로 메시지 발송 시, 요청 body에 해당 내용을 넣지 않아도 등록된 이미지가 발송됩니다.
    • SMS Failover는 알림톡 수신 결과 코드 기준, 성공이 아닌 경우 동작하며, prefix로 B가 붙은 코드들에 대해서는 failover 기능을 통한 SMS 대체 발송이 이루어지지 않습니다.

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

    템플릿 버튼 정보

    TypeNameMandatory 항목
    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 ExpressTNTExpress
    TNT택배
    TNT Express
    숫자 8~9자리
    USPSUSPS숫자 10자리 또는 숫자 22자리 또는 대문자 알파벳 2자리 + 숫자 9자리 + 대문자 알파벳 2자리
    (구분자 없음)
    EMSEMS대문자 알파벳 2자리 + 숫자 9자리 + 대문자 알파벳 2자리
    (구분자 없음)
    DHLDHL숫자 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"
            }
        ]
    }
    
    항목MandatoryType설명비고
    requestIdMandatoryString발송 요청 아이디
    requestTimeMandatoryDateTime발송 요청 시간yyyy-MM-dd'T'HH:mm:ss.SSS
    statusCodeMandatoryString요청 상태 코드202 - 성공
    그외 - 실패
    * HTTP Status 규격을 따름
    statusNameMandatoryString요청 상태명success - 성공
    processing - 처리중
    reserved - 예약중
    fail - 실패
    messages.messageIdMandatoryString메시지 아이디
    messages.countryCodeOptionalString수신자 국가번호
    messages.toMandatoryString수신자번호
    messages.contentMandatoryString알림톡 메시지 내용
    messages.requestStatusCodeMandatoryString발송요청 상태 코드A000 - 성공
    그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
    messages.requestStatusNameMandatoryString발송요청 상태명success - 성공
    fail - 실패
    messages.requestStatusDescMandatoryString발송요청 상태 내용
    messages.useSmsFailoverMandatoryBooleanSMS Failover 사용 여부

    응답 Status

    HTTP StatusDesc
    202Accepted (발송 요청 완료)
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    500Internal 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

    Parameters

    항목MandatoryType설명비고
    requestIdMandatoryString요청 아이디발송 요청 아이디
    plusFriendIdMandatoryString카카오 채널등록된 채널 명
    requestStartTimeMandatoryString조회 시간 시작 시각yyyy-MM-dd'T'HH:mm:ss
    requestEndTimeMandatoryString조회 시간 종료 시각yyyy-MM-dd'T'HH:mm:ss
    completeStartTimeMandatoryString발송 완료 시작 시간yyyy-MM-dd'T'HH:mm:ss
    completeEndTimeMandatoryString발송 완료 종료 시간yyyy-MM-dd'T'HH:mm:ss
    messageIdOptionalString메시지 아이디
    requestStatusNameOptionalString요청 상태success, fail
    messageStatusNameOptionalString요청 상태success, processing, fail
    templateCodeOptionalString템플릿 코드등록된 템플릿 코드
    toOptionalString메세지 수신 번호붙임표 (-)를 제외한 번호
    pageIndexOptionalInteger페이지 번호default: 0
    pageSizeOptionalInteger페이지 크기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

    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",
        "pageIndex": "integer",
        "itemCount": "integer",
        "hasMore": "boolean"
    }
    
    항목MandatoryType설명비고
    requestIdOptionalString발송 요청 아이디requestId로 조회하는 경우에만 노출됨
    statusCodeMandatoryString요청 상태 코드202 - 성공
    그외 - 실패
    * HTTP Status 규격을 따름
    statusNameMandatoryString요청 상태명success - 성공
    processing - 발송중
    reserved - 예약중
    fail - 실패
    messages.requestTimeMandatoryDateTime발송 요청 시간yyyy-MM-dd'T'HH:mm:ss.SSS
    messages.messageIdMandatoryString메시지 아이디
    messages.countryCodeOptionalString수신자 국가번호default: 82
    messages.toMandatoryString수신자번호
    messages.contentMandatoryString알림톡 메시지 내용
    messages.plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
    messages.templateCodeMandatoryString템플릿 코드
    messages.completeTimeOptionalDateTime발송 리포트(처리 완료) 시간yyyy-MM-dd'T'HH:mm:ss
    messages.requestStatusCodeMandatoryString발송요청 상태 코드A000 - 성공
    그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
    messages.requestStatusNameMandatoryString발송요청 상태명success - 성공
    fail - 실패
    messages.requestStatusDescMandatoryString발송요청 상태 내용
    messages.messageStatusCodeMandatoryString발송결과 상태 코드0000 - 성공
    그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
    messages.messageStatusNameMandatoryString발송결과 상태명success - 성공
    processing - 처리중
        * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태
        * messageCode, messageDesc가 조회되지 않음
    fail - 실패
    messages.messageStatusDescMandatoryString발송결과 상태 내용
    messages.useSmsFailoverMandatoryBooleanSMS Failover 사용 여부
    messages.failoverOptionalObjectSMS Failover
    messages.failover.smsServiceIdOptionalStringSMS Failover 서비스 아이디
    messages.failover.requestIdOptionalStringSMS Failover 발송 요청 아이디
    messages.failover.messageIdOptionalStringSMS Failover 발송 메시지 아이디
    messages.failover.requestStatusCodeOptionalStringSMS Failover 발송 요청 상태 코드오류 코드 표 참고
    messages.failover.requestStatusNameOptionalStringSMS Failover 발송 요청 상태명success - 성공
    fail - 실패
    messages.failover.requestStatusDescOptionalStringSMS Failover 발송 요청 상태 내용
    messages.failover.messageStatusOptionalStringSMS Failover 발송 처리 상태READY: 대기
    PROCESSING: 처리 중
    COMPLETED: 처리 완료
    messages.failover.messageStatusCodeOptionalStringSMS Failover 발송 단말 수신 상태 결과 코드오류 코드 표 참고
    messages.failover.messageStatusNameOptionalStringSMS Failover 발송 단말 수신 결과명
    messages.failover.messageStatusDescOptionalStringSMS Failover 발송 단말 수신 내용
    pageSizeMandatoryInteger페이지 사이즈
    pageIndexMandatoryInteger페이지 인덱스 (0부터 시작)
    itemCountMandatoryInteger조회한 페이지 내의 메시지 수
    hasMoreMandatoryBoolean다음 페이지 존재 여부
    참고
    • 조회 조건에 requestId가 포함되어있지않은 경우, requestId는 포함되지 않습니다.

    응답 Status

    HTTP StatusDesc
    200OK (조회 완료)
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    500Internal 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
    messageIdMandatoryString메시지 아이디메시지 발송시 반환되는 메시지 식별자

    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"
        }
    }
    
    항목MandatoryType설명비고
    messageIdMandatoryString메시지 아이디
    requestIdMandatoryString발송 요청 아이디
    requestTimeMandatoryDateTime발송 요청 시간yyyy-MM-dd'T'HH:mm:ss.SSS
    completeTimeOptionalDateTime발송 리포트(처리 완료) 시간yyyy-MM-dd'T'HH:mm:ss
    plusFriendIdMandatoryString카카오톡 채널명 ((구)플러스친구 아이디)
    templateCodeMandatoryString템플릿 코드
    countryCodeOptionalString수신자 국가번호
    toMandatoryString수신자번호
    contentMandatoryString알림톡 메시지 내용
    requestStatusCodeMandatoryString발송요청 상태 코드A000 - 성공
    그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
    requestStatusNameMandatoryString발송요청 상태명success - 성공
    fail - 실패
    requestStatusDescMandatoryString발송요청 상태 내용
    messageStatusCodeMandatoryString발송결과 상태 코드0000 - 성공
    그외 코드 - 실패(Desc 항목에 실패 사유가 명시)
    messageStatusNameMandatoryString발송결과 상태명success - 성공
    processing - 처리중
        * 발송요청 성공 후, 메시지 발송서버에서 처리중인 상태
        * messageCode, messageDesc가 조회되지 않음
    fail - 실패
    messageStatusDescMandatoryString발송결과 상태 내용
    messages.useSmsFailoverMandatoryBooleanSMS Failover 사용 여부
    messages.failoverOptionalObjectSMS Failover 사용 여부
    messages.failover.smsServiceIdOptionalStringSMS Failover 서비스 아이디
    messages.failover.requestIdOptionalStringSMS Failover 발송 요청 아이디
    messages.failover.requestStatusCodeOptionalStringSMS Failover 발송 요청 상태 코드오류 코드 표 참고
    messages.failover.requestStatusNameOptionalStringSMS Failover 발송 요청 상태명success - 성공
    fail - 실패
    messages.failover.requestStatusDescOptionalStringSMS Failover 발송 요청 상태 내용
    messages.failover.messageIdOptionalStringSMS Failover 발송 메시지 아이디
    messages.failover.messageStatusOptionalStringSMS Failover 발송 처리 상태READY: 대기
    PROCESSING: 처리 중
    COMPLETED: 처리 완료
    messages.failover.messageStatusCodeOptionalStringSMS Failover 발송 단말 수신 상태 결과 코드오류 코드 표 참고
    messages.failover.messageStatusNameOptionalStringSMS Failover 발송 단말 수신 결과명
    messages.failover.messageStatusDescOptionalStringSMS Failover 발송 단말 수신 내용

    Failover 요청 상태 코드

    requestStatusCodeDesc
    0성공
    E4000failover 설정이 유효하지 않음
    E4001failover 설정 정보가 누락됨
    E4002failover SMS 서비스가 설정되지 않음
    E4003failover SMS type(SMS, LMS)이 설정되지 않음
    E4004failover SMS 발신번호가 설정되지 않음
    E4005failover SMS 제목이 설정되지 않음
    E4006failover SMS 내용이 설정되지 않음
    E4007failover SMS 수신번호가 설정되지 않음
    E4008failover SMS 서비스가 사용 가능한 상태가 아님
    E4009failover SMS 발신번호가 인증되지 않음
    E4010failover SMS 080무료수신거부 서비스가 사용 가능한 상태가 아님
    E4999failover 설정 파싱 오류 (고객 지원으로 문의 필요)
    E5000내부 오류 (고객 지원으로 문의 필요)

    응답 Status

    HTTP StatusDesc
    200OK (조회 완료)
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    500Internal 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
    reserveIdMandatoryString예약 메시지 아이디예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

    Headers

    API Header 바로가기

    요청 Body

    없음
    

    응답 Body

    {
      "reserveId": "string",
      "reserveTimeZone": "string",
      "reserveTime": "string",
      "reserveStatus": "string"
    }
    
    항목MandatoryType설명비고
    reserveIdMandatoryString예약 메시지 아이디예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)
    reserveTimeMandatoryString예약 일시메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
    reserveTimeZoneMandatoryString예약 일시 타임존예약 일시 타임존 (기본: Asia/Seoul)
    * 지원 타임존 목록
    * TZ database name 값 사용
    reserveStatusMandatoryString예약 상태READY - 발송 대기
    PROCESSING - 발송 요청중
    CANCELED - 발송 취소
    FAIL - 발송 요청 실패
    DONE - 발송 요청 성공
    STALE - 발송 요청 실패 (시간 초과)

    응답 Status

    HTTP StatusDesc
    200OK (조회 완료)
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    500Internal 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
    reserveIdMandatoryString예약 메시지 아이디예약 발송 요청 조회 시 반환되는 메시지 식별자(requestId)

    Headers

    API Header 바로가기

    요청 Body

    없음
    

    응답 Body

    없음
    

    응답 Status

    HTTP StatusDesc
    204No Content (삭제 완료)
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    500Internal 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

    Parameters

    항목MandatoryType설명비고
    pageSizeOptionalInteger페이지 사이즈default: 20 (1 ~ 100 사이의 숫자만 입력 가능)
    pageIndexOptionalInteger페이지 인덱스default: 0

    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"
        }
    ]
    
    항목MandatoryType설명비고
    createTimeMandatoryString생성 시간format: LocalDateTime
    updateTimeOptionalString수정 시간format: LocalDateTime
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디
    channelIdMandatoryString카카오톡 채널 아이디
    channelNameMandatoryString카카오톡 채널 이름
    channelStatusMandatoryString카카오톡 채널 상태- 정상: ACTIVE
    - 삭제: DELETED
    - 영구 삭제 중: DELETING_PERMANENTLY
    - 영구 삭제: PERMANENTLY_DELETED
    - 차단: BLOCKED
    - 삭제 지연 중: PENDING_DELETE
    useSmsFailoverMandatoryBooleanSMS 대체 발송 사용 여부
    failoverServiceIdOptionalStringFailover SMS 서비스ID
    failoverTelNoOptionalStringFailover 발신번호
    isBlockMandatoryBoolean채널 차단 여부
    isDormantMandatoryBoolean채널 휴면 전환 여부

    응답 Status

    HTTP StatusDesc
    200OK
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    429Too Many Requests
    500Internal 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

    항목MandatoryType설명비고
    serviceIdMandatoryString서비스 아이디프로젝트 등록 시 발급받은 서비스 아이디

    Parameters

    • channelId는 필수 값이며, templateCode 사용 시 템플릿에 대한 상세정보를 반환합니다.
    • comments를 비롯한 부가 정보들은 상세 조회시에만 노출됩니다.
    항목MandatoryType설명비고
    channelIdMandatoryString채널 아이디카카오톡에 등록된 채널 아이디
    templateCodeMandatoryString템플릿 코드templateCode를 사용하여 조회 시 상세 조회 결과 반환
    등록된 템플릿 코드
    templateNameOptionalString템플릿 이름like 조회 결과를 반환
    pageSizeOptionalInteger페이지 사이즈default: 20 (1 ~ 100 사이의 숫자만 입력 가능)
    pageIndexOptionalInteger페이지 인덱스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"
        }
    ]
    
    항목MandatoryType설명비고
    createTimeMandatoryString생성 시간format: LocalDateTime
    updateTimeOptionalString수정 시간format: LocalDateTime
    channelIdMandatoryString카카오톡 채널 아이디
    templateCodeMandatoryString템플릿 코드
    templateNameMandatoryString템플릿 이름
    categoryCodeMandatoryString템플릿 카테고리 코드
    categoryNameMandatoryString템플릿 카테고리 이름
    messageTypeMandatoryString템플릿 메시지 유형- BA: 기본형
    - EX: 부가 정보형
    - AD: 광고 추가형
    - MI: 복합형
    emphasizeTypeMandatoryString템플릿 강조 유형- NONE :기본형
    - TEXT: 강조표기형
    - IMAGE: 이미지형
    - ITEM_LIST: 아이템리스트형
    contentMandatoryString템플릿 내용
    adContentOptionalString광고성 메시지
    extraContentOptionalString부가 정보
    titleOptionalString강조표기형 제목
    additionalTitleOptionalString강조표기형 추가 제목
    comments.commentIdMandatoryString검수 아이디
    comments.contentMandatoryString검수 내용
    comments.statusMandatoryString검수 상태- 검수 완료: APR
    - 검수 반려: REJ
    comments.createMandatoryString검수 시간
    comments.attachmentOptionalObject검수 문의하기 첨부파일
    comments.attachment.fileNameMandatoryString파일 이름
    comments.attachment.fileUrlMandatoryString파일 URL
    templateInspectionStatusMandatoryString템플릿 검수 상태- 수락: ACCEPT
    - 등록: REGISTER
    - 검수 중: INSPECT
    - 완료: COMPLETE
    - 반려: REJECT
    templateStatusMandatoryString템플릿 상태- 정상: ACTIVE
    - 대기: READY
    - 정지: STOP
    buttonsOptionalArray of Object알림톡 메시지 버튼상위 템플릿 버튼 정보 참조
    buttons.orderMandatoryInteger버튼 순서버튼 등록 순서
    buttons.typeMandatoryString버튼 Type상위 템플릿 버튼 정보 참조
    buttons.nameMandatoryString버튼명상위 템플릿 버튼 정보 참조
    buttons.linkMobileOptionalString버튼 mobile link등록된 template button 정보 참고
    buttons.linkPcOptionalString버튼 pc link등록된 template button 정보 참고
    buttons.schemeIosOptionalString버튼 ios scheme등록된 template button 정보 참고
    buttons.schemeAndroidOptionalString버튼 adnroid scheme등록된 template button 정보 참고
    titleOptionalString강조표시형 제목
    additionalTitleOptionalString강조표시형 추가 제목
    useImageMandatoryBoolean이미지 사용 여부
    imageNameOptionalString이미지 이름
    imageUrlOptionalString이미지 URL
    useHeaderContentMandatoryBoolean헤더 사용 여부
    headerContentOptionalString헤더 내용
    useItemHighlightMandatoryBoolean아이템 하이라이트 사용여부
    useItemHighlightImageMandatoryBoolean아이템 하이라이트 이미지 사용여부
    itemHighlightOptionalObject아이템 하이라이트아이템 하이라이트 사용시에만 노출
    itemHighlight.titleOptionalString아이템 하이라이트 제목
    itemHighlight.descriptionOptionalString아이템 하이라이트 내용
    itemHighlight.imageUrlOptionalString아이템 하이라이트 이미지 URL
    itemOptionalObject아이템아이템 사용시에만 노출
    item.listOptionalString아이템 리스트아이템 리스트 사용시에만 노출
    item.list.titleOptionalString아이템 명
    item.list.descriptionOptionalString아이템 내용
    item.summaryOptionalString아이템 요약 정보아이템 요약정보 사용시에만 노출
    item.summary.titleOptionalString아이템 요약정보 명
    item.summary.descriptionOptionalString아이템 요약정보 내용
    securityFlagMandatoryBoolean보안 설정 여부
    isBlockMandatoryBoolean템플릿 차단 여부
    isDormantMandatoryBoolean템플릿 휴면 전환 여부
    참고
    • channelId는 필수 값이며 templateCode 사용 시 템플릿에 대한 상세 정보를 반환합니다.
    • comments를 비롯한 부가 정보는 상세 조회 시에만 노출됩니다.

    응답 Status

    HTTP StatusDesc
    200OK
    400Bad Request
    401Unauthorized
    403Forbidden
    404Not Found
    429Too Many Requests
    500Internal Server Error

    오류 코드

    알림톡 수신 결과 코드

    StatusError textDesc
    0000-정상 발송
    1001NoJsonBodyRequest Body가 Json형식이 아님
    1002InvalidHubPartnerKey파트너 키가 유효하지 않음
    1003InvalidSenderKey발신 프로필 키가 유효하지 않음
    1004NoValueJsonElementRequest BODY(Json)에서 name을 찾을 수 없음
    1005SenderNotFound발신프로필을 찾을 수 없음
    1006DeletedSender삭제된 발신 프로필
    1007StoppedSender차단 상태의 발신 프로필
    1011ContractNotFound계약 정보를 찾을 수 없음
    1012InvalidUserKeyException잘못된 형식의 유저 키 요청
    1013InvalidAppLink유효하지 않은 app연결
    1014InvalidBizNum유효하지 않은 사업자번호
    1015TalkUserIdNotFonud유효하지 않은 app user id 요청
    1016BizNumNotEqual사업자등록번호 불일치
    1020InvalidReceiveUserException올바른 유저 식별자 값이 하나도 없는 경우
    1021BlockedProfile차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
    1022DeactivatedProfile닫힘 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
    1023DeletedProfile삭제된 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
    1024DeletingProfile삭제대기 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
    1025SpammedProfile메시지차단 상태의 카카오톡 채널 (카카오톡 채널 운영툴에서 확인)
    1026UnableUseMessageType해당 msg_type 에서 사용할 수 없는 response_method 로 요청 (이미지알림톡(AI)는 realtime 으로 발송 불가)
    1030InvalidParameterException잘못된 파라메터 요청
    1033-템플릿 타입과 메시지타입 불일치
    2003FailedToSendMessageByNoFriendshipException메시지 전송 실패 (테스트 서버에서 카카오톡 채널을 추가하지 않은 경우)
    2004FailedToMatchTemplateException템플릿 일치 확인 시 오류 발생 (카카오 내부 오류)
    2006FailedToMatchSerialNumberPrefixPattern시리얼넘버 형식 불일치
    3000UnexceptedExcetpion예기치 않은 오류 발생
    3005AckTimeoutException메시지를 발송 했으나, 수신확인 안됨 (성공 불 확실)
    3006FailedToSendMessageException카카오 내부 시스템 오류로 메시지 전송 실패
    3008InvalidPhoneNumberException전화번호 오류
    3010JsonParsseExcetpionJson 파싱 오류
    3011MessageNotFoundException메시지가 존재하지 않음
    3012SerialNumberDuplicatedException메시지 일련번호가 중복됨 (메시지 일련 번호는 고유의 값이 부여되어야 함)
    3013MessageEmptyException빈 메시지
    3014MessageLengthOverLimitException메시지 길이 제한 오류 (텍스트 타입 1000자 초과, 이미지 타입 400자 초과)
    3015TemplateNotFoundException템플릿을 찾을 수 없음
    3016NoMatchedTemplateException메시지 내용이 템플릿과 일치하지 않음
    3018NoSendAvailableException메시지를 전송할 수 없음
    3020SeenInfoNotFoundException메시지 확인 정보를 찾을 수 없음
    3022NoSendAvailableTimeException메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 08시~ 20시까지 발송 가능)
    3024MessageInvaildImageException메시지에 포함된 이미지를 전송할 수 없음
    3025ExceedMaxVariableLengthException변수 글자수 제한 초과
    3026Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})'상담/봇 전환 버튼 extra, event 글자수 제한 초과
    3027NoMatchedTemplateButtonException버튼 내용이 템플릿과 일치 하지 않음
    3028NoMatchedTemplateTitleException메시지 강조 표기 타이틀이 템플릿과 일치하지 않음
    3029ExceedMaxTitleLengthException메시지 강조 표기 타이틀 길이 제한 초과 (50자)
    3031-텍스트 유형 불일치
    3030NoMatchedTemplateWithMessageTypeException메시지 타입과 템플릿 강조유형이 일치하지 않음
    3031NoMatchedTemplateHeaderException헤더가 템플릿과 일치하지 않음
    3032ExceedMaxHeaderLengthException헤더 길이 제한 초과(16 자)
    3033NoMatchedTemplateItemHighlightException아이템 하이라이트가 템플릿과 일치하지 않음
    3034ExceedMaxItemHighlightTitleLengthException아이템 하이라이트 타이틀 길이 제한 초과(이미지 없는 경우 30 자, 이미지 있는 경우 21 자)
    3035ExceedMaxItemHighlightDescriptionLengthException아이템 하이라이트 디스크립션 길이 제한 초과(이미지 없는 경우 19 자, 이미지 있는 경우 14 자)
    3036NoMatchedTemplateItemListException아이템 리스트가 템플릿과 일치하지 않음
    3037ExceedMaxItemDescriptionLengthException아이템 리스트의 아이템의 디스크립션 길이 제한 초과(23 자)
    3038NoMatchedTemplateItemSummaryException아이템 요약정보가 템플릿과 일치하지 않음
    3039ExceedMaxItemSummaryDescriptionLengthException아이템 요약정보의 디스크립션 길이 제한 초과(14 자)
    3040InvalidItemSummaryDescriptionException아이템 요약정보의 디스크립션에 허용되지 않은 문자 포함(통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함)
    4000ResponseHistoryNotFoundException메시지 전송 결과를 찾을 수 없음
    4001UnKnownMessageStatusError알수 없는 메시지 상태
    7011-시리얼 넘버 패턴 에러
    7014-메시지 유효 시간 초과 에러
    8512-수신자 타입 찾을 수 없음
    8514-request_id 찾을 수 없음
    8520-지원하지 않는상품 타입 오류
    8521-지원하지 않는 메시지 타입 오류
    8522-지원하지 않는 텍스트 유형 오류
    8523-지원하지 않는 response method 오류
    8530-수신자 목록 사이즈 오류
    8999-내부 서버 오류
    9998현재 서비스를 제공하고 있지 않습니다.시스템에 문제가 발생하여 담당자가 확인하고 있는 경우
    9999시스템에 알수 없는 문제 발생, 담당자 확인중시스템에 문제가 발생하여 담당자 확인중
    B000Prepare to relay failed중계사 발송을 위한 사전 작업 실패
    B001Request to relay failed중계사 발송 실패
    B002Filtering for request to relay failed잘못된 요청으로 인해 필터링됨
    B003Invalid phone number format올바르지 않은 발신번호 포멧
    B004Quota Exceed쿼터 초과
    B005Message processing timeout exceed메시지 요청 시간과 처리 시간의 차이가 허용 범위를 벗어남
    B400Invalid Request메시지 형식 오류
    B999Unexpected server error예기치 못한 에러

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

    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.