เริ่ม Campaign

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

เริ่ม campaign โดยกำหนดทุกอย่างใน request เดียว

โทรเมื่อไร เวลาเริ่ม เวลาสิ้นสุด (ไม่บังคับ) และช่วงเวลาโทรในแต่ละวัน
โทรหาแต่ละคนกี่ครั้ง จำนวนครั้งที่โทร และเวลารอระหว่างแต่ละครั้ง
ใช้เบอร์ไหนโทรออก ให้ลูกค้าเห็น และ agent ใช้ AI voice ไหน (ใส่อย่างละค่าเดียว หรือหลายค่าให้ระบบสุ่ม)

campaign จะเปลี่ยนจาก DRAFT เป็น SCHEDULED ระบบเตรียม call ให้ recipient คนละหนึ่ง call แล้วเริ่มโทรเมื่อถึงเวลาเริ่ม และอยู่ในช่วงเวลาโทร field ที่บังคับมีแค่ startDateTime ส่วน field อื่นมีค่า default ทั้งหมด ถ้าส่ง field ที่ไม่มีในตารางด้านล่างมาจะได้ 400 รวมถึง maxConcurrentCalls ด้วย เพราะจำนวน call พร้อมกันตั้งค่าไว้ต่อองค์กร ไม่ได้ตั้งต่อ request

เริ่ม campaign ได้ ครั้งเดียว และต้องเริ่มจาก DRAFT เท่านั้น ถ้าเรียกซ้ำจะได้ 409 ถ้าต้องการโทรหา recipient ชุดเดิมอีกรอบ ให้สร้าง campaign ใหม่

Path parameters

ชื่อ	คำอธิบาย
`id`	ID ของ campaign (`campaignId` ที่ได้จาก สร้าง Campaign)

Body

โทรเมื่อไร

Field	Type	บังคับ	Default	คำอธิบาย
`startDateTime`	string (ISO-8601, UTC)	✅		เวลาที่เริ่มโทรได้เร็วที่สุด ถ้าใส่เวลาที่ผ่านไปแล้ว ระบบจะถือว่าเป็น “ตอนนี้”
`endDateTime`	string (ISO-8601, UTC) หรือ `null`		`null`	เวลาสิ้นสุด recipient ที่ยังไม่ได้โทรหาภายในเวลานี้จะเป็น `EXPIRED` ถ้าเป็น `null` คือไม่มีเวลาสิ้นสุด
`timeWindows`	object[]		จันทร์–ศุกร์ 09:00–19:00, เสาร์–อาทิตย์ 10:00–19:00	วันและช่วงเวลาที่เริ่มโทรได้ ใช้เวลาไทย ดูเพิ่มเติม

แต่ละรายการใน timeWindows

Field	Type	คำอธิบาย
`dayOfWeek`	integer 1–7	1 = วันจันทร์ … 7 = วันอาทิตย์ วันที่ไม่ได้ใส่ไว้ ระบบจะไม่โทรเลย
`time`	object[]	ช่วงเวลา `{ "start": "HH:MM", "end": "HH:MM" }` อย่างน้อยหนึ่งช่วง เป็นเวลาไทย และ `start` ต้องมาก่อน `end` ชั่วโมงต้องมี 2 หลัก เช่น `09:00` ไม่ใช่ `9:00` และส่งเป็น array ว่างไม่ได้

Retry

Field	Type	Default	คำอธิบาย
`maxAttempts`	integer ตั้งแต่ 1 ขึ้นไป	`1`	จำนวนครั้งที่โทรหา recipient แต่ละคนทั้งหมด นับครั้งแรกด้วย `3` = โทรครั้งแรก 1 ครั้ง + retry อีกไม่เกิน 2 ครั้ง
`retryInterval`	integer (มิลลิวินาที)	`3600000` (1 ชั่วโมง) เมื่อ `maxAttempts` มากกว่า 1 นอกนั้นเป็น `0`	เวลารออย่างน้อยหลัง call จบ ก่อนจะ retry ถ้า `maxAttempts` มากกว่า 1 ต้องตั้งอย่างน้อย `300000` (5 นาที) ถ้าไม่ใช่ ให้ส่ง `0` หรือไม่ต้องส่งมา `7200000` = 2 ชั่วโมง `14400000` = 4 ชั่วโมง ดูเพิ่มเติม

