배치 발신(캠페인) 생성

명단에 자동으로 전화를 거는 배치를 만듭니다. 생성 즉시 반환되며, 실제 발신은 동시 통화 한도·분당 발신 속도·발신 가능 시간대를 지켜가며 순차적으로 진행됩니다.

대상은 CallFlowId · AgentId · Url 중 정확히 하나를 지정합니다 (발신 API와 동일).

수신자별로 다른 값을 쓰려면 Tasks[].Variables에 넣습니다. 콜 플로우에서 {{변수명}}으로 참조합니다. 변수 이름은 영문/숫자/밑줄만 가능합니다(값은 한글 가능).

발신 차수(Rounds): 몇 번 걸지, 얼마 간격으로 걸지, 각 차수를 언제 걸지를 한 배열로 정합니다. 배열 인덱스가 곧 차수라 Rounds[0]이 1차 발신이고 그 뒤가 재시도입니다. 차수마다 시간대를 따로 줄 수 있어 “1차는 낮에, 안 받으면 2·3차는 저녁에” 같은 진행이 됩니다.

발신 가능 시간대: 광고성 전화는 21시~익일 8시 발신이 법으로 금지되어 있어 이 시간에는 Rounds[].Windows 설정과 무관하게 발신되지 않습니다. Windows는 그보다 더 좁게 제한할 때 사용합니다.

배치 발신은 계정별로 활성화가 필요합니다.

명단에 자동으로 전화를 거는 배치를 만듭니다. 생성 즉시 반환되며, 실제 발신은 동시 통화 한도·분당 발신 속도·발신 가능 시간대를 지켜가며 순차적으로 진행됩니다. **대상은 `CallFlowId` · `AgentId` · `Url` 중 정확히 하나**를 지정합니다 (발신 API와 동일). 수신자별로 다른 값을 쓰려면 `Tasks[].Variables`에 넣습니다. 콜 플로우에서 `{{변수명}}`으로 참조합니다. 변수 **이름**은 영문/숫자/밑줄만 가능합니다(값은 한글 가능). **발신 차수(`Rounds`)**: 몇 번 걸지, 얼마 간격으로 걸지, **각 차수를 언제 걸지**를 한 배열로 정합니다. 배열 인덱스가 곧 차수라 `Rounds[0]`이 1차 발신이고 그 뒤가 재시도입니다. 차수마다 시간대를 따로 줄 수 있어 "1차는 낮에, 안 받으면 2·3차는 저녁에" 같은 진행이 됩니다. **발신 가능 시간대**: 광고성 전화는 21시~익일 8시 발신이 법으로 금지되어 있어 이 시간에는 `Rounds[].Windows` 설정과 무관하게 발신되지 않습니다. `Windows`는 그보다 **더 좁게** 제한할 때 사용합니다. 배치 발신은 계정별로 활성화가 필요합니다.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

Request

This endpoint expects an object.

NamestringRequired

FromstringRequired

발신 번호 (계정에 등록된 번호)

Taskslist of objectsRequired

수신자 목록. 건수 제한은 없고 요청 본문 크기(10MB)가 상한이다 — 초과하면 413. 3만건 규모까지 한 번에 넣을 수 있다.

CallFlowIdstringOptional

콜 플로우로 발신. AgentId·Url과 배타.

AgentIdstringOptional

매니지드 에이전트로 발신. CallFlowId·Url과 배타.

UrlstringOptional

VoiceML을 반환할 URL. CallFlowId·AgentId와 배타.

StatusenumOptional

생성 직후 상태. 기본값 running(만들면 바로 발신 대기). paused 로 만들면 명단을 확인한 뒤 actions 의 resume 으로 시작한다.

Allowed values:

MachineDetectionenumOptional

자동응답기(음성사서함) 감지. 기본값 None(사용 안 함). Enable 은 감지만 해서 결과의 answeredBy 에 human·machine·unknown 을 남기고 통화는 그대로 진행합니다. Hangup 은 자동응답기로 판정되면 통화를 끊습니다. AMD 애드온이 활성화된 계정만 쓸 수 있고(없으면 422), 감지한 통화마다 요금이 붙습니다. 애드온 활성 여부는 발신할 때마다 다시 확인합니다 — 배치를 만든 뒤 애드온을 해지하면 남은 통화는 감지 없이 걸립니다(배치가 실패하지는 않습니다).

