---
title: "โทรออก (API)"
description: "ทริกเกอร์การโทรออกที่ขับเคลื่อนด้วย AI จากโค้ดของคุณเอง สำหรับโฟลว์แบบสำรวจ ติดตามผล หรือยืนยัน"
---

การโทรออกช่วยให้คุณส่งหมายเลขปลายทางและการกำหนดค่าเอเจนต์ให้ ThunderPhone แล้วให้ AI โทรแทนคุณ กรณีการใช้งานทั่วไป:

- การยืนยันนัดหมาย
- การโทรกลับเพื่อทำแบบสำรวจ
- การติดตามผล "ครั้งที่สอง" หลังจากรับสายไม่ทัน
- การแจ้งเตือนรูปแบบการจัดส่ง

<Note>
  โทรหาทั้งรายการใช่หรือไม่ ฟีเจอร์
  [**แคมเปญ**](/th/guides/outbound-campaigns) ของแดชบอร์ด
  (`/dashboard/campaigns`) รับไฟล์ CSV รายชื่อติดต่อ และจัดการ
  ช่วงเวลาโทรตามเขตเวลา การโทรพร้อมกัน และนโยบายการลองใหม่ให้คุณ
  คู่มือนี้ครอบคลุมการโทรแบบโปรแกรมครั้งเดียว
</Note>

## ข้อกำหนดเบื้องต้น

<Steps>
  <Step title="เตรียมหมายเลข VoIP">
    การโทรออกกำหนดให้คุณต้องเป็นเจ้าของ `from_number` ผ่าน
    [การเชื่อมต่อ VoIP](/api-reference/voip-connections) หมายเลข ThunderPhone
    ใช้สำหรับสายเข้าเท่านั้น ดู
    [นำหมายเลขของคุณมาใช้เอง](/th/guides/bring-your-own-numbers)
  </Step>
  <Step title="สร้างเอเจนต์">
    พรอมป์ต์สำหรับการโทรออกมักเริ่มต้นด้วยการที่เอเจนต์ระบุตัวตนและวัตถุประสงค์ —
    "สวัสดี นี่คือ Acme โทรมาเพื่อยืนยันนัดหมายของคุณสำหรับพรุ่งนี้เวลา 15:00 น.…"
    ตั้งค่า `outbound_speak_order` เป็น `agent_first` (ค่าเริ่มต้น)
  </Step>
  <Step title="รักษายอดคงเหลือให้เป็นบวก">
    การโทรออกจะส่งกลับ `402 Payment Required` หากยอดคงเหลือ ≤
    `$0.00` เติมเงินผ่าน
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    หรือเปิดใช้ [การเติมเงินอัตโนมัติ](/api-reference/billing#update-auto-reload)
  </Step>
</Steps>

## โทรด้วยเอเจนต์ที่บันทึกไว้

วิธีที่ง่ายที่สุด — อ้างอิงเอเจนต์ด้วย id:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'
```

การตอบกลับ:

```json
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` หมายความเพียงว่าระบบรับคำขอแล้ว — สาย
  **ยังไม่ได้เชื่อมต่อ** ตรวจสอบสถานะแบบวนซ้ำผ่าน
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  เพื่อดูสถานะปัจจุบัน (`in_progress` → `completed` / `failed`)
</Warning>

## โทรด้วยการกำหนดค่าแบบอินไลน์

หากคุณต้องการพรอมป์ต์ใช้ครั้งเดียวที่ไม่คุ้มค่าจะบันทึกเป็นเอเจนต์
ให้ส่ง `config` แทน โครงสร้างจะตรงกับสคีมาการตอบกลับของ
[เว็บฮุก `call.incoming`](/th/webhooks/call-incoming):

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## ติดตามสาย

ในขณะเดียวกัน ให้สมัครรับ
[เว็บฮุก `telephony.complete`](/th/webhooks/events) —
วิธีที่เร็วที่สุดในการทราบว่าสายสิ้นสุดแล้ว หากคุณไม่สามารถรับ
เว็บฮุกขาเข้าได้ ให้ตรวจสอบ `GET /v1/calls/{call_id}` ทุกสองสามวินาที
ระเบียนจะมี `end_reason`, `duration_seconds` และ URL ของไฟล์บันทึกเสียง
เมื่อสายสิ้นสุด

## รูปแบบความล้มเหลวที่ควรจัดการ

| ข้อผิดพลาด | วิธีแก้ไข |
|-------|-----|
| `402 Payment Required` | เติมเงินในยอดคงเหลือหรือเปิดใช้การเติมเงินอัตโนมัติ |
| `403` บล็อกการโทรออก (หมายเลข ThunderPhone) | ใช้หมายเลข VoIP แทน |
| `403` บล็อกการโทรออก (VoIP ที่ยังไม่ได้ยืนยัน) | เรียกใช้ [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | ยืนยันว่า `from_number` ตรงกับหมายเลขโทรศัพท์ที่คุณเป็นเจ้าของ |
| `502 Bad Gateway` | ความล้มเหลวชั่วคราวของ SIP / LiveKit สามารถลองใหม่ได้อย่างปลอดภัย |

## การควบคุมเวลาพักสาย

การโทรออกที่ใช้เวลานานเนื่องจากผู้รับสายตอบสนองช้า
(เมนู IVR คิว) สามารถกำหนดเพดานได้ด้วย `max_hold_seconds`:

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

เอเจนต์จะวางสายหากไม่ได้รับเสียงจากมนุษย์ภายใน
N วินาทีที่ผ่านมา ค่าเริ่มต้นคือ 900 (15 นาที)

---

## ขั้นตอนถัดไป

<CardGroup cols={2}>
  <Card title="ข้อมูลอ้างอิงการโทรออก" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    ทุกฟิลด์ของคำขอและรหัสข้อผิดพลาด
  </Card>
  <Card title="รับ call.complete" icon="bolt" href="/th/webhooks/call-complete">
    สตรีมการโทรออกที่เสร็จสิ้นไปยังระบบของคุณ
  </Card>
  <Card title="การเรียกเก็บเงิน" icon="credit-card" href="/api-reference/billing">
    เติมเงินอัตโนมัติเพื่อให้การโทรออกไม่ล้มเหลวเนื่องจากยอดคงเหลือ
  </Card>
  <Card title="ทดสอบเอเจนต์โทรออก" icon="flask" href="/th/guides/test-agents">
    ทดสอบการทำงานแบบไม่ส่งจริงของเอเจนต์โทรออกก่อนใช้งานจริง
  </Card>
</CardGroup>