친구톡 발송 목록 조회

Prev Next

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

친구톡 메시지에 대한 발송 요청 목록을 조회합니다. 최근 30일 이내의 요청 목록을 조회할 수 있습니다.

요청

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

메서드 URI
GET /friendtalk/v2/services/{serviceId}/messages

요청 헤더

Simple & Easy Notification Service API에서 공통으로 사용하는 헤더에 대한 정보는 Simple & Easy Notification Service 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

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

필드 타입 필수 여부 설명
serviceId String Required Biz Message 서비스 아이디

요청 쿼리 파라미터

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

필드 타입 필수 여부 설명
requestId String Conditional 요청 아이디
  • 메시지 발송 시 응답받은 요청 아이디 입력
  • requestId, requestStartTime+requestEndTime, completeStartTime+completeEndTime 중 하나는 필수 입력
  • requestStartTime+requestEndTime과 completeStartTime+completeEndTime는 동시 사용 불가
requestStartTime String Conditional 발송 요청 기준 조회 시작 일시
  • YYYY-MM-DDTHH:mm:ss 형식
  • requestId, requestStartTime+requestEndTime, completeStartTime+completeEndTime 중 하나는 필수 입력
  • requestStartTime+requestEndTime과 completeStartTime+completeEndTime는 동시 사용 불가
requestEndTime String Conditional 발송 요청 기준 조회 종료 일시
  • YYYY-MM-DDTHH:mm:ss 형식
  • requestStartTime과의 기간이 31일 이내여야 함
completeStartTime String Conditional 발송 완료 기준 조회 시작 일시
  • YYYY-MM-DDTHH:mm:ss 형식
  • requestId, requestStartTime+requestEndTime, completeStartTime+completeEndTime 중 하나는 필수 입력
  • requestStartTime+requestEndTime과 completeStartTime+completeEndTime는 동시 사용 불가
completeEndTime String Conditional 발송 완료 기준 조회 종료 일시
  • YYYY-MM-DDTHH:mm:ss 형식
  • completeStartTime과의 기간이 24시간 이내여야 함
plusFriendId String Optional 채널 아이디
  • 채널 조회 참조
  • requestId 미입력 시 필수 입력
messageId String Optional 메시지 아이디
requestStatusName String Optional 요청 상태
  • success | fail
    • success: 성공
    • fail: 실패
messageStatusName String Optional 수신 상태
  • success | processing | fail
    • success: 성공
    • processing: 처리중
    • fail: 실패
to String Optional 수신 번호
  • 숫자만 입력 가능
nextToken String Optional 페이지 위치 토큰
  • 다음 목록 조회 시 사용하며, 이전 호출에서 응답받은 토큰값 입력
pageSize Integer Optional 페이지당 항목 수
  • 1~100 (기본값: 20)
  • requestId 입력 시 기본으로 100 적용

요청 예시

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

curl --location --request GET 'https://sens.apigw.ntruss.com/friendtalk/v2/services/ncp:kkobizmsg:kr:27*********6:sens/messages?requestStartTime=2025-11-25T09%3A10%3A00&requestEndTime=2025-11-25T23%3A30%3A00&pageSize=3' \
--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 - 요청 아이디
  • 요청에 requestId 포함 시 표시
statusCode String - 상태 코드
  • HTTP 상태 코드 규칙을 따름
statusName String - 상태
  • success | processing | reserved | fail
    • success: 성공
    • processing: 처리중
    • reserved: 예약
    • fail: 실패
messages Array - 메시지 발송 요청 목록
pageSize Integer - 페이지당 항목 수
pageIndex Integer - 페이지 인덱스
nextToken String - 페이지 위치 토큰
  • 다음 페이지가 없을 경우, 표시되지 않음
itemCount Integer - 응답 결과 수
hasMore Boolean - 다음 페이지 존재 여부
  • true: 존재
  • false: 존재 안 함

messages

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

필드 타입 필수 여부 설명
requestTime String - 요청 일시
  • YYYY-MM-DDTHH:mm:ss.sss 형식
requestId String - 요청 아이디
messageId String - 메시지 아이디
countryCode String - 국가 코드
to String - 수신 번호
content String - 메시지 내용
plusFriendId String - 채널 아이디
completeTime String - 완료 일시
  • YYYY-MM-DDTHH:mm:ss 형식
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 - 수신 상태 설명
isWide Boolean - 와이드 이미지형 메시지 여부
  • true | false
    • true: 와이드 이미지형 메시지
    • false: 와이드 이미지형 메시지 아님
isAd Boolean - 광고 메시지 여부
  • true | false
    • true: 광고 메시지
    • false: 광고 메시지 아님
