카카오 메시지 발송결과 조회하기

발송 그룹이란?

카카오 메시지를 보낼 때마다 하나의 '발송 그룹'이 생성됩니다. 발송 그룹은 한 번의 API 호출로 여러 수신자에게 보낸 메시지들을 함께 관리하는 단위입니다. 예를 들어 100명의 고객에게 알림톡을 한 번에 발송했다면, 하나의 발송 그룹 안에 100개의 메시지가 포함됩니다.

📘

발송 그룹 ID로 할 수 있는 일

  • 모든 메시지의 성공/실패 현황을 한눈에 확인하기
  • 아직 발송되지 않은 예약 메시지 취소하기
  • 예약된 메시지를 지금 바로 발송하기

발송 그룹 정보 조회하기

어떤 상황에서 필요한가요?

  • 대량으로 보낸 메시지의 전체 발송 현황이 궁금할 때
  • 예약해둔 메시지가 잘 대기 중인지 확인하고 싶을 때
  • 메시지 발송에 사용된 비용 정보를 확인하고 싶을 때

사용 방법

발송 그룹을 조회할 때는 메시지 발송 후 받은 groupId를 사용합니다.

const sendon = new Sendon({
  id: SENDON_EXAM_ACCOUNT,
  apikey: SENDON_EXAM_API_KEY,
  debug: false,
})

// 발송 시 응답으로 받은 그룹 ID
const groupId = "84db8cbb-db70-4e68-8ee7-c37704787e0d";
const result = await sendon.kakao.getGroupInfo(groupId);

console.log('발송 그룹 정보:', result);
Sendon sendon = Sendon.getInstance(SENDON_EXAM_ACCOUNT, SENDON_EXAM_API_KEY);

GetGroup getGroup = sendon.kakao.getGroup("0195cb3a-3981-75e4-bf95-4948f4637a73");

응답 예시

{
  "code": 200,
  "message": "성공",
  "data": {
    "userId": 12345,
    "profileId": "발신프로필ID",
    "groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d",
    "message": "안녕하세요 #{이름}님, 회원가입이 완료되었습니다.",
    "messageType": "AT",
    "requestDomain": "example.com",
    "sender": "발신자정보",
    "reservedStatus": "RESERVED",
    "groupStatus": "RESERVED",
    "countRequest": 10,
    "messageCount": 10,
    "standbyCount": 10,
    "sendingCount": 0,
    "succeededCount": 0,
    "failedCount": 0,
    "canceledCount": 0,
    "fallbackCount": 0,
    "unitCost": 10,
    "vatPoint": 1,
    "totalPoint": 11,
    "refundPoint": 0,
    "messageContents": {
      "messageType": "AT",
      "AT": {
        "body": "안녕하세요 #{이름}님, 회원가입이 완료되었습니다.",
        "buttons": [
          {
            "name": "자세히 보기",
            "type": "WL",
            "urlMobile": "https://example.com",
            "urlPc": "https://example.com"
          }
        ],
        "templateId": "템플릿ID",
        "templateCode": "템플릿코드"
      }
    },
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
}

주요 응답 필드 살펴보기

필드의미
messageCount이 그룹에 포함된 전체 메시지 수
standbyCount아직 발송 대기 중인 메시지 수
sendingCount현재 발송 진행 중인 메시지 수
succeededCount성공적으로 발송된 메시지 수
failedCount발송에 실패한 메시지 수
canceledCount취소된 메시지 수
fallbackCount카카오톡 발송 실패 후 문자로 대체 발송된 수
totalPoint이 그룹의 총 발송 비용(포인트)

예약 메시지 관리

예약 메시지의 취소나 즉시 발송과 같은 기능은 카카오 메시지 발송 예약하기 문서를 참조하세요.

알아두면 좋은 정보

메시지 유형 한눈에 보기

코드설명특징
AT알림톡 (기본형)텍스트와 버튼이 포함된 기본 형태
AI알림톡 (이미지형)텍스트, 이미지, 버튼을 모두 담을 수 있음
AE알림톡 (강조형)제목이 강조된 형태로 눈에 잘 띔
FT친구톡 (텍스트형)최대 1,000자 텍스트와 버튼 포함 가능
FI친구톡 (이미지형)400자 텍스트와 이미지, 버튼 포함
FW친구톡 (와이드이미지형)76자 텍스트와 눈에 띄는 와이드 이미지

그룹 상태 의미

상태의미
RESERVED예약됨 - 아직 발송 전, 대기 중인 상태
PROCESSING처리중 - 현재 발송이 진행되고 있는 상태
COMPLETED완료됨 - 발송 처리가 모두 끝난 상태
FAILED실패 - 발송 자체가 실패한 상태
CANCELED취소됨 - 발송이 취소된 상태

발송 결과 확인 시 알아두세요

⚠️

발송 결과 확인 시 알아두세요

  • 대량 메시지는 결과가 실시간으로 바로 반영되지 않을 수 있습니다. 약간의 시간 간격을 두고 조회해 보세요.
  • 일부 메시지가 실패했더라도 전체 발송 프로세스가 완료되면 groupStatusCOMPLETED로 표시됩니다.
  • 즉시 발송 전환은 모든 메시지가 예약 상태일 때만 가능합니다.
  • 모든 메시지가 실패했더라도 발송 프로세스 자체가 끝나면 상태는 COMPLETED입니다. 예를 들어, 친구톡을 보냈는데 수신자 모두가 채널 친구가 아니어서 10건 전부 실패했어도 발송 상태는 '완료'로 표시됩니다.

그룹 ID 잘 활용하기

  • 그룹 ID는 발송 요청마다 새롭게 생성되는 고유한 문자열입니다.
  • 발송 후 받은 그룹 ID를 DB에 저장해두면 나중에 발송 결과를 편리하게 조회할 수 있습니다.
  • 곧 웹훅 기능이 추가될 예정입니다. 이 기능이 구현되면 발송 상태가 변경될 때마다 설정한 URL로 자동 알림을 받을 수 있습니다.

관련 링크