Start a campaign

POSThttps://api.voice-agent.gowajee.ai/api/campaign/:id/schedule

Starts a campaign. In one request you decide:

when calls may happen: the start time, an optional deadline, and the daily calling hours,
how often to try each person: attempts and the wait between them,
which phone numbers the customer sees, and which AI voices the agent uses (one of each, or several to shuffle).

The campaign goes from DRAFT to SCHEDULED, one call is prepared for each recipient, and dialling begins once the start time arrives inside a calling window. Only startDateTime is required. Everything else has a default. Any field not listed below is rejected with 400. That includes maxConcurrentCalls: the number of calls at the same time is set per organization, not per request.

A campaign can be started once, from DRAFT. Starting it again returns 409. To call the same people again, create a new campaign.

Path parameters

Name	Description
`id`	The campaign ID (`campaignId` from Create a campaign).

Body

When to call

Field	Type	Required	Default	Description
`startDateTime`	string (ISO-8601, UTC)	✅		The earliest time to start calling. A time in the past means “now”.
`endDateTime`	string (ISO-8601, UTC) or `null`		`null`	The deadline. Anyone not called by then becomes `EXPIRED`. `null` means no deadline.
`timeWindows`	object[]		Mon–Fri 09:00–19:00, Sat–Sun 10:00–19:00	The days, and the hours in Bangkok time, when calls may start. More

Each timeWindows item:

Field	Type	Description
`dayOfWeek`	integer 1–7	1 = Monday … 7 = Sunday. Days not listed get no calls.
`time`	object[]	One or more `{ "start": "HH:MM", "end": "HH:MM" }` ranges in Bangkok time, with `start` before `end`. Hours need two digits: `09:00`, not `9:00`. It can’t be empty.

Retries

Field	Type	Default	Description
`maxAttempts`	integer, 1 or more	`1`	Total calls per recipient, counting the first. `3` = 1 call + up to 2 retries.
`retryInterval`	integer (milliseconds)	`3600000` (1 hour) when `maxAttempts` is more than 1, otherwise `0`	Minimum wait after a call ends before the retry. When `maxAttempts` is more than 1 it must be at least `300000` (5 minutes). Otherwise send `0`, or leave it out. `7200000` = 2 hours, `14400000` = 4 hours. More

NO_ANSWER, BUSY and FAILED are retried. So is CANCELLED (for example a call that waited too long in the queue), and that doesn’t use up an attempt. Someone who was reached is never called again in the same campaign.

Caller numbers

Field	Type	Default	Description
`callerIds`	string[]	The agent’s numbers, or else Gowajee’s shared number	Outbound phone numbers, written exactly as on System → Settings → Phone Numbers. One number = every call uses it. Several = shuffled per call, and a retry never repeats the previous number. More
`sipAccountId`	string (UUID)		Legacy. The ID of the SIP account that holds `sipCallerId`. It must be one of your organization’s SIP accounts.
`sipCallerId`	string (UUID)		Legacy. The ID of one caller number. Pins every call to it. Prefer `callerIds`. If you send both, `callerIds` wins.

Voices

Field	Type	Default	Description
`ttsVoiceKeys`	string[]	The agent’s own voice setup	AI voice keys from the voice catalog. One key = every call uses it. Several = shuffled per call. Sending this switches the calls to the TTS V2 voices. Listen first at Voice Lab. More

Other

Field	Type	Default	Description
`removeDuplicates`	boolean	`false`	Before dialling, remove anyone this agent already reached (`COMPLETED`) within your Duplicate Call Alert window. More

Request

curl -X POST "https://api.voice-agent.gowajee.ai/api/campaign/eac2489c-672c-455e-ab8c-4e0ecd18d7dc/schedule" \
  -H "X-API-Key: $GOWAJEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDateTime": "2026-10-01T02:00:00.000Z",
    "endDateTime": "2026-10-07T11:00:00.000Z",
    "timeWindows": [
      { "dayOfWeek": 1, "time": [{ "start": "09:00", "end": "12:00" }, { "start": "13:00", "end": "18:00" }] },
      { "dayOfWeek": 2, "time": [{ "start": "09:00", "end": "18:00" }] },
      { "dayOfWeek": 3, "time": [{ "start": "09:00", "end": "18:00" }] },
      { "dayOfWeek": 4, "time": [{ "start": "09:00", "end": "18:00" }] },
      { "dayOfWeek": 5, "time": [{ "start": "09:00", "end": "18:00" }] }
    ],
    "maxAttempts": 3,
    "retryInterval": 14400000,
    "callerIds": ["+6621234567", "+6621234568"],
    "ttsVoiceKeys": ["nicha", "suda"]
  }'

const HOUR = 60 * 60 * 1000;
const weekday = { time: [{ start: '09:00', end: '18:00' }] };

const res = await fetch(`https://api.voice-agent.gowajee.ai/api/campaign/${campaignId}/schedule`, {
  method: 'POST',
  headers: { 'X-API-Key': process.env.GOWAJEE_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    startDateTime: '2026-10-01T02:00:00.000Z',
    timeWindows: [1, 2, 3, 4, 5].map((dayOfWeek) => ({ dayOfWeek, ...weekday })),
    maxAttempts: 3,
    retryInterval: 4 * HOUR,
    callerIds: ['+6621234567', '+6621234568'],
    ttsVoiceKeys: ['nicha', 'suda'],
  }),
});