imageId String - 이미지 아이디
imageName String - 이미지 파일 이름
imageUrl String - 이미지 URL
imageLink String - 이미지 URL
useSmsFailover Boolean - SMS 대체 발송 사용 여부
  • true | false
    • true: 사용
    • false: 사용 안 함
failover Object - SMS 대체 발송 정보
  • 대체 발송이 실행된 경우, 표시
failover.smsServiceId String - 대체 발송에 사용된 SMS 서비스 아이디
failover.requestId String - 대체 발송 요청 아이디
failover.messageId String - 대체 발송 메시지 아이디
failover.requestStatusCode String -
failover.requestStatusName String - 대체 발송 요청 상태
  • success | fail
    • success: 성공
    • fail: 실패
failover.requestStatusDesc String - 대체 발송 요청 상태 설명
failover.messageStatus String - 대체 발송 메시지 수신 상태
  • READY | PROCESSING | COMPLETED
    • READY: 대기중
    • PROCESSING: 처리중
    • COMPLETED: 완료
failover.messageStatusCode String - 대체 발송 메시지 수신 상태 코드
failover.messageStatusName String - 대체 발송 메시지 수신 상태
failover.messageStatusDesc String - 대체 발송 메시지 수신 상태 설명

응답 상태 코드

Simple & Easy Notification Service API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Simple & Easy Notification Service 응답 상태 코드를 참조해 주십시오.

응답 예시

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

{
    "statusCode": "202",
    "statusName": "success",
    "messages": [
        {
            "requestTime": "2025-11-25T15:37:16.395",
            "requestId": "RBFA-*************-****-********-oTlbUtlO",
            "messageId": "6b086ab3-****-****-****-2d4fb547f559",
            "countryCode": "82",
            "to": "010********",
            "content": "2025년 12월 1일부터 10일까지 페스티벌이 열립니다. 많은 참여와 관심 부탁드립니다.",
            "plusFriendId": "@******",
            "completeTime": "2025-11-25T15:37:17",
            "requestStatusCode": "A000",
            "requestStatusName": "success",
            "requestStatusDesc": "성공",
            "messageStatusCode": "1030",
            "messageStatusName": "fail",
            "messageStatusDesc": "잘못된 파라메터 요청",
            "isWide": false,
            "isAd": true,
            "imageId": "a15c7206-****-****-****-57adec9e48f9",
            "imageName": "myImage.jpg",
            "imageUrl": "https://mud-kage.kakao.com/dn/dccjAa/***********/**********************/img_l.jpg",
            "imageLink": "https://mud-kage.kakao.com/dn/dccjAa/***********/**********************/img_l.jpg",
            "useSmsFailover": true,
            "failover": {
                "smsServiceId": "ncp:sms:kr:27*********6:sens",
                "requestId": "RSLA-*************-****-********-sftfPTbc",
                "messageId": "f0df7828-****-****-****-b1164a57025d",
                "requestStatusCode": "0",
                "requestStatusName": "success",
                "requestStatusDesc": "성공",
                "messageStatus": "COMPLETED",
                "messageStatusCode": "0",
                "messageStatusName": "success",
                "messageStatusDesc": "성공"
            }
        },
        {
            "requestTime": "2025-11-25T15:32:07.826",
            "requestId": "RBFA-*************-****-********-zgrtzVEW",
            "messageId": "ace5ea34-62e9-4b7c-8793-56ddbe21b384",
            "countryCode": "82",
            "to": "010********",
            "content": "2025년 12월 1일부터 10일까지 페스티벌이 열립니다. 많은 참여와 관심 부탁드립니다.",
            "plusFriendId": "@******",
            "completeTime": "2025-11-25T15:32:08",
            "requestStatusCode": "A000",
            "requestStatusName": "success",
            "requestStatusDesc": "성공",
            "messageStatusCode": "1030",
            "messageStatusName": "fail",
            "messageStatusDesc": "잘못된 파라메터 요청",
            "isWide": false,
            "isAd": true,
            "imageId": "a15c7206-****-****-****-57adec9e48f9",
            "imageName": "myImage.jpg",
            "imageUrl": "https://mud-kage.kakao.com/dn/dccjAa/***********/**********************/img_l.jpg",
            "imageLink": "https://mud-kage.kakao.com/dn/dccjAa/***********/**********************/img_l.jpg",
            "useSmsFailover": true,
            "failover": {
                "smsServiceId": "ncp:sms:kr:27*********6:sens",
                "requestStatusCode": "E4000",
                "requestStatusName": "fail",
                "requestStatusDesc": "Invalid failover data. The 080 block call service is not available."
            }
        }
    ],
    "pageSize": 3,
    "pageIndex": 0,
    "itemCount": 2,
    "hasMore": false
}