발송 그룹 결과 조회 (폴링)

get/public/v1/messages/{groupId}200

알아 둘 것

  • 결과는 **폴링으로만** 받습니다 — 웹훅은 제공하지 않습니다.
  • `status` 가 COMPLETED·FAILED·CANCELED 중 하나가 되면 더 이상 바뀌지 않습니다. 그 전까지만 폴링하세요.
  • 폴링 간격은 5초 이상을 권장합니다. 너무 잦으면 8628(호출 한도)로 막힙니다.

파라미터

이름위치필수설명
groupId경로필수발송 그룹 ID (접수 응답의 groupId)

요청 본문

이 호출에는 본문이 없습니다.

응답

아래는 200 응답의 실제 모양입니다. 자동 생성된 스펙이 그리는 것은 data 안쪽뿐이라, 그것만 보고 짜면 값을 찾지 못합니다.

  • successboolean필수

    성공 응답에서는 항상 `true` 입니다.

    예: true

  • messagestring필수

    사람이 읽는 설명. 성공에는 기본 문구가 실리므로 분기 근거로 쓰지 마세요.

    예: "Request processed successfully"

  • dataPublicGroupResponse필수

    요청 결과 본문

    • groupIdstring필수

      발송 그룹 ID

    • messageTypestring필수

      채널 코드

      ATAIU_FTSMLMMM
    • statusstring필수

      잡 상태

      PENDINGSPLITTINGRUNNINGCOMPLETEDFAILEDCANCELED
    • countsPublicGroupCounts필수

      건수 집계

    • scheduledAtstring필수null 가능date-time

      예약 시각

    • startedAtstring필수null 가능date-time

      발송 시작 일시

    • finishedAtstring필수null 가능date-time

      발송 종료 일시

    • canceledAtstring필수null 가능date-time

      취소 일시 (예약 취소)

    • failedReasonstring필수null 가능

      실패 사유 · FAILED 만

  • timestampstring필수date-time

    응답을 만든 시각 (KST)

  • methodstring필수

    요청 메서드. 요청을 그대로 되비춰 줍니다.

    예: "POST"

  • pathstring필수

    요청 경로

    예: "/public/v1/messages/alimtalk"

  • correlationIdstring필수

    요청 추적 ID. **문의할 때 이 값을 함께 알려 주세요** — 서버 로그를 이 값으로 찾습니다.

에러

실패 응답도 봉투에 담겨 오고, 숫자 code 로 원인이 갈립니다. 이 호출에서 볼 수 있는 코드는 다음과 같습니다.

코드HTTP키설명
8620401PUBLIC_API_KEY_REQUIREDAPI 키가 필요합니다. Authorization: Bearer {key} 또는 X-Api-Key 헤더로 전달해 주세요.
8621401PUBLIC_API_KEY_INVALID유효하지 않은 API 키입니다.
8622401PUBLIC_API_KEY_SUSPENDED정지된 API 키입니다. 콘솔에서 상태를 확인해 주세요.
8623401PUBLIC_API_KEY_EXPIRED만료된 API 키입니다.
8624403PUBLIC_IP_BLOCKED허용되지 않은 IP 에서의 호출입니다. 국외 IP 는 예외 없이 차단됩니다.
8628429PUBLIC_RATE_LIMITED호출 한도를 초과했습니다. 잠시 후 다시 시도해 주세요.
8629404PUBLIC_MESSAGE_GROUP_NOT_FOUND발송 그룹을 찾을 수 없습니다.
6950404SEND_RESULT_NOT_FOUND발송 내역을 찾을 수 없습니다.

여기서 바로 실행

get

요청은 그대로 나가지만 샌드박스 키로는 이 API 를 쓸 수 없습니다 — 응답으로 8626 이 돌아옵니다. 어떤 모양으로 막히는지 확인하는 자리이고, 실제 조회·취소는 라이브 키로 직접 호출해 주세요.

요청 (전체)

# 성공 응답은 200 입니다.
# 응답은 봉투에 싸여 옵니다 — 알맹이는 data 안에 있습니다.
curl -X GET 'https://api.directalk.io/public/v1/messages/grp_01HQZX8N2K4M7P9R3T5V6W8Y0A' \
  -H 'Authorization: Bearer dk_live_xxxxxxxxxxxxxxxxxxxxxxxx'

응답 200

{
  "success": true,
  "message": "Request processed successfully",
  "data": {
    "groupId": "문자열",
    "messageType": "AT",
    "status": "PENDING",
    "counts": {
      "requested": 0,
      "optOutExcluded": 0,
      "duplicateExcluded": 0,
      "sent": 0,
      "success": 0,
      "fail": 0
    },
    "scheduledAt": "2026-08-20T10:00:00+09:00",
    "startedAt": "2026-08-20T10:00:00+09:00",
    "finishedAt": "2026-08-20T10:00:00+09:00",
    "canceledAt": "2026-08-20T10:00:00+09:00",
    "failedReason": "문자열"
  },
  "timestamp": "2026-08-25T14:32:10.482+09:00",
  "method": "GET",
  "path": "/public/v1/messages/grp_01HQZX8N2K4M7P9R3T5V6W8Y0A",
  "correlationId": "c7f1a2b4-9e30-4d15-8a6c-2f0b7d9e1c34"
}

실패 응답 예시

{
  "success": false,
  "message": "API 키가 필요합니다. Authorization: Bearer {key} 또는 X-Api-Key 헤더로 전달해 주세요.",
  "code": 8620,
  "timestamp": "2026-08-25T14:32:10.482+09:00",
  "method": "GET",
  "path": "/public/v1/messages/grp_01HQZX8N2K4M7P9R3T5V6W8Y0A",
  "correlationId": "c7f1a2b4-9e30-4d15-8a6c-2f0b7d9e1c34"
}