자동응답기(음성사서함) 감지. 기본값 None(사용 안 함). `Enable` 은 감지만 해서 결과의 `answeredBy` 에 human·machine·unknown 을 남기고 통화는 그대로 진행합니다. `Hangup` 은 자동응답기로 판정되면 통화를 끊습니다. **AMD 애드온이 활성화된 계정만** 쓸 수 있고(없으면 422), 감지한 통화마다 요금이 붙습니다. 애드온 활성 여부는 **발신할 때마다** 다시 확인합니다 — 배치를 만든 뒤 애드온을 해지하면 남은 통화는 감지 없이 걸립니다(배치가 실패하지는 않습니다).

Allowed values:

Roundslist of objectsOptional

발신 차수. 배열 인덱스가 곧 차수이고 Rounds[0] 이 1차 발신, 그 뒤가 재시도입니다. 생략하면 한 번 걸고 끝(발신 가능 시간대 전체)입니다. 최대 5개. 차수마다 시간대를 따로 줄 수 있는 것이 핵심입니다 — “1차는 낮(10~~18시)에 걸고, 안 받으면 2·3차는 받을 확률이 높은 저녁(18~~21시)에” 같은 진행을 한 배치로 표현합니다. 재시도도 최초 발신과 똑같이 동시통화 한도·분당 상한·발신 가능 시간대의 적용을 받습니다. 정책상의 시각이 그 차수의 시간대 밖이면 시간대가 열릴 때까지 기다렸다가 걸립니다 — 20시 50분에 실패한 통화의 “30분 뒤”는 21시 20분이지만 그 시각은 발신 금지라 실제로는 다음 열리는 시각에 걸립니다.

발신 차수. **배열 인덱스가 곧 차수**이고 `Rounds[0]` 이 1차 발신, 그 뒤가 재시도입니다. 생략하면 **한 번 걸고 끝**(발신 가능 시간대 전체)입니다. 최대 5개. 차수마다 시간대를 따로 줄 수 있는 것이 핵심입니다 — "1차는 낮(10~18시)에 걸고, 안 받으면 2·3차는 받을 확률이 높은 저녁(18~21시)에" 같은 진행을 한 배치로 표현합니다. 재시도도 최초 발신과 똑같이 동시통화 한도·분당 상한·발신 가능 시간대의 적용을 받습니다. 정책상의 시각이 그 차수의 시간대 밖이면 **시간대가 열릴 때까지 기다렸다가** 걸립니다 — 20시 50분에 실패한 통화의 "30분 뒤"는 21시 20분이지만 그 시각은 발신 금지라 실제로는 다음 열리는 시각에 걸립니다.

MessagePolicyobjectOptional

끝내 통화가 안 된 분께 보낼 문자. 생략하면 보내지 않습니다. 본문의 {{변수}} 는 그 수신자의 Variables 값으로 치환됩니다(콜 플로우 멘트와 같은 문법). 참조한 변수가 없는 수신자가 한 명이라도 있으면 400 으로 거절합니다 — 빈칸으로 나가는 문자는 되돌릴 수 없기 때문입니다. 문자는 통화가 실패한 직후 나갑니다(차수 시간대를 따로 기다리지 않습니다). 다만 법정 금지 시간(21~08시)에 걸리면 다음 날 아침으로 밀리고, 보낼 시점이 24시간 이상 지나면 보내지 않습니다(일시정지해 둔 배치를 며칠 뒤 재개했을 때 뒤늦은 문자가 나가는 것을 막습니다). ⚠️ 문자 발신번호 등록은 음성 발신 등록과 별개 절차입니다. 등록되지 않은 번호는 발송 요청이 성공해도 통신사에서 거절될 수 있어, 생성 응답의 warnings 로 알려 드립니다.

끝내 통화가 안 된 분께 보낼 문자. 생략하면 보내지 않습니다. 본문의 `{{변수}}` 는 그 수신자의 `Variables` 값으로 치환됩니다(콜 플로우 멘트와 같은 문법). 참조한 변수가 없는 수신자가 한 명이라도 있으면 400 으로 거절합니다 — 빈칸으로 나가는 문자는 되돌릴 수 없기 때문입니다. 문자는 통화가 실패한 **직후** 나갑니다(차수 시간대를 따로 기다리지 않습니다). 다만 법정 금지 시간(21~08시)에 걸리면 다음 날 아침으로 밀리고, 보낼 시점이 24시간 이상 지나면 보내지 않습니다(일시정지해 둔 배치를 며칠 뒤 재개했을 때 뒤늦은 문자가 나가는 것을 막습니다). ⚠️ 문자 발신번호 등록은 음성 발신 등록과 **별개 절차**입니다. 등록되지 않은 번호는 발송 요청이 성공해도 통신사에서 거절될 수 있어, 생성 응답의 `warnings` 로 알려 드립니다.

MaxConcurrencyintegerOptional

