알림톡 API v2 가이드

기본 정보

API URL

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

Simple & Easy Notification Service 알림톡 API v2 Swagger 바로가기

API Header

항목 Mandotory 설명
Content-Type Mandatory 요청 Body Content Type을 application/json으로 지정 (POST)
x-ncp-apigw-timestamp Mandatory 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(millisecond)로 나타낸 것이다.
APIGW 서버와 시간차가 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 사용

 

메시지

메시지 발송

메시지를 발송합니다. Swagger 바로가기

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

항목 Mandotory 타입 설명 비고
serviceId Mandatory String 서비스 아이디 프로젝트 등록 시 발급받은 서비스 아이디

Headers

API Header 바로가기

요청 Body

{
    "plusFriendId":"string",
    "templateCode":"string",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string"
                }
            ]
        }
    ],
    "reserveTime": "yyyy-MM-dd HH:mm",
    "reserveTimeZone": "string",
    "scheduleCode": "string"
}
항목 Mandatory 타입 설명 비고
plusFriendId Mandatory String 플러스친구 아이디
templateCode Mandatory String 템플릿 코드
messages Mandatory Object 메시지 정보 아래 항목들 참조 (messages.XXX)
최대 100개
messages.countryCode Optional String 수신자 국가번호
messages.to Mandatory String 수신자번호
messages.content Mandatory String 알림톡 메시지 내용
messages.buttons Optional Array of Object 알림톡 메시지 버튼 아래 템플릿 버튼 정보 참조
messages.buttons.type Mandatory String 버튼 Type 아래 템플릿 버튼 정보 참조
messages.buttons.name Mandatory String 버튼명 아래 템플릿 버튼 정보 참조
reserveTime Optional String 예약 일시 메시지 발송 예약 일시 (yyyy-MM-dd HH:mm)
reserveTimeZone Optional String 예약 일시 타임존 예약 일시 타임존 (기본: Asia/Seoul)
* 지원 타임존 목록
* TZ database name 값 사용
scheduleCode Optional String 스케줄 코드 등록하려는 스케줄 코드
  • 내용(content), 버튼(buttons)는 등록 및 검수 완료된 템플릿 규격에 맞추어 입력해야합니다.
  • 템플릿 규격에 맞지 않는 메시지 발송 요청시, 메시지 발송에 실패합니다.
  • reserveTime, scheduleCode를 모두 요청하는 경우 예약 발송으로 처리됩니다. (예약발송이 우선순위가 높음)

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

템플릿 버튼 정보

타입 명칭 Mandatory 항목
DS 배송 조회
WL 웹 링크 linkMobile, linkPc (http:// 또는 https://로 시작하는 URL)
AL 앱 링크 schemeIos, schemeAndroid
BK 봇 키워드
MD 메시지 전달

응답 Body

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string",
    "messages":[
        {
            "messageId":"string",
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "requestStatusCode":"string",
            "requestStatusName":"string",
            "requestStatusDesc":"string"
        }
    ]
}
항목 Mandatory 타입 설명 비고
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 발송요청 상태 내용

응답 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 요청 아이디 발송 요청 아이디

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"
        }
    ]
}
항목 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 발송결과 상태 내용

응답 Status

HTTP Status Desc
200 OK (조회 완료)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

메시지 발송 결과 조회

메시지 발송 결과를 조회합니다. Swagger 바로가기

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

항목 Mandotory 타입 설명 비고
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"
}
항목 Mandatory 타입 설명 비고
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 - 성공
fail - 실패
messageStatusDesc Mandatory String 발송결과 상태 내용

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

 

스케줄 메시지

스케줄 메시지 취소

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

DELETE https://sens.apigw.gov-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
아쉬운 점이 있다면 이야기해 주세요.
0/5000
내용을 입력해 주세요
의견 보내기

참여해 주셔서 고맙습니다!

여러분의 의견을 귀기울여 듣고 개선해 나가겠습니다.