배치 발신 (캠페인)

개요

배치 발신은 수신자 명단을 등록해 두면 플랫폼이 알아서 순차적으로 전화를 거는 기능입니다. 예약 확인, 설문, 안내 통화처럼 같은 시나리오를 여러 사람에게 반복해야 할 때 사용합니다.

배치를 만들면 생성 API 는 즉시 반환됩니다. 실제 발신은 여기서 일어나지 않고, 디스패처가 동시통화 한도·분당 발신 속도·발신 가능 시간대를 보면서 명단을 하나씩 집어 갑니다. 그래서 수만 건짜리 배치를 만들어도 요청은 바로 끝납니다.

배치가 거는 대상

발신 시 실행할 시나리오는 CallFlowId · AgentId · Url 중 정확히 하나를 지정합니다. 일반 발신(createCall) 과 같은 규칙입니다.

제한 3층

배치는 세 가지 제한을 동시에 지킵니다. 셋 중 하나라도 막히면 그 시점에는 발신하지 않습니다.

여기에 더해 계정 전체의 동시통화 한도가 상위에 있습니다. 배치가 그 한도에 부딪히면 해당 시도는 실패로 처리되지 않고 잠시 후 다시 시도됩니다(아래 재시도 정책 참고).

자동응답기 감지

MachineDetection 으로 사람이 받았는지 자동응답기인지 판별할 수 있습니다. 기본은 꺼져 있고, 켜면 판별한 통화마다 요금이 붙습니다(AMD 부가서비스 필요). 판별만 하고 통화를 이어가는 Enable, 자동응답기면 끊는 Hangup 중에 고릅니다 — 자세한 내용은 빠른 시작을 보세요.

애드온 활성 여부는 발신할 때마다 다시 확인합니다. 배치를 만든 뒤 애드온을 해지하면 남은 통화는 감지 없이 걸립니다(배치가 실패하지는 않습니다).

발신 가능 시간대

시간대는 차수마다 지정합니다(Rounds[].Windows). Days 는 1(월)~7(일), Start/End 는 "HH:MM" 입니다.

"Timezone": "Asia/Seoul",
"Rounds": [
  { "Windows": [{ "Days": [1,2,3,4,5], "Start": "09:00", "End": "18:00" }] }
]

생략하면 법정 허용 시간(08:00~21:00) 전체입니다. 차수를 여러 개 두고 각각 다른 시간대를 주면 "1차는 낮에, 안 받으면 2·3차는 저녁에" 같은 진행이 됩니다 — 안 받았을 때 다시 걸기를 보세요.

StartAt / EndAt 으로 배치 자체의 시작·종료 시각도 지정할 수 있습니다. EndAt 이 지나면 남은 대상은 발신하지 않고 배치가 종료됩니다.

상태 모델

배치 상태

API 로 만든 배치는 기본이 running 입니다 — 만들면 바로 발신 대기 상태가 됩니다. 명단을 확인한 뒤 시작하고 싶다면 Status: "paused" 로 만들고 나중에 resume 하세요. (콘솔은 3만 건 규모 명단을 사람이 표로 확인할 수 있도록 paused 로 만듭니다.)

수신자 상태

안 받았을 때 다시 걸기

기본은 한 사람에게 한 번입니다. Rounds 에 차수를 더하면 통화가 안 됐을 때 다시 겁니다.

배열 인덱스가 곧 차수입니다 — Rounds[0] 이 1차 발신이고 그 뒤가 재시도입니다. 최대 5개.

"Rounds": [
  { "Windows": [{ "Days": [1,2,3,4,5], "Start": "10:00", "End": "18:00" }] },
  { "After": 30, "On": ["no-answer","busy"],
    "Windows": [{ "Days": [1,2,3,4,5], "Start": "18:00", "End": "21:00" }] },
  { "After": 45, "On": ["no-answer","busy"],
    "Windows": [{ "Days": [1,2,3,4,5], "Start": "18:00", "End": "21:00" }] }
]