이 배치가 동시에 유지할 통화 수. 기본값: 1

PacingPerMinuteintegerOptional

분당 최대 발신 수. 기본값: 10

TimezonestringOptional

발신 시간대 판정 기준. 기본값: Asia/Seoul

StartAtdatetimeOptional

이 시각 이후부터 발신 시작

EndAtdatetimeOptional

이 시각이 지나면 남은 대상은 발신하지 않고 종료

PriorityintegerOptional

같은 계정에 배치가 여럿일 때 우선순위(높을수록 먼저). 기본값: 0

Response

생성 성공

batchIdstringOptional

namestringOptional

statusenumOptional

running=발신 중 · paused=일시정지(진행 중 통화는 유지) · canceled=취소 · completed=완료 · expired=EndAt 경과로 종료

fromstringOptional

callFlowIdstringOptional

agentIdstringOptional

urlstringOptional

maxConcurrencyintegerOptional

pacingPerMinuteintegerOptional

timezonestringOptional

startAtdatetime or nullOptional

endAtdatetime or nullOptional

machineDetectionenum or nullOptional

자동응답기 감지 모드. 사용하지 않는 배치는 null 입니다.

roundslist of objectsOptional

발신 차수. 배열 인덱스가 곧 차수이고 rounds[0] 이 1차 발신입니다. 길이 1 = 한 번 걸고 끝. 각 차수가 자기 시간창(windows)을 가집니다.

messagePolicyobject or nullOptional

끝내 통화가 안 된 분께 보낼 문자. null 이면 보내지 않습니다.

warningslist of stringsOptional

생성 응답에만 포함됩니다. 거절할 정도는 아니지만 알아야 하는 것들 — 발신번호에 문자 전송 이력이 없거나(문자 발신번호 미등록 가능성), 남은 문자 한도가 수신자 수보다 적은 경우입니다.

dateCreateddatetimeOptional

dateUpdateddatetimeOptional

countsmap from strings to integersOptional

상태별 수신자 수 (pending·dialing·done·failed·canceled·expired)

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

대상은 CallFlowId · AgentId · Url 중 정확히 하나를 지정합니다 (발신 API와 동일).

배치 발신은 계정별로 활성화가 필요합니다.

$	curl -X POST https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/call-batches \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"Name": "7월 예약 확인",
>	"From": "07052358010",
>	"Tasks": [
>	{
>	"To": "01012345678",
>	"Variables": {
>	"customer_name": "홍길동",
>	"visit_date": "7월 30일"
>	}
>	},
>	{
>	"To": "01087654321",
>	"Variables": {
>	"customer_name": "김영희",
>	"visit_date": "7월 31일"
>	}
>	}
>	],
>	"CallFlowId": "cf_9a8b7c6d",
>	"MachineDetection": "Enable",
>	"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"
>	}
>	]
>	}
>	],
>	"MessagePolicy": {
>	"OnFinalFail": {
>	"Body": "{{customer_name}}님, {{visit_date}} 예약 확인차 전화드렸는데 연결이 어려워 문자 남깁니다."
>	}
>	},
>	"MaxConcurrency": 3,
>	"PacingPerMinute": 20
>	}'

1	{
2	"batchId": "clx1a2b3c4d5e",
3	"name": "7월 예약 확인",
4	"status": "draft",
5	"from": "07052358010",
6	"callFlowId": "string",
7	"agentId": "string",
8	"url": "string",
9	"maxConcurrency": 1,
10	"pacingPerMinute": 1,
11	"timezone": "string",
12	"startAt": "2024-01-15T09:30:00Z",
13	"endAt": "2024-01-15T09:30:00Z",
14	"machineDetection": "Enable",
15	"rounds": [
16	{
17	"after": 1,
18	"on": [
19	"string"
20	],
21	"windows": [
22	{
23	"days": [
24	1
25	],
26	"start": "string",
27	"end": "string"
28	}
29	]
30	}
31	],
32	"messagePolicy": {
33	"onFirstFail": {
34	"body": "string"
35	},
36	"onFinalFail": {
37	"body": "string"
38	}
39	},
40	"warnings": [
41	"07052358010 번호로 문자가 전송된 이력이 없습니다. 문자 발신번호 등록은 음성과 별개 절차라, 등록되지 않은 번호는 발송 요청은 성공해도 통신사에서 전량 거절될 수 있습니다."
42	],
43	"dateCreated": "2024-01-15T09:30:00Z",
44	"dateUpdated": "2024-01-15T09:30:00Z",
45	"counts": {
46	"dialing": 3,
47	"done": 77,
48	"pending": 120
49	}
50	}