카카오 메시지 발송 예약하기

센드온 SDK를 사용하여 카카오 알림톡 및 친구톡 메시지를 특정 시간에 예약 발송할 수 있습니다.

예약 발송 기능을 활용하면 시간에 맞춰 자동으로 메시지가 발송되어 다양한 비즈니스 상황에 효과적으로 대응할 수 있습니다.

예약 발송이 유용한 상황

  • 이벤트 알림 및 리마인더
  • 정기적인 공지사항
  • 시간대별 타겟 마케팅 메시지
  • 휴일 및 특별 프로모션 안내

예약 발송 설정 방법

메시지 발송 요청에 reservation 객체 파라미터를 추가하여 예약 발송을 설정할 수 있습니다.

기본 구조

reservation: {
  dateTime: '2023-12-25T09:00:00.000Z' // ISO 8601 형식의 날짜 문자열
}

ISO 8601 날짜 형식

예약 시간은 ISO 8601 형식의 날짜 문자열로 지정합니다:

  • 2023-12-25T09:00:00.000Z - 2023년 12월 25일 09시 00분 00초 (UTC)
  • 2023-12-25T09:00:00+09:00 - 2023년 12월 25일 09시 00분 00초 (KST, UTC+9)

중요 사항

  • 예약 시간은 현재 시간으로부터 최소 30분 이후로 설정해야 합니다.
  • 최대 예약 가능 기간은 센드온 플랫폼 정책을 따릅니다.

예약 발송 파라미터

메시지 발송 요청 파라미터

파라미터타입설명필수 여부
reservationobject예약 발송 설정 객체선택
reservation.dateTimestring예약 발송 시간(ISO 8601 형식)필수(reservation 사용 시)

예약 메시지 발송 시 응답 파라미터

파라미터타입설명필수 여부
groupIdstring예약 메시지의 그룹 ID필수

알림톡 예약 발송

알림톡 메시지를 특정 시간에 발송하도록 예약하는 예제입니다.

// 하루 후 예약 발송
const tomorrow = new Date()
tomorrow.setDate(tomorrow.getDate() + 1)

const result = await sendon.kakao.sendAlimTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  templateId: SENDON_EXAM_KAKAO_TEMPLATE_ID,
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  reservation: {
    dateTime: tomorrow.toISOString(),
  },
})

친구톡 예약 발송

친구톡 메시지를 특정 시간에 발송하도록 예약하는 예제입니다.

// 다음날 오전 10시로 예약 발송 설정
const tomorrow = new Date()
tomorrow.setDate(tomorrow.getDate() + 1)
tomorrow.setHours(10, 0, 0, 0)

const result = await sendon.kakao.sendFriendTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  messageType: 'FT', // FT: 텍스트형
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  message: '안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.',
  buttons: [
    {
      name: '자세히 보기',
      type: 'WL',
      urlMobile: 'https://example.com/promotion',
      urlPc: 'https://example.com/promotion',
    },
  ],
  reservation: {
    dateTime: tomorrow.toISOString(),
  },
})

다양한 예약 시간 설정 방법

JavaScript의 Date 객체를 활용하여 다양한 예약 시간을 설정할 수 있습니다.

// 1. 특정 날짜 및 시간 예약 (2023년 12월 25일 오전 10시 KST)
const specificDate = new Date('2023-12-25T10:00:00+09:00');

// 2. 내일 같은 시간 예약
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);

// 3. 3시간 후 예약
const threeHoursLater = new Date(Date.now() + 3 * 60 * 60 * 1000);

// 4. 다음 주 월요일 오전 9시 예약
const nextMonday = new Date();
nextMonday.setDate(nextMonday.getDate() + (8 - nextMonday.getDay()) % 7);
nextMonday.setHours(9, 0, 0, 0);

// 5. 매월 1일 오전 10시 예약 (다음 달)
const firstDayNextMonth = new Date();
firstDayNextMonth.setMonth(firstDayNextMonth.getMonth() + 1, 1);
firstDayNextMonth.setHours(10, 0, 0, 0);

// 예약 발송 설정에 적용
const result = await sendon.kakao.sendAlimTalk({
  // ... 다른 파라미터들 ...
  reservation: {
    dateTime: nextMonday.toISOString(), // 예: 다음 주 월요일 발송
  },
});

여러 수신자에게 동시 예약 발송

한 번의 API 호출로 여러 수신자에게 동일한 시간에 예약 발송할 수 있습니다.

// 특정 날짜 설정 (다음 달 1일 오전 9시)
const nextMonth = new Date();
nextMonth.setMonth(nextMonth.getMonth() + 1, 1);
nextMonth.setHours(9, 0, 0, 0);

const result = await sendon.kakao.sendAlimTalk({
  sendProfileId: SEND_PROFILE_ID,
  templateId: TEMPLATE_ID,
  to: [
    {
      phone: RECIPIENT_PHONE_NUMBER_1,
      variables: {
        '#{고객명}': '김고객',
        '#{포인트}': '5,000',
      },
    },
    {
      phone: RECIPIENT_PHONE_NUMBER_2,
      variables: {
        '#{고객명}': '이사용자',
        '#{포인트}': '3,000',
      },
    },
    {
      phone: RECIPIENT_PHONE_NUMBER_3,
      variables: {
        '#{고객명}': '박테스트',
        '#{포인트}': '10,000',
      },
    }
  ],
  reservation: {
    dateTime: nextMonth.toISOString(),
  },
});

