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

발송 그룹이란?
카카오 메시지를 보낼 때마다 하나의 '발송 그룹'이 생성됩니다. 발송 그룹은 한 번의 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 | 취소됨 - 발송이 취소된 상태 |
발송 결과 확인 시 알아두세요
발송 결과 확인 시 알아두세요
- 대량 메시지는 결과가 실시간으로 바로 반영되지 않을 수 있습니다. 약간의 시간 간격을 두고 조회해 보세요.
- 일부 메시지가 실패했더라도 전체 발송 프로세스가 완료되면
groupStatus
는COMPLETED
로 표시됩니다.- 즉시 발송 전환은 모든 메시지가 예약 상태일 때만 가능합니다.
- 모든 메시지가 실패했더라도 발송 프로세스 자체가 끝나면 상태는
COMPLETED
입니다. 예를 들어, 친구톡을 보냈는데 수신자 모두가 채널 친구가 아니어서 10건 전부 실패했어도 발송 상태는 '완료'로 표시됩니다.
그룹 ID 잘 활용하기
- 그룹 ID는 발송 요청마다 새롭게 생성되는 고유한 문자열입니다.
- 발송 후 받은 그룹 ID를 DB에 저장해두면 나중에 발송 결과를 편리하게 조회할 수 있습니다.
- 곧 웹훅 기능이 추가될 예정입니다. 이 기능이 구현되면 발송 상태가 변경될 때마다 설정한 URL로 자동 알림을 받을 수 있습니다.
관련 링크
Updated 3 days ago