---
title: "메시지 발송 결과 조회"
slug: "sens-brandmessage-get"
updated: 2026-04-23T08:55:50Z
published: 2026-04-23T09:02:20Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 메시지 발송 결과 조회

Classic/VPC 환경에서 이용 가능합니다.

브랜드 메시지의 메시지 발송 결과를 조회합니다.

## 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| GET | /brandmessage/v2/services/{serviceId}/messages/{messageId} |

### 요청 헤더

Simple & Easy Notification Service API에서 공통으로 사용하는 헤더에 대한 정보는 [Simple & Easy Notification Service 요청 헤더](/docs/sens-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

### 요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `serviceId` | String | Required | Biz Message 서비스 아이디 - [프로젝트 목록 조회](/docs/sens-project-list) 참조 |
| `messageId` | String | Required | 메시지 아이디 - [메시지 발송 목록 조회](/docs/sens-brandmessage-list) 참조 |

### 요청 예시

요청 예시는 다음과 같습니다.

```
curl --location --request GET 'https://sens.apigw.ntruss.com/brandmessage/v2/services/ncp:kkobizmsg:kr:27*********6:sens/messages/27577f08-****-****-****-471033372652' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
```

## 응답

응답 형식을 설명합니다.

### 응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | - | 요청 아이디 |
| `messageId` | String | - | 메시지 아이디 |
| `requestTime` | String | - | 요청 일시 - YYYY-MM-DDTHH:mm:ss.sss 형식 |
| `completeTime` | String | - | 완료 일시 - YYYY-MM-DDTHH:mm:ss 형식 |
| `plusFriendId` | String | - | 채널 아이디 |
| `messageType` | String | - | 메시지 타입 - `TEXT` \| `IMAGE` \| `WIDE_IMAGE` \| `WIDE_ITEM_LIST` \| `COMMERCE` \| `CAROUSEL_COMMERCE` \| `CAROUSEL_FEED` \| `PREMIUM_VIDEO` - `TEXT`: 텍스트 - `IMAGE`: 이미지형 - `WIDE_IMAGE`: 와이드 이미지형 - `WIDE_ITEM_LIST`: 와이드 리스트형 - `COMMERCE`: 커머스형 - `CAROUSEL_COMMERCE`: 캐러셀 커머스형 - `CAROUSEL_FEED`: 캐러셀 피드형 - `PREMIUM_VIDEO`: 프리미엄 동영상형 |
| `templateCode` | String | - | 메시지 템플릿 코드 |
| `countryCode` | String | - | 국가 코드 |
| `to` | String | - | 수신 번호 |
| `content` | String | - | 메시지 내용 |
| `requestStatusCode` | String | - | 요청 상태 코드 - `A000`: 성공 - 그 외: 실패 |
| `requestStatusName` | String | - | 요청 상태 - `success` \| `fail` - `success`: 성공 - `fail`: 실패 |
| `requestStatusDesc` | String | - | 요청 상태 설명 |
| `messageStatusCode` | String | - | 수신 상태 코드 - `0000`: 성공 - 그 외: 실패 |
| `messageStatusName` | String | - | 수신 상태 - `success` \| `processing` \| `fail` - `success`: 성공 - `processing`: 처리중. `messageStatusCode`와 `messageStatusDesc`가 표시되지 않음 - `fail`: 실패 |
| `messageStatusDesc` | String | - | 수신 상태 설명 |
| `useSmsFailover` | Boolean | - | SMS 대체 발송 사용 여부 - `true` \| `false` - `true`: 사용 - `false`: 사용 안 함 |
| `failover` | Object | - | SMS 대체 발송 정보 - 대체 발송이 실행된 경우, 표시 |
| `failover.smsServiceId` | String | - | 대체 발송에 사용된 SMS 서비스 아이디 |
| `failover.requestId` | String | - | 대체 발송 요청 아이디 |
| `failover.messageId` | String | - | 대체 발송 메시지 아이디 |
| `failover.requestStatusCode` | String | - | [SMS 대체 발송 요청 상태 코드](/docs/sens-brandmessage-get#SMS%EB%8C%80%EC%B2%B4%EB%B0%9C%EC%86%A1%EC%9A%94%EC%B2%AD%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) 참조 |
| `failover.requestStatusName` | String | - | 대체 발송 요청 상태 - `success` \| `fail` - `success`: 성공 - `fail`: 실패 |
| `failover.requestStatusDesc` | String | - | 대체 발송 요청 상태 설명 |
| `failover.messageStatus` | String | - | 대체 발송 메시지 상태 - `READY` \| `PROCESSING` \| `COMPLETED` - `READY`: 대기중 - `PROCESSING`: 처리중 - `COMPLETED`: 완료 |
| `failover.messageStatusCode` | String | - | 대체 발송 메시지 수신 상태 코드 - [SMS 수신 결과 코드](/docs/sens-sms-get#%EC%88%98%EC%8B%A0%EA%B2%B0%EA%B3%BC%EC%BD%94%EB%93%9C) 참조 |
| `failover.messageStatusName` | String | - | 대체 발송 메시지 수신 상태 |
| `failover.messageStatusDesc` | String | - | 대체 발송 메시지 수신 상태 설명 |
| `isAdult` | Boolean | - | 대상 연령 - `true` \| `false` (기본값) - `true`: 성인용 - `false`: 전체 연령용 |
| `targeting` | String | - | 타겟팅 코드 - `M` \| `N` \| `I` (기본값) - `M`: 고객사의 광고성 정보 수신동의 유저(카카오톡 수신 동의) - `N`: 고객사의 광고성 정보 수신동의 유저(카카오톡 수신 동의) 중 해당 채널 친구 제외 - `I`: 광고성 정보 수신동의 유저(카카오톡 수신 동의)이면서 해당 채널 친구 - `F`: 채널 친구가 아닌 대상 제외(지원 예정) |
| `templateParameters` | Object | - | 템플릿 파라미터 |
| `headerContent` | String | - | 헤더 내용 |
| `additionalContent` | String | - | 부가 내용 |
| `buttons` | Array | - | 버튼 목록: [buttons](/docs/sens-brandmessage-get#buttons) |
| `image` | Object | - | 이미지 정보 |
| `image.imageId` | String | - | 이미지 아이디 |
| `image.imageLink` | String | - | 이미지 URL |
| `item` | Object | - | 와이드 리스트 정보 |
| `item.list` | Array | - | 와이드 리스트: [list](/docs/sens-brandmessage-get#list) |
| `carousel` | Object | - | 캐러셀 정보 |
| `carousel.head` | Object | - | 캐러셀 인트로 정보 |
| `carousel.head.headerContent` | String | - | 캐러셀 헤더 |
| `carousel.head.content` | String | - | 캐러셀 내용 |
| `carousel.head.imageId` | String | - | 캐러셀 인트로 이미지 아이디 |
| `carousel.head.linkMobile` | String | - | 캐러셀 인트로 모바일 웹 링크 |
| `carousel.head.linkPc` | String | - | 캐러셀 인트로 PC 웹 링크 |
| `carousel.head.schemeAndroid` | String | - | 캐러셀 인트로 Android 앱 링크 |
| `carousel.head.schemeIos` | String | - | 캐러셀 인트로 iOS 앱 링크 |
| `carousel.list` | Array | - | 캐러셀 목록: [list](/docs/sens-brandmessage-get#list) |
| `carousel.tail` | Object | - | 캐러셀 더보기 정보 |
| `carousel.tail.linkMobile` | String | - | 모바일 웹 링크 |
| `carousel.tail.linkPc` | String | - | PC 웹 링크 |
| `carousel.tail.schemeAndroid` | String | - | Android 앱 링크 |
| `carousel.tail.schemeIos` | String | - | iOS 앱 링크 |
| `commerce` | Object | - | 커머스 정보 |
| `commerce.title` | String | - | 상품 제목 |
| `commerce.regularPrice` | Integer | - | 상품 정상 가격 |
| `commerce.discountPrice` | Integer | - | 상품 할인 가격 |
| `commerce.discountRate` | Integer | - | 상품 할인율 |
| `commerce.discountFixed` | Integer | - | 상품 정액 할인 가격 |
| `coupon` | Object | - | 쿠폰 정보 |
| `coupon.title` | String | - | 쿠폰 제목 |
| `coupon.description` | String | - | 쿠폰 상세 설명 |
| `coupon.linkMobile` | String | - | 모바일 웹 링크 |
| `coupon.linkPc` | String | - | PC 웹 링크 |
| `coupon.schemeAndroid` | String | - | Android 앱 링크 |
| `coupon.schemeIos` | String | - | iOS 앱 링크 |
| `video` | Object | - | 동영상 정보 (프리미엄 동영상형) |
| `video.thumbnailId` | String | - | 동영상 썸네일용 이미지 아이디 |
| `video.videoUrl` | String | - | 카카오TV 동영상 URL |

#### `buttons`

`buttons`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `type` | String | - | 버튼 유형 - `WL` \| `AL` |
| `name` | String | - | 버튼 이름 |
| `linkMobile` | String | - | 모바일 웹 링크 |
| `linkPc` | String | - | PC 웹 링크 |
| `schemeIos` | String | - | iOS 앱 링크 |
| `schemeAndroid` | String | - | Android 앱 링크 |
| `bizFormId` | String | - | 비즈니스 폼 아이디 |

#### `list`

`list`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `title` | String | - |  |
| `imageId` | String | - |  |
| `linkMobile` | String | - | 모바일 웹 링크 |
| `linPc` | String | - | PC 웹 링크 |
| `schemeAndroid` | String | - | Android 앱 링크 |
| `schemeIos` | String | - | iOS 앱 링크 |

### 응답 상태 코드

Simple & Easy Notification Service API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Simple & Easy Notification Service 응답 상태 코드](/docs/sens-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

### 응답 예시

응답 예시는 다음과 같습니다.

```
{
    "requestId": "RBBA-*************-****-********-QlvjXtBr",
    "messageId": "bc87c708-****-****-****-57b56c506309",
    "requestTime": "2025-11-28T11:21:06.317",
    "completeTime": "2025-11-28T11:21:06",
    "plusFriendId": "@******",
    "messageType": "TEXT",
    "countryCode": "82",
    "to": "010********",
    "content": "축하 카드",
    "requestStatusCode": "A000",
    "requestStatusName": "success",
    "requestStatusDesc": "성공",
    "messageStatusCode": "0000",
    "messageStatusName": "success",
    "messageStatusDesc": "정상 발송",
    "useSmsFailover": true,
    "failover": {
        "smsServiceId": "ncp:sms:kr:27*********6:sens",
        "requestId": "RSLA-*************-****-********-ZzdhBYsk",
        "messageId": "6cc7eab4-****-****-****-c523f8a0e8ce",
        "requestStatusCode": "0",
        "requestStatusName": "success",
        "requestStatusDesc": "성공",
        "messageStatus": "COMPLETED",
        "messageStatusCode": "0",
        "messageStatusName": "success",
        "messageStatusDesc": "성공"
    },
    "isAdult": false,
    "targeting": "I",
    "buttons": [
        {
            "name": "홈페이지",
            "type": "WL",
            "linkPc": "https://******.com/ko/",
            "linkMobile": "https://******.com/ko/"
        },
        {
            "name": "블로그",
            "type": "WL",
            "linkPc": "https://******.com/ko/blog/",
            "linkMobile": "https://*******.com/ko/blog/"
        }
    ],
    "image": {
        "imageId": "c175d6a4-****-****-****-90973f8f0aae",
        "imageLink": "https://mud-kage.kakao.com/dn/h9B2k/***********/**********************/img_l.jpg"
    }
}
```

## 수신 결과 코드

알림톡/브랜드 메시지에 대한 수신 결과 코드는 다음과 같습니다.

| 코드 | 메시지 | 설명 |
| --- | --- | --- |
| 0000 | - | 정상 발송 |
| 1001 | NoJsonBody | 요청 바디가 JSON 형식이 아님 |
| 1002 | InvalidHubPartnerKey | 파트너 키가 유효하지 않음 |
| 1003 | InvalidSenderKey | 발신 프로필 키가 유효하지 않음 |
| 1004 | NoValueJsonElement | 요청 바디(JSON)에서 name을 찾을 수 없음 |
| 1005 | SenderNotFound | 발신 프로필을 찾을 수 없음 |
| 1006 | DeletedSender | 삭제된 발신 프로필 |
| 1007 | StoppedSender | 차단 상태의 발신 프로필 |
| 1011 | ContractNotFound | 계약 정보를 찾을 수 없음 |
| 1012 | InvalidUserKeyException | 잘못된 형식의 유저 키 요청 |
| 1013 | InvalidAppLink | 유효하지 않은 앱 연결 |
| 1014 | InvalidBizNum | 유효하지 않은 사업자 번호 |
| 1015 | TalkUserIdNotFonud | 유효하지 않은 앱 유저 아이디 요청 |
| 1016 | BizNumNotEqual | 사업자 등록 번호 불일치 |
| 1020 | InvalidReceiveUserException | 유저 식별 값이 전부 유효하지 않음 |
| 1021 | BlockedProfile | 카카오톡 채널이 차단됨 (카카오톡 채널 운영 툴에서 확인) |
| 1022 | DeactivatedProfile | 카카오톡 채널이 닫혀 있음 (카카오톡 채널 운영 툴에서 확인) |
| 1023 | DeletedProfile | 카카오톡 채널이 삭제됨 (카카오톡 채널 운영 툴에서 확인) |
| 1024 | DeletingProfile | 카카오톡 채널이 삭제 대기 중 (카카오톡 채널 운영 툴에서 확인) |
| 1025 | SpammedProfile | 카카오톡 채널이 메시지 차단 상태임 (카카오톡 채널 운영 툴에서 확인) |
| 1026 | UnableUseMessageType | 해당 msg_type에서 사용할 수 없는 메서드로 요청 (이미지 알림톡(AI)은 실시간으로 발송 불가) |
| 1027 | - | 채널 메시지 제재 상태로 인한 메시지 전송 실패 |
| 1030 | InvalidParameterException | 잘못된 파라미터 요청 |
| 1033 | - | 템플릿 타입과 메시지 타입 불일치 |
| 2000 | FailedToCheckFriendshipException | 톡채널과 친구 관계 확인 시 오류 (시스템 오류) |
| 2003 | FailedToSendMessageByNoFriendshipException | 메시지 전송 실패 (테스트 서버에서 카카오톡 채널을 추가하지 않은 경우) |
| 2004 | FailedToMatchTemplateException | 템플릿 일치 확인 시 오류 발생 (카카오 내부 오류) |
| 2005 | FailedToReadImageException | 카카오에서 이미지 메타 정보 읽어오는 중 오류 |
| 2006 | FailedToMatchSerialNumberPrefixPattern | 시리얼넘버 형식 불일치 |
| 3000 | UnexceptedExcetpion | 예기치 않은 오류 발생 |
| 3005 | AckTimeoutException | 메시지를 발송했으나 수신 확인 안 됨 (성공 불확실) |
| 3006 | FailedToSendMessageException | 카카오 내부 시스템 오류로 메시지 전송 실패 |
| 3008 | InvalidPhoneNumberException | 전화번호 오류 |
| 3010 | JsonParseException | JSON 파싱 오류 |
| 3011 | MessageNotFoundException | 메시지가 존재하지 않음 |
| 3012 | SerialNumberDuplicatedException | 메시지 일련번호가 중복됨 (메시지 일련번호는 고유의 값이 부여되어야 함) |
| 3013 | MessageEmptyException | 빈 메시지 |
| 3014 | MessageLengthOverLimitException | 메시지 길이 제한 오류 (텍스트 타입 1,000자 초과, 이미지 타입 400자 초과) |
| 3015 | TemplateNotFoundException | 템플릿을 찾을 수 없음 |
| 3016 | NoMatchedTemplateException | 메시지 내용이 템플릿과 일치하지 않음 |
| 3018 | NoSendAvailableException | 메시지를 전송할 수 없음 |
| 3019 | MessageNoUserException | 톡 사용자가 아님 |
| 3020 | MessageUserBlockedAlimTalkException | 알림톡 차단 |
| 3021 | MessageNotSupportedKakaotalkException | 톡 최소 버전 미지원 |
| 3022 | NoSendAvailableTimeException | 메시지 발송 가능한 시간이 아님 (친구 톡/마케팅 메시지는 8시~20시까지 발송 가능) |
| 3023 | MessageInvalidVideoException | 메시지에 포함된 비디오를 전송할 수 없음 (비디오 주소 또는 섬네일 이미지 주소가 올바르지 않거나 섬네일 이미지가 규격에 맞지 않음) |
| 3024 | MessageInvalidImageException | 메시지에 포함된 이미지를 전송할 수 없음 |
| 3025 | ExceedMaxVariableLengthException | 변수 글자 수 제한 초과 |
| 3026 | Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' | 상담/봇 전환 버튼 extra, event 글자 수 제한 초과 |
| 3027 | NoMatchedTemplateButtonException | 버튼 내용이 템플릿과 일치하지 않음 |
| 3028 | NoMatchedTemplateTitleException | 메시지 강조 표기 타이틀이 템플릿과 일치하지 않음 |
| 3029 | ExceedMaxTitleLengthException | 메시지 강조 표기 타이틀 길이 제한 초과 (50자) |
| 3030 | NoMatchedTemplateWithMessageTypeException | 메시지 타입과 템플릿 강조 유형이 일치하지 않음 |
| 3031 | NoMatchedTemplateHeaderException | 헤더가 템플릿과 일치하지 않음 |
| 3032 | ExceedMaxHeaderLengthException | 헤더 길이 제한 초과 (16 자) |
| 3033 | NoMatchedTemplateItemHighlightException | 아이템 하이라이트가 템플릿과 일치하지 않음 |
| 3034 | ExceedMaxItemHighlightTitleLengthException | 아이템 하이라이트 타이틀 길이 제한 초과 (이미지 없는 경우 30자, 이미지 있는 경우 21자) |
| 3035 | ExceedMaxItemHighlightDescriptionLengthException | 아이템 하이라이트 설명 길이 제한 초과 (이미지 없는 경우 19자, 이미지 있는 경우 14자) |
| 3036 | NoMatchedTemplateItemListException | 아이템 리스트가 템플릿과 일치하지 않음 |
| 3037 | ExceedMaxItemDescriptionLengthException | 아이템 리스트의 아이템 설명 길이 제한 초과 (23자) |
| 3038 | NoMatchedTemplateItemSummaryException | 아이템 요약 정보가 템플릿과 일치하지 않음 |
| 3039 | ExceedMaxItemSummaryDescriptionLengthException | 아이템 요약 정보 길이 제한 초과 (14자) |
| 3040 | InvalidItemSummaryDescriptionException | 아이템 요약 정보에 허용되지 않은 문자 포함 (통화기호/코드, 숫자, 콤마, 소수점, 공백을 제외한 문자 포함) |
| 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 | 예기치 못한 오류 |

## SMS 대체 발송 요청 상태 코드

Biz Message 발송 실패 시 SMS로 대체 발송을 요청할 때 반환되는 상태 코드입니다.

| 코드 | 설명 |
| --- | --- |
| 0 | 성공 |
| E4000 | SMS 대체 발송 설정이 유효하지 않음 |
| E4001 | SMS 대체 발송 설정 정보가 누락됨 |
| E4002 | SMS 대체 발송 서비스가 설정되지 않음 |
| E4003 | SMS 대체 발송 타입(SMS, LMS)이 설정되지 않음 |
| E4004 | SMS 대체 발송 발신 번호가 설정되지 않음 |
| E4005 | SMS 대체 발송 메시지 제목이 설정되지 않음 |
| E4006 | SMS 대체 발송 메시지 내용이 설정되지 않음 |
| E4007 | SMS 대체 발송 메시지 수신 번호가 설정되지 않음 |
| E4008 | SMS 대체 발송 서비스가 사용 가능한 상태가 아님 |
| E4009 | SMS 대체 발송 발신 번호가 인증되지 않음 |
| E4010 | SMS 대체 발송의 080 무료 수신 거부 서비스가 사용 가능한 상태가 아님 |
| E4999 | SMS 대체 발송 설정 파싱 오류 (고객 지원으로 문의 필요) |
| E5000 | 내부 오류 (고객 지원으로 문의 필요) |