HOUR_MS = 60 * 60 * 1000
res = requests.post(
    f"https://api.voice-agent.gowajee.ai/api/campaign/{campaign_id}/schedule",
    headers={"X-API-Key": os.environ["GOWAJEE_API_KEY"]},
    json={
        "startDateTime": "2026-10-01T02:00:00.000Z",
        "timeWindows": [
            {"dayOfWeek": d, "time": [{"start": "09:00", "end": "18:00"}]} for d in range(1, 6)
        ],
        "maxAttempts": 3,
        "retryInterval": 4 * HOUR_MS,
        "callerIds": ["+6621234567", "+6621234568"],
        "ttsVoiceKeys": ["nicha", "suda"],
    },
    timeout=60,
)

Response

{
  "success": true,
  "message": "Campaign schedule updated successfully",
  "data": {
    "id": "eac2489c-672c-455e-ab8c-4e0ecd18d7dc",
    "status": "SCHEDULED"
  }
}

With removeDuplicates: true the response also has "removedRecipients": 12.

{
  "success": false,
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "Unknown voice: nichaa",
  "errors": ["Unknown voice: nichaa"]
}

{
  "success": false,
  "statusCode": 404,
  "code": "CAMPAIGN_NOT_FOUND",
  "message": "Campaign not found",
  "errors": ["Campaign not found"]
}

{
  "success": false,
  "statusCode": 409,
  "code": "CAMPAIGN_ALREADY_STARTED",
  "message": "Campaign has already been started (current status: RUNNING). Only a DRAFT campaign can be started; create a new campaign to call these recipients again.",
  "errors": ["Campaign has already been started (current status: RUNNING). Only a DRAFT campaign can be started; create a new campaign to call these recipients again."]
}

{
  "success": false,
  "statusCode": 403,
  "code": "CALLING_NOT_ALLOWED",
  "message": "Your organization is not allowed to make calls.",
  "errors": ["Your organization is not allowed to make calls."]
}

Errors

The body is the usual error envelope. The checks run in this order, and the first one that fails decides the response:

The body shape (400). This runs first, so a malformed body gets 400 even on a campaign that was already started.
The campaign (404).
The campaign is DRAFT (409). A well-formed body on a started campaign always gets 409.
The schedule rules (400).
Calling is allowed for your organization (403).
Duplicate removal (400), only when you send removeDuplicates: true.

Status	`code`	`message`	Cause
`400`	`INVALID_ID`	`id must be a valid UUID`	The `id` in the path isn’t a UUID.
`400`	`VALIDATION_FAILED`	`property <x> should not exist`	A field that isn’t listed above, for example `maxConcurrentCalls` or `retryIntervalMs`.
`400`	`VALIDATION_FAILED`	`startDateTime must be a valid ISO 8601 date string`	`startDateTime` is missing or isn’t a valid date. The same check applies to `endDateTime`.
`400`	`VALIDATION_FAILED`	`timeWindows.0.time.0.start must be HH:MM (24-hour, two-digit hour)`	A time isn’t two-digit `HH:MM`, for example `9:00`. The path in the message points to the item.
`400`	`VALIDATION_FAILED`	`timeWindows.0.dayOfWeek must not be greater than 7`	`dayOfWeek` isn’t a whole number from 1 to 7.
`400`	`VALIDATION_FAILED`	`maxAttempts must not be less than 1`	`maxAttempts` must be a whole number, 1 or more.
`400`	`VALIDATION_FAILED`	`callerIds should not be empty` / `ttsVoiceKeys should not be empty`	You sent `[]`. Leave the field out instead.
`400`	`VALIDATION_FAILED`	`sipAccountId must be a UUID`	The same for `sipCallerId`.
`400`	`VALIDATION_FAILED`	`Start date must be before end date`
`400`	`VALIDATION_FAILED`	`At least one time window must be provided`	`timeWindows` is `[]`.
`400`	`VALIDATION_FAILED`	`Time ranges must be provided for day N`	A day has `"time": []`.
`400`	`VALIDATION_FAILED`	`Start time must be before end time for day N`
`400`	`VALIDATION_FAILED`	`retryInterval must be at least 300000 ms (5 minutes) when maxAttempts is more than 1`	Retries are on and `retryInterval` is under 5 minutes. With retries off, a value from 1 to 299999 is also rejected (the message ends in `(or 0)`): send `0` or leave it out.
`400`	`VALIDATION_FAILED`	`Unknown voice: <key>`	A `ttsVoiceKeys` entry isn’t in the voice catalog.
`400`	`VALIDATION_FAILED`	`Unknown caller ID: <number>`	A `callerIds` entry isn’t one of your organization’s numbers.
`400`	`VALIDATION_FAILED`	`Unknown SIP account`	`sipAccountId` isn’t one of your organization’s SIP accounts.
`400`	`VALIDATION_FAILED`	`Cannot set caller ID without specifying a SIP account`	`sipCallerId` was sent without `sipAccountId`.
`400`	`VALIDATION_FAILED`	`The specified caller ID does not belong to the selected SIP account`	`sipCallerId` isn’t in that SIP account.
`400`	`VALIDATION_FAILED`	`Duplicate call alert is not enabled for this organization`	`removeDuplicates: true`, but the feature is off.
`400`	`VALIDATION_FAILED`	`All recipients are duplicates within the configured window`	`removeDuplicates` would leave nobody to call. The campaign stays `DRAFT`.
`404`	`CAMPAIGN_NOT_FOUND`	`Campaign not found`	Wrong `id`, or the campaign belongs to another organization.
`409`	`CAMPAIGN_ALREADY_STARTED`	`Campaign has already been started (current status: …)`	The campaign isn’t `DRAFT`. A campaign can be started once. Create a new one to call people again.
`403`	`CALLING_NOT_ALLOWED`	`Your organization is not allowed to make calls.`	Calling is turned off for your organization. Contact Gowajee.