📆 Twilio 메시지 예약 전송 완전 정복 (SMS/WhatsApp Scheduling 가이드)

📘 본 문서는 Twilio 공식 문서인 Message Scheduling를 한국어로 번역/정리한 글입니다.
최신 정보 및 자세한 기능은 반드시 공식 문서를 참고해주세요.

---

Twilio의 Message Scheduling 기능은 미래의 특정 시점에 SMS, MMS, WhatsApp 메시지를 예약 전송할 수 있는 기능입니다. 이 기능은 Messaging Service를 통해서만 사용할 수 있으며, Engagement Suite에 포함되어 있습니다.

---

✅ 사전 조건

• 이미 메시지를 일반적으로 Twilio Messaging Service를 통해 전송할 수 있어야 함
• WhatsApp 메시지를 예약하려면 WhatsApp 발신 번호가 Messaging Service의 Sender Pool에 등록되어 있어야 하며, 사전 승인된 템플릿을 사용해야 함

---

✉️ 메시지 예약 전송 방식

Twilio에서 예약 메시지를 생성할 땐, 일반 메시지와 동일하게 Message 리소스를 생성하되,
두 가지 추가 파라미터를 포함해야 합니다:

파라미터	필수 값	설명
scheduleType	fixed	예약 전송을 의미하는 고정값
sendAt	ISO 8601 형식의 날짜 (2025-06-10T15:00:00Z)	메시지를 전송할 시점

그 외에도 아래 값들이 필요합니다:

• messagingServiceSid: 메시지를 전송할 Messaging Service의 SID
• body 또는 mediaUrl 또는 contentSid
• to: 수신자 번호 (예: +821012345678) 또는 WhatsApp 주소 (예: whatsapp:+821012345678)

🔒 제한사항

• 메시지는 전송 5분 전까지는 예약되어야 함
• 예약은 최대 35일 후까지 가능함

---

💻 예제 코드 (Node.js)

const twilio = require("twilio");
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function createMessage() {
  const message = await client.messages.create({
    body: "이건 예약된 메시지입니다.",
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    scheduleType: "fixed",
    sendAt: new Date("2025-06-10T15:00:00Z"),
    to: "+821012345678",
  });
  console.log(message.sid);
}

createMessage();

---

📩 Twilio 응답 예시

{
  "status": "scheduled",
  "sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "to": "+821012345678",
  "messaging_service_sid": "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

• 메시지가 정상 예약되면 HTTP 응답 코드 201과 함께 status: scheduled로 표시됨
• 메시지가 실패하면 400 오류 발생 (시간 형식 오류 등)

---

⚠️ 전송 시 실패할 수 있는 경우

1. 수신자가 Opt-Out 한 경우

예약 당시에는 생성되지만, 전송 시점에 해당 사용자가 차단(Opt-Out)했을 경우 메시지는 실패 처리됨 (21610)

→ 메시지 취소 API를 사용해 사전에 취소 가능

2. WhatsApp 템플릿 유효성 실패

템플릿은 메시지 생성 시가 아닌, 실제 전송 시점에 유효성 검사를 거침.
허용되지 않은 템플릿이면 전송 실패

---

🛑 예약 메시지 취소

async function cancelMessage() {
  const message = await client
    .messages("SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
    .update({ status: "canceled" });
  console.log(message.status); // canceled
}

• status: "canceled" 로 업데이트하면 예약이 취소됨
• 이때 status callback에는 canceled 이벤트가 전송됨

---

💡 유의사항

• 하나의 Twilio 계정(서브계정 포함) 당 최대 1,000,000개의 예약 메시지 생성 가능
• 예약 메시지는 예약된 순간부터 카운트됨

---

🏷️ 관련 문서

• Twilio Message Scheduling (공식 문서)
• Message Resource API 문서