카카오 메시지 대체발송하기

대체발송(Fallback)은 카카오 알림톡이나 친구톡 발송이 실패할 경우 자동으로 SMS, LMS, MMS 등 일반 문자메시지로 전환하여 발송하는 기능입니다. 이 기능을 통해 메시지 전달의 신뢰성을 높이고 다양한 상황에서 메시지가 수신자에게 도달할 수 있도록 보장할 수 있습니다.
대체발송이 필요한 상황
- 수신자가 카카오톡을 사용하지 않는 경우
- 수신자가 카카오톡 알림을 차단한 경우
- 수신자가 비즈니스 채널과 친구 관계가 아닌 경우 (친구톡)
- 카카오톡 서버 오류 등으로 발송이 실패한 경우
대체발송 유형
센드온 SDK에서는 다음과 같은 대체발송 유형을 지원합니다:
-
SMS (Short Message Service)
- 최대 90바이트 이내의 짧은 텍스트 메시지
- 제목이나 이미지를 포함할 수 없음
-
LMS (Long Message Service)
- 최대 2,000바이트 이내의 긴 텍스트 메시지
- 제목 포함 가능
-
MMS (Multimedia Message Service)
- 텍스트 메시지와 함께 이미지를 포함
- 제목 포함 가능
- 이미지는 최대 3장까지 첨부 가능
- 메시지가 짧아도 이미지가 첨부되면 MMS로 분류됨
대체발송 설정 방법
대체발송 설정 옵션
대체발송 설정은 fallback
객체를 통해 지정하며, 다음과 같은 옵션을 제공합니다:
옵션 | 설명 | 적용 가능 메시지 |
---|---|---|
NONE | 대체발송을 사용하지 않음 (기본값) | 알림톡, 친구톡 |
TEMPLATE | 템플릿에 설정된 대체발송 내용을 사용 | 알림톡만 가능 |
CUSTOM | 직접 설정한 대체발송 내용을 사용 | 알림톡, 친구톡 |
참고:
fallback
파라미터를 설정하지 않으면 대체발송이 이루어지지 않습니다.
TEMPLATE 옵션 설명
TEMPLATE 옵션은 알림톡에만 사용 가능한 기능으로, 센드온 플랫폼에서 템플릿을 등록할 때 미리 설정한 대체발송 내용을 활용합니다.
- 센드온 플랫폼에서 알림톡 템플릿 등록 시 함께 설정한 대체발송 내용을 그대로 사용
- 별도로 대체발송 내용을 작성할 필요 없이 템플릿에 설정된 내용을 일관되게 활용 가능
- 템플릿 변경 시 대체발송 내용도 함께 관리되므로 유지보수가 용이
- 템플릿에 대체발송 내용이 설정되어 있지 않은 경우 사용 불가
대체발송 설정 예제
SMS 대체발송 설정
const sendon = new Sendon({
id: SENDON_EXAM_ACCOUNT,
apikey: SENDON_EXAM_API_KEY,
debug: false,
})
const result = await sendon.kakao.sendAlimTalk({
sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
templateId: SENDON_EXAM_KAKAO_TEMPLATE_ID,
to: [SENDON_EXAM_KAKAO_TO_PHONE],
fallback: {
fallbackType: 'CUSTOM',
custom: {
type: 'SMS',
senderNumber: SENDON_EXAM_KAKAO_TO_PHONE,
message: '안녕하세요. 알림톡 발송 실패로 인한 대체 SMS입니다.',
isAd: false, // 광고성 메시지 여부
},
},
})
LMS 대체발송 설정
const result = await sendon.kakao.sendAlimTalk({
sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
templateId: SENDON_EXAM_KAKAO_TEMPLATE_ID,
to: [SENDON_EXAM_KAKAO_TO_PHONE],
fallback: {
fallbackType: 'CUSTOM',
custom: {
type: 'LMS',
senderNumber: SENDER_PHONE_NUMBER, // 센드온에 등록되고 승인된 발신번호
message: `안녕하세요. 카카오톡 발송 실패로 인한 대체 LMS입니다.
주문번호: ORD-12345
주문일시: 2023-12-15 14:30
주문상품: 프리미엄 서비스 패키지
결제금액: 55,000원
주문 상세내역은 웹사이트에서 확인하실 수 있습니다.
https://example.com/orders/ORD-12345`,
title: '주문 완료 안내', // LMS 제목
isAd: false,
},
},
})
MMS 대체발송 설정
const imageFile = new File(
[fs.readFileSync(path.resolve(__dirname, '../../../resources/sendon_image.png'))],
'sendon.png',
{
type: 'image/png',
},
)
const uploadResult = await sendon.kakao.uploadFallbackImage([imageFile])
const result = await sendon.kakao.sendAlimTalk({
sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
templateId: SENDON_EXAM_KAKAO_TEMPLATE_ID,
to: [SENDON_EXAM_KAKAO_TO_PHONE],
fallback: {
fallbackType: 'CUSTOM',
custom: {
type: 'MMS',
senderNumber: SENDON_EXAM_KAKAO_FROM_PHONE, // 센드온에 등록되고 승인된 발신번호
message: '카카오톡 발송 실패로 인한 대체 MMS 메시지입니다.',
title: '이벤트 안내',
isAd: true,
images: uploadResult.data.imageIds, // 업로드된 이미지 ID 배열
},
},
})
템플릿 대체발송 사용 예제 (알림톡 전용)
async function sendAlimTalkWithTemplateFallback() {
const result = await sendon.kakao.sendAlimTalk({
sendProfileId: SEND_PROFILE_ID,
templateId: TEMPLATE_ID,
to: [RECIPIENT_PHONE_NUMBER],
fallback: {
fallbackType: 'TEMPLATE',
},
});
console.log('발송 결과:', result);
return result;
}
대체발송 파라미터
기본 파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
fallback | object | 대체발송 설정 객체 | 선택 |
fallback.fallbackType | string | 대체발송 유형 ('NONE', 'TEMPLATE', 'CUSTOM') | 필수 |
CUSTOM 옵션 사용 시 파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
fallback.custom | object | 대체발송 상세 설정 | CUSTOM 타입 필수 |
fallback.custom.type | string | 대체문자 유형 ('SMS', 'LMS', 'MMS') | 필수 |
fallback.custom.senderNumber | string | 발신번호 (센드온에 등록된 번호) | 필수 |
fallback.custom.message | string | 메시지 내용 | 필수 |
fallback.custom.isAd | boolean | 광고성 메시지 여부 | 필수 |
fallback.custom.title | string | 메시지 제목 | LMS/MMS 선택 |
fallback.custom.images | string[] | 이미지 ID 배열 | MMS 필수 |
대체발송 이미지 업로드
MMS 대체발송을 사용하려면 먼저 이미지를 업로드해야 합니다.
async function uploadFallbackImage() {
// 이미지 파일 객체 (예: 파일 선택 input 등에서 가져온 File 객체)
const imageFile = YOUR_IMAGE_FILE;
const result = await sendon.kakao.uploadFallbackImage([imageFile]);
console.log('이미지 업로드 결과:', result);
// 성공 시 result.data.imageIds에 업로드된 이미지 ID 배열이 포함됩니다
return result;
}
응답 형식
대체발송이 포함된 메시지 발송 요청이 성공적으로 처리되면 다음과 같은 응답을 받습니다:
{
"code": 200,
"message": "성공",
"data": {
"groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d"
}
}
주의사항
-
대체발송 처리 시점
- 대체문자는 카카오 메시지 발송 처리가 완료된 후, 미발송된 메시지에 대한 포인트가 환급된 이후에 발송됩니다.
-
포인트 차감
- 대체발송 시 알림톡/친구톡 포인트와 별도로 문자 메시지 발송에 필요한 포인트가 차감됩니다.
- 이로 인해 최초 포인트 차감액보다 더 많은 포인트가 차감될 수 있습니다.
-
포인트 부족
- 대체발송에 필요한 포인트가 부족한 경우 대체발송이 취소될 수 있습니다.
-
광고성 표시
- 광고성 메시지의 경우
isAd
값을true
로 설정해야 합니다. - 광고성 메시지는 관련 법규를 준수해야 합니다.
- 광고성 메시지의 경우
-
문자 길이 제한
- SMS: 90바이트 이내
- LMS: 2,000바이트 이내
- 바이트 계산 시 한글은 일반적으로 2~3바이트를 차지합니다.
-
인코딩 차이
- 카카오 메시지는 UTF-8 인코딩을 사용하고, 대체발송 문자는 EUC-KR 인코딩을 사용합니다.
- 이 차이로 인해 이모티콘이나 일부 특수 문자가 대체발송 문자에서 정상적으로 출력되지 않을 수 있습니다.
- 대체문자 설정 시 문자가 의도하지 않은 형태로 표시되지 않는지 확인하는 것이 좋습니다.
-
발신번호 등록
- 대체발송에 사용되는 발신번호(senderNumber)는 센드온 계정에 사전 등록되고 승인된 번호여야 합니다.
-
이미지 제한
- MMS 발송 시 이미지는 총 3개까지 첨부 가능합니다.
- 메시지 내용이 짧아도 이미지가 첨부되면 MMS로 분류됩니다.
-
템플릿 대체발송 제한
TEMPLATE
옵션은 알림톡에서만 사용 가능합니다.- 친구톡에서는
CUSTOM
옵션만 사용할 수 있습니다.
관련 링크
Updated 18 days ago
What’s Next