위 예시는 1차를 낮(1018시)에 걸고, 안 받으면 2·3차를 저녁(1821시)에 겁니다. 차수마다 시간대를 따로 줄 수 있는 것이 핵심입니다 — 받을 확률이 높은 시간대에 재시도를 몰 수 있습니다.

1차에 After·On 을 쓸 수 없는 이유는 기준이 될 직전 통화가 없기 때문입니다. 발신 시작 시각은 StartAt 으로 지정하세요.

On 에는 다시 걸 통화 결과를 나열합니다. 차수마다 다르게 줄 수 있습니다.

재시도도 최초 발신과 똑같은 제한을 받습니다 — 동시통화 한도, 분당 발신 속도, 그 차수의 발신 가능 시간대가 그대로 적용됩니다. After 로 계산한 시각이 그 차수의 시간대 밖이면 시간대가 열릴 때까지 기다렸다가 겁니다(낮 10시 30분이 되어도 저녁 차수면 18시에 걸립니다). 예를 들어 20시 50분에 실패한 통화의 "30분 뒤" 재시도는 금지 시간대(21~08시)에 걸려 다음 날 아침 8시로 밀립니다.

수신자별 시도 횟수는 결과의 dialRound 로, 다음 시도 예정 시각은 expectedDialAt 으로 확인할 수 있습니다(시간대 제한이 이미 반영된 값입니다).

내부 재시도와는 다릅니다

위의 Rounds 재시도는 "전화를 안 받았을 때"이고, 이와 별개로 발신 자체가 실패했을 때의 내부 재시도가 항상 동작합니다. 둘은 서로의 횟수를 소모하지 않습니다.

• 일시적 실패(5xx·타임아웃): 되돌려 다시 시도하며, 최대 3회까지입니다.
• 영구 실패(잘못된 번호 등): 재시도 없이 즉시 failed.
• 동시통화 한도 초과: 그 번호의 잘못이 아니므로 횟수를 소모하지 않고 잠시 후 다시 집어 갑니다.

끝내 통화가 안 된 분께 문자 보내기

MessagePolicy 로 통화가 안 된 수신자에게 문자를 보낼 수 있습니다.

"MessagePolicy": {
  "OnFinalFail": { "Body": "{{customer_name}}님, 전화드렸는데 연결이 어려워 문자 남깁니다." }
}

• OnFirstFail — 첫 통화가 안 됐을 때 바로. 재시도 전화는 그 뒤에 이어집니다. (재시도 차수가 있어야 쓸 수 있습니다. 다시 걸지 않으면 첫 실패가 곧 최종 실패입니다.)
• OnFinalFail — 재시도를 모두 소진하고 끝내 통화가 안 됐을 때.

둘 다 지정하면 한 수신자가 문자를 2통 받습니다. 통화가 연결된 분께는 보내지 않습니다.

본문의 {{변수}} 는 그 수신자의 Variables 값으로 치환됩니다 — 통화 멘트와 같은 문법이라 명단에 넣은 {{customer_name}} 을 그대로 쓸 수 있습니다. 참조한 변수가 없는 수신자가 한 명이라도 있으면 배치 생성이 400 으로 거절됩니다(빈칸으로 나간 문자는 되돌릴 수 없습니다).

문자도 발신과 같은 시간대 제한을 지키며, 보낼 시점이 24시간 이상 지나면 보내지 않습니다 (일시정지해 둔 배치를 며칠 뒤 재개했을 때 뒤늦은 문자가 나가지 않도록). 배치를 취소하면 아직 보내지 않은 문자도 함께 취소됩니다.

콘솔과 API

콘솔의 배치 발신 화면에서 CSV 명단 업로드·진행 현황 확인· 결과 내려받기를 할 수 있습니다. API 와 같은 데이터를 보므로 섞어 써도 됩니다.

다음 단계

• 빠른 시작 — 배치 생성부터 제어까지 curl 예제
• 결과 조회 — 수신자별 결과와 콜 플로우 수집값 받기
• API 레퍼런스 — 전체 파라미터·응답 스키마