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

대체발송(Fallback)은 카카오 알림톡이나 친구톡 발송이 실패할 경우 자동으로 SMS, LMS, MMS 등 일반 문자메시지로 전환하여 발송하는 기능입니다. 이 기능을 통해 메시지 전달의 신뢰성을 높이고 다양한 상황에서 메시지가 수신자에게 도달할 수 있도록 보장할 수 있습니다.

대체발송이 필요한 상황

  • 수신자가 카카오톡을 사용하지 않는 경우
  • 수신자가 카카오톡 알림을 차단한 경우
  • 수신자가 비즈니스 채널과 친구 관계가 아닌 경우 (친구톡)
  • 카카오톡 서버 오류 등으로 발송이 실패한 경우

대체발송 유형

센드온 SDK에서는 다음과 같은 대체발송 유형을 지원합니다:

  1. SMS (Short Message Service)

    • 최대 90바이트 이내의 짧은 텍스트 메시지
    • 제목이나 이미지를 포함할 수 없음
  2. LMS (Long Message Service)

    • 최대 2,000바이트 이내의 긴 텍스트 메시지
    • 제목 포함 가능
  3. 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;
}

대체발송 파라미터

기본 파라미터

파라미터타입설명필수 여부
fallbackobject대체발송 설정 객체선택
fallback.fallbackTypestring대체발송 유형 ('NONE', 'TEMPLATE', 'CUSTOM')필수

CUSTOM 옵션 사용 시 파라미터

파라미터타입설명필수 여부
fallback.customobject대체발송 상세 설정CUSTOM 타입 필수
fallback.custom.typestring대체문자 유형 ('SMS', 'LMS', 'MMS')필수
fallback.custom.senderNumberstring발신번호 (센드온에 등록된 번호)필수
fallback.custom.messagestring메시지 내용필수
fallback.custom.isAdboolean광고성 메시지 여부필수
fallback.custom.titlestring메시지 제목LMS/MMS 선택
fallback.custom.imagesstring[]이미지 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"
  }
}

주의사항

  1. 대체발송 처리 시점

    • 대체문자는 카카오 메시지 발송 처리가 완료된 후, 미발송된 메시지에 대한 포인트가 환급된 이후에 발송됩니다.
  2. 포인트 차감

    • 대체발송 시 알림톡/친구톡 포인트와 별도로 문자 메시지 발송에 필요한 포인트가 차감됩니다.
    • 이로 인해 최초 포인트 차감액보다 더 많은 포인트가 차감될 수 있습니다.
  3. 포인트 부족

    • 대체발송에 필요한 포인트가 부족한 경우 대체발송이 취소될 수 있습니다.
  4. 광고성 표시

    • 광고성 메시지의 경우 isAd 값을 true로 설정해야 합니다.
    • 광고성 메시지는 관련 법규를 준수해야 합니다.
  5. 문자 길이 제한

    • SMS: 90바이트 이내
    • LMS: 2,000바이트 이내
    • 바이트 계산 시 한글은 일반적으로 2~3바이트를 차지합니다.
  6. 인코딩 차이

    • 카카오 메시지는 UTF-8 인코딩을 사용하고, 대체발송 문자는 EUC-KR 인코딩을 사용합니다.
    • 이 차이로 인해 이모티콘이나 일부 특수 문자가 대체발송 문자에서 정상적으로 출력되지 않을 수 있습니다.
    • 대체문자 설정 시 문자가 의도하지 않은 형태로 표시되지 않는지 확인하는 것이 좋습니다.
  7. 발신번호 등록

    • 대체발송에 사용되는 발신번호(senderNumber)는 센드온 계정에 사전 등록되고 승인된 번호여야 합니다.
  8. 이미지 제한

    • MMS 발송 시 이미지는 총 3개까지 첨부 가능합니다.
    • 메시지 내용이 짧아도 이미지가 첨부되면 MMS로 분류됩니다.
  9. 템플릿 대체발송 제한

    • TEMPLATE 옵션은 알림톡에서만 사용 가능합니다.
    • 친구톡에서는 CUSTOM 옵션만 사용할 수 있습니다.

관련 링크