ระบบ retry call ที่เป็น NO_ANSWER, BUSY และ FAILED รวมถึง CANCELLED ด้วย (เช่น call ที่รอคิวนานเกินไป) ซึ่งกรณีนี้ ไม่นับเป็นหนึ่งครั้งที่โทร ถ้าติดต่อ recipient ได้แล้ว ระบบจะไม่โทรหาคนนั้นอีกใน campaign เดียวกัน

เบอร์โทรออก

Field	Type	Default	คำอธิบาย
`callerIds`	string[]	เบอร์ของ agent ถ้าไม่มีจะใช้เบอร์กลางของ Gowajee	เบอร์ที่ใช้โทรออก เขียนให้ตรงกับหน้า ระบบ → ตั้งค่า → เบอร์โทรศัพท์ ใส่เบอร์เดียว = ใช้เบอร์นั้นทุก call ใส่หลายเบอร์ = สุ่มใหม่ทุก call และตอน retry จะไม่ใช้เบอร์เดียวกับครั้งก่อน ดูเพิ่มเติม
`sipAccountId`	string (UUID)		Legacy ID ของ SIP account ที่มี `sipCallerId` อยู่ ต้องเป็น SIP account ขององค์กรเอง
`sipCallerId`	string (UUID)		Legacy ID ของเบอร์โทรออกหนึ่งเบอร์ ทุก call จะใช้เบอร์นี้ แนะนำให้ใช้ `callerIds` แทน ถ้าส่งมาทั้งคู่ ระบบใช้ `callerIds`

Voice

Field	Type	Default	คำอธิบาย
`ttsVoiceKeys`	string[]	voice ที่ตั้งไว้ใน agent	key ของ AI voice จาก รายการ Voice ใส่ key เดียว = ใช้ voice นั้นทุก call ใส่หลาย key = สุ่มใหม่ทุก call ถ้าส่ง field นี้มา call จะเปลี่ยนไปใช้ voice ของ TTS V2 ลองฟังก่อนได้ที่ Voice Lab ดูเพิ่มเติม

อื่น ๆ

Field	Type	Default	คำอธิบาย
`removeDuplicates`	boolean	`false`	ก่อนเริ่มโทร ตัด recipient ที่ agent นี้เคยโทรติดแล้ว (`COMPLETED`) ภายในช่วงเวลาที่ตั้งไว้ใน Duplicate Call Alert ออก ดูเพิ่มเติม

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"
  }
}

ถ้าส่ง removeDuplicates: true มา response จะมี "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."]
}

Error

body ใช้รูปแบบ error ปกติ ระบบตรวจตามลำดับด้านล่าง และตอบกลับตาม ข้อแรกที่ไม่ผ่าน

รูปแบบ body (400) ข้อนี้ตรวจก่อนเสมอ ถ้า body ผิดรูปแบบก็จะได้ 400 แม้ campaign จะเริ่มไปแล้ว
campaign (404)
campaign ต้องเป็น DRAFT (409) ถ้า body ถูกรูปแบบแต่ campaign เริ่มไปแล้ว จะได้ 409 เสมอ
เงื่อนไขของการตั้งเวลา (400)
องค์กรได้รับสิทธิ์โทรออก (403)
การตัด recipient ที่ซ้ำ (400) ตรวจเฉพาะเมื่อส่ง removeDuplicates: true

