Batch calls

POST/api/v1/calls/batchkey or session

Same worker, many contacts, one request. If your contacts belong to an ongoing process (leads, renewals, no-shows) a job is the better tool. Batch is for one-off campaigns.

Can take a while for big batches, the request is allowed 5 minutes.

Body

agentIduuidrequired

callsobject[]required

1 to 1000.

defaultScheduledAtISO 8601

Used when an item has none. Omit for "now".

defaultPriorityint

1 high, 5 normal, 10 low.default 5

retryConfigobject

{ maxRetries: 3, retryOnNoAnswer: true, retryOnBusy: true, retryOnFailed: false } is the default.

retryScheduleISO 8601[]

Exact retry times, applied to every call.

stopOnErrorboolean

Stop at the first failing item.default false

timezoneAwareConfigobject

Business hours, weekend rules. See below.

Each item in calls:

contactPhonestringrequired

E.164.

contactNamestring

contactEmailstring

scheduledAtISO 8601

Overrides the default.

priorityint

timezoneIANA

e.g. Europe/Helsinki. Used with timezoneAwareConfig.

callMetadataobject

metadataobject

Schedule precedence per item: timezone-aware slot, then item scheduledAt, then defaultScheduledAt, then now.

Timezone aware scheduling

Give each contact a timezone and tell us when it's polite to call:

{
  "agentId": "6f0c…",
  "timezoneAwareConfig": {
    "targetLocalTime": "10:00",
    "respectBusinessHours": true,
    "businessHoursStart": "09:00",
    "businessHoursEnd": "17:00",
    "allowedDaysOfWeek": [1, 2, 3, 4, 5],
    "autoDetectFromPhone": true,
    "fallbackTimezone": "Europe/Helsinki"
  },
  "calls": [
    { "contactPhone": "+358401234567", "timezone": "Europe/Helsinki" },
    { "contactPhone": "+14155552671" }
  ]
}

Both people get called at 10:00 their time on the next weekday. The second one has no timezone, so we infer it from the country code (autoDetectFromPhone), then fall back to fallbackTimezone. allowedDaysOfWeek uses 0 for Sunday. Invalid config is a 400 before anything is scheduled.

Response

201 all scheduled, 207 mixed, 400 none.

{
  "data": {
    "agentId": "…",
    "agent": { "id": "…", "name": "…" },
    "summary": { "totalRequested": 3, "successful": 2, "failed": 1, "partialSuccess": true, "stopped": false },
    "results": [
      { "index": 0, "success": true, "callId": "…", "contactPhone": "+358…" },
      { "index": 1, "success": false, "error": "Phone number is blocked", "contactPhone": "+358…" }
    ]
  },
  "meta": { "timestamp": "…", "message": "Scheduled 2 calls, 1 failed" }
}

Per-item errors: Invalid phone number format. Must be E.164 format, Phone number is blocked, Invalid scheduledAt format.

Body

Timezone aware scheduling

Response

On this page