Bulk Upsert Consents API (한국어 번역)

원문 링크: Twilio Docs - Bulk Upsert Consents

📢 소개

Bulk Upsert Consents API는 여러 연락처의 동의 상태를 한 번에 등록하거나 갱신할 수 있는 기능입니다. 현재는 SMS 채널만 지원하며, Pilot 단계에 있습니다. 즉, Twilio는 현재 초기 사용자들의 피드백을 받고 있으며, 이 기능을 미리 사용해보고 의견을 줄 수 있는 기회가 있다는 뜻입니다.

⚠️ 주의: 이 API는 HIPAA 인증 서비스가 아닙니다. 의료 정보를 다루는 시스템에서는 사용하지 마세요.

---

✅ 기능 개요

• 최대 25개의 consents 객체를 한 요청으로 생성하거나 업데이트 가능
• 각 요청은 고유한 correlation_id로 구분되어, 개별 응답 확인 가능
• 실패한 요청은 개별 correlation_id에 에러 메시지와 함께 응답됨

---

🔐 제한 사항

항목	제한
요청 수	분당 100건
응답 타임아웃	최대 3초 (99%는 1초 이내)

---

🔄 요청 포맷

POST https://accounts.twilio.com/v1/Consents/Bulk

Content-Type: application/x-www-form-urlencoded

요청 파라미터

• items (필수): 연락처의 동의 정보를 담은 객체 배열

  • contact_id: E.164 포맷의 전화번호 (예: +19999999991)
  • correlation_id: 32자리 UUID 문자열
  • sender_id: 메시징 서비스 SID 또는 전화번호
  • status: opt-in 또는 opt-out
  • source: website, offline, opt-in-message, opt-out-message, others
  • date_of_consent: ISO 8601 날짜 문자열 (선택)

예시 (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 createBulkConsents() {
  const bulkConsent = await client.accounts.v1.bulkConsents.create({
    items: [
      {
        contact_id: "+19999999991",
        correlation_id: "ad388b5a46b33b874b0d41f7226db2ef",
        sender_id: "MG00000000000000000000000000000000",
        date_of_consent: "2025-02-28T10:05:27Z",
        status: "opt-in",
        source: "website",
      },
      {
        contact_id: "+19",
        correlation_id: "02520cfa6c432f0e3ec3a38c122d428d",
        sender_id: "12345",
        date_of_consent: "2025-02-25T10:05:27Z",
        status: "opt-out",
        source: "opt-out-message",
      },
    ],
  });

  console.log(bulkConsent.items);
}

createBulkConsents();

---

📥 응답 구조

{
  "items": [
    {
      "correlation_id": "ad388b5a46b33b874b0d41f7226db2ef",
      "error_code": 0,
      "error_messages": []
    },
    {
      "correlation_id": "02520cfa6c432f0e3ec3a38c122d428d",
      "error_code": 30646,
      "error_messages": [
        "INVALID_CONTACT_ID"
      ]
    }
  ]
}

• error_code: 0이면 성공, 그 외에는 실패 코드
• error_messages: 유효성 검사 실패 시 메시지 포함

---

🧾 참고: 주요 에러 코드

• 30646: 잘못된 contact_id, 누락된 필드 등 유효성 검사 실패