Status	`code`	`message`	สาเหตุ
`400`	`INVALID_ID`	`id must be a valid UUID`	`id` ใน path ไม่ใช่ UUID
`400`	`VALIDATION_FAILED`	`property <x> should not exist`	ส่ง field ที่ไม่มีในตารางด้านบน เช่น `maxConcurrentCalls` หรือ `retryIntervalMs`
`400`	`VALIDATION_FAILED`	`startDateTime must be a valid ISO 8601 date string`	ไม่ได้ส่ง `startDateTime` หรือวันที่ไม่ถูกต้อง `endDateTime` ก็ตรวจแบบเดียวกัน
`400`	`VALIDATION_FAILED`	`timeWindows.0.time.0.start must be HH:MM (24-hour, two-digit hour)`	เวลาไม่ได้อยู่ในรูปแบบ `HH:MM` ที่ชั่วโมงมี 2 หลัก เช่นส่ง `9:00` มา path ใน message บอกว่าผิดที่รายการไหน
`400`	`VALIDATION_FAILED`	`timeWindows.0.dayOfWeek must not be greater than 7`	`dayOfWeek` ไม่ใช่จำนวนเต็มตั้งแต่ 1 ถึง 7
`400`	`VALIDATION_FAILED`	`maxAttempts must not be less than 1`	`maxAttempts` ต้องเป็นจำนวนเต็มตั้งแต่ 1 ขึ้นไป
`400`	`VALIDATION_FAILED`	`callerIds should not be empty` / `ttsVoiceKeys should not be empty`	ส่ง `[]` มา ถ้าไม่ต้องการกำหนดค่า ให้ตัด field นี้ออกแทน
`400`	`VALIDATION_FAILED`	`sipAccountId must be a UUID`	`sipCallerId` ก็ตรวจแบบเดียวกัน
`400`	`VALIDATION_FAILED`	`Start date must be before end date`
`400`	`VALIDATION_FAILED`	`At least one time window must be provided`	`timeWindows` เป็น `[]`
`400`	`VALIDATION_FAILED`	`Time ranges must be provided for day N`	มีวันที่ส่ง `"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`	เปิด retry ไว้ แต่ `retryInterval` ต่ำกว่า 5 นาที ถ้าไม่ได้เปิด retry ค่าตั้งแต่ 1 ถึง 299999 ก็ไม่ผ่านเช่นกัน (message จะลงท้ายด้วย `(or 0)`) ให้ส่ง `0` หรือไม่ต้องส่งมา
`400`	`VALIDATION_FAILED`	`Unknown voice: <key>`	มีค่าใน `ttsVoiceKeys` ที่ไม่อยู่ใน รายการ Voice
`400`	`VALIDATION_FAILED`	`Unknown caller ID: <number>`	มีเบอร์ใน `callerIds` ที่ไม่ใช่เบอร์ขององค์กร
`400`	`VALIDATION_FAILED`	`Unknown SIP account`	`sipAccountId` ไม่ใช่ SIP account ขององค์กร
`400`	`VALIDATION_FAILED`	`Cannot set caller ID without specifying a SIP account`	ส่ง `sipCallerId` มาโดยไม่มี `sipAccountId`
`400`	`VALIDATION_FAILED`	`The specified caller ID does not belong to the selected SIP account`	`sipCallerId` ไม่ได้อยู่ใน SIP account นั้น
`400`	`VALIDATION_FAILED`	`Duplicate call alert is not enabled for this organization`	ส่ง `removeDuplicates: true` มา แต่องค์กรยังไม่ได้เปิดฟีเจอร์นี้
`400`	`VALIDATION_FAILED`	`All recipients are duplicates within the configured window`	ถ้าตัดรายการซ้ำด้วย `removeDuplicates` จะไม่เหลือ recipient ให้โทรเลย campaign จะยังเป็น `DRAFT`
`404`	`CAMPAIGN_NOT_FOUND`	`Campaign not found`	`id` ผิด หรือ campaign นี้เป็นขององค์กรอื่น
`409`	`CAMPAIGN_ALREADY_STARTED`	`Campaign has already been started (current status: …)`	campaign ไม่ได้เป็น `DRAFT` เริ่ม campaign ได้ครั้งเดียว ถ้าต้องการโทรหา recipient ชุดเดิมอีกรอบ ให้สร้าง campaign ใหม่
`403`	`CALLING_NOT_ALLOWED`	`Your organization is not allowed to make calls.`	องค์กรนี้ปิดสิทธิ์โทรออกอยู่ ติดต่อ Gowajee