응답 형식

예약 발송 요청이 성공적으로 처리되면 다음과 같은 응답을 받습니다:

{
  "code": 200,
  "message": "성공",
  "data": {
    "groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d"
  }
}
응답 필드타입설명
codenumber응답 코드 (200: 성공)
messagestring응답 메시지
data.groupIdstring예약 메시지의 고유 식별자

반환된 groupId는 예약 메시지 관리(취소, 즉시 발송 등)에 사용할 수 있으므로 저장해두는 것이 좋습니다.

예약 메시지 관리

예약 메시지 관리 API

API 메소드설명요청 파라미터
sendon.reserved.cancel예약된 메시지를 취소합니다groupId
sendon.reserved.sendNow예약된 메시지를 즉시 발송합니다groupId
sendon.reserved.getStatus예약 메시지의 상태를 조회합니다groupId

예약 메시지 취소하기

예약 발송 요청 시 반환되는 그룹 ID를 사용하여 예약된 메시지를 취소할 수 있습니다.

const alimtalkResult = await sendon.kakao.sendAlimTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  templateId: SENDON_EXAM_KAKAO_TEMPLATE_ID,
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  reservation: {
    dateTime: tomorrow.toISOString(),
  },
})

const result = await sendon.reserved.cancel(alimtalkResult.data.groupId)
Reservation reservation = new Reservation("2025-12-12 12:00:00");

SendAlimtalk sendAlimtalkResult = sendon.kakao.sendAlimtalk(new AlimtalkBuilder()
		.setProfileId(SENDON_EXAM_KAKAO_PROFILE_ID)
    .setTemplateId(SENDON_EXAM_KAKAO_TEMPLATE_ID)
    .setTo(Arrays.asList(SENDON_EXAM_KAKAO_TO_PHONE))
		.setReservation(reservation)                                                            
);

취소 응답 예시

{
  "code": 200,
  "message": "성공",
  "data": {
    "succeeded": 10, // 취소에 성공한 메시지 수
    "failed": 0      // 취소에 실패한 메시지 수
  }
}

주의사항

  • 예약 취소는 예약된 발송 시간보다 최소 10분 전에 요청해야 합니다.
  • 이미 발송이 시작된 메시지는 취소할 수 없습니다.
  • 그룹의 일부 메시지만 선택하여 취소할 수 없고, 그룹 전체만 취소 가능합니다.

예약 메시지 즉시 발송하기

예약된 메시지를 기다리지 않고 즉시 발송할 수 있습니다.

const alimtalkResult = await sendon.kakao.sendAlimTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  templateId: SENDON_EXAM_KAKAO_TEMPLATE_ID,
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  reservation: {
    dateTime: tomorrow.toISOString(),
  },
})

const result = await sendon.kakao.sendReservation(alimtalkResult.data.groupId);
Reservation reservation = new Reservation("2025-12-12 12:00:00");

SendAlimtalk sendAlimtalkResult = sendon.kakao.sendAlimtalk(new AlimtalkBuilder()
		.setProfileId(SENDON_EXAM_KAKAO_PROFILE_ID)
    .setTemplateId(SENDON_EXAM_KAKAO_TEMPLATE_ID)
    .setTo(Arrays.asList(SENDON_EXAM_KAKAO_TO_PHONE))
		.setReservation(reservation)                                                            
);


SendGroup sendGroup = sendon.kakao.sendGroup(sendAlimtalkResult.data.groupId);

즉시 발송 응답 예시

{
  "code": 200,
  "message": "성공",
  "data": {
    "succeeded": 10, // 즉시 발송으로 변경된 메시지 수
    "failed": 0      // 변경 실패한 메시지 수
  }
}

주의사항

  • 즉시 발송 전환은 모든 메시지가 예약 상태일 때만 가능합니다.
  • 일부라도 발송이 시작된 메시지가 있으면 즉시 발송 요청이 실패합니다.

주의사항

  1. 예약 시간 제한

    • 예약 시간은 현재 시간보다 최소 30분 이후로 설정해야 합니다.
    • 최대 예약 가능 기간은 센드온 플랫폼 정책에 따라 제한될 수 있습니다.
  2. 시간 형식

    • 예약 시간은 ISO 8601 형식의 날짜 문자열로 지정해야 합니다.
    • JavaScript의 toISOString() 메소드를 사용하여 적절한 형식으로 변환할 수 있습니다.
  3. 예약 메시지 관리

    • 예약 취소는 예약 시간 최소 10분 전에 요청해야 합니다.
    • 발송이 시작된 예약 메시지는 취소할 수 없습니다.
  4. 친구톡 발송 시간 제한

    • 친구톡은 야간 시간(20시~익일 08시)에는 발송이 제한됩니다.
    • 이 시간대에 예약 발송을 설정하면 발송에 실패할 수 있습니다.
  5. 응답 데이터 관리

    • 예약 발송 요청 성공 시 반환되는 Group ID를 저장하세요.
    • 이 Group ID는 예약 취소나 즉시 발송 등의 관리 작업에 필요합니다.
  6. 시간대 설정

    • 국제 표준시(UTC)와 한국 표준시(KST) 간의 차이를 고려하여 예약 시간을 설정하세요.
    • KST는 UTC+9이므로, 한국 시간으로 설정할 때 이 점을 유의해야 합니다.

관련 링크