Open in
โทรออก (API)
เรียกใช้การโทรออกที่ขับเคลื่อนด้วย AI จากโค้ดของคุณเอง — สำหรับขั้นตอนการสำรวจ การติดตามผล หรือการยืนยัน
การโทรออกช่วยให้คุณส่งหมายเลขปลายทางและการกำหนดค่าเอเจนต์ให้ ThunderPhone เพื่อให้ AI โทรออกแทนคุณ กรณีการใช้งานทั่วไป:
- การยืนยันนัดหมาย
- การโทรกลับเพื่อทำแบบสำรวจ
- การติดตามผลแบบ "ลองอีกครั้ง" หลังรับสายไม่ทัน
- การแจ้งเตือนลักษณะงานจัดส่ง
ข้อกำหนดเบื้องต้น
- เลือกหมายเลขที่เปิดใช้งานการโทรออก
ใช้หมายเลขที่คุณเป็นเจ้าของผ่าน การเชื่อมต่อ VoIP หรือขออนุญาต ใช้หมายเลข ThunderPhone ของคุณสำหรับการโทรออกจากหน้า Phone Numbers หมายเลข ThunderPhone เริ่มต้นเป็นแบบรับสายเข้าเท่านั้น ThunderPhone ตรวจสอบ คำขอแต่ละรายการด้วยตนเอง เมื่อได้รับอนุมัติแล้ว หมายเลขเหล่านั้นสามารถโทรออกได้สูงสุดตาม ขีดจำกัดรายวันที่อนุมัติ (รีเซ็ตเวลา 00:00 UTC) และเรียกใช้แคมเปญได้ รวมถึงคุณ สามารถขอเพิ่มขีดจำกัดได้ หมายเลข VoIP ของลูกค้าไม่มีขีดจำกัดรายวัน ดังนั้นจึงแนะนำ ให้ใช้สำหรับการโทรออก ดู นำหมายเลขของคุณมาใช้เอง
- สร้างเอเจนต์
พรอมต์สำหรับการโทรออกมักเริ่มต้นด้วยการที่เอเจนต์ แนะนำตัวเองและวัตถุประสงค์ — "สวัสดี นี่คือ Acme โทรมาเพื่อ ยืนยันนัดหมายของคุณสำหรับวันพรุ่งนี้เวลา 15:00 น.…" ตั้งค่า
outbound_speak_orderเป็นagent_first(ค่าเริ่มต้น) - รักษายอดคงเหลือให้เป็นบวก
การโทรออกจะส่งคืน
402 Payment Requiredหากยอดคงเหลือ ≤$0.00เติมเงินหรือเปิดใช้การเติมเงินอัตโนมัติใน Organization → Billing Settings บนแดชบอร์ด คีย์sk_live_ของคุณสามารถตรวจสอบยอดคงเหลือด้วยGET /v1/billingแต่ ไม่สามารถเติมเงินหรือเปลี่ยนการเติมเงินอัตโนมัติได้
โทรออกด้วยเอเจนต์ที่บันทึกไว้
วิธีที่ง่ายที่สุด — อ้างอิงเอเจนต์ด้วย ID:
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": "+14155552671",
"agent_id": 12
}'การตอบกลับ:
{ "call_id": 987654321, "status": "initiated" }โทรออกด้วยการกำหนดค่าแบบอินไลน์
หากคุณต้องการพรอมป์ต์แบบใช้ครั้งเดียวที่ไม่คุ้มค่ากับการบันทึกเป็นเอเจนต์
ให้ส่ง config แทน โครงสร้างจะตรงกับสคีมาการตอบกลับของ
call.incoming webhook:
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": "+14155552671",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'ควบคุมสิ่งที่จะเกิดขึ้นหลังการตรวจสอบความเงียบครั้งสุดท้าย
คุณยังส่งการตั้งค่าการดำเนินการสุดท้ายเมื่อเงียบแบบเดียวกันใน config แบบอินไลน์ที่ AI เอเจนต์ที่บันทึกไว้ใช้ได้:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"silence_final_action": "hang_up"
}
}ใช้ silence_final_action เพื่อเลือกสิ่งที่จะเกิดขึ้นหลังการตรวจสอบความเงียบครั้งสุดท้าย คุณยังส่ง silence_final_message ได้ และเมื่อการดำเนินการสุดท้ายคือการโอนสาย ให้ส่ง silence_transfer_destination
เพิ่มรายการคำลงใน config แบบอินไลน์
การโทรออกแบบอินไลน์สามารถรวมรายการ words เดียวกับ AI เอเจนต์ที่บันทึกไว้ได้
ใช้สิ่งนี้เมื่อต้องการให้การโทรปฏิบัติตามกฎการออกเสียงหรือการรับฟังแบบกำหนดเอง
โดยไม่ต้องบันทึก AI เอเจนต์ก่อน
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"prompt": "[REDACTED_LITERAL]",
"voice": "john",
"product": "spark",
"words": []
}
}ติดตามการโทร
การตอบกลับที่มีเวลา queued_at หมายความว่าความจุสำหรับโทรออกของ ThunderPhone กำลังถูกใช้งานอยู่: สายจะเริ่มโทรเมื่อมีช่องว่างภายใน 10 นาที และจะสิ้นสุดด้วย end_reason เป็น outbound_queue_timeout หากไม่มีช่องว่าง คุณไม่จำเป็นต้องลองใหม่ ดูสายที่อยู่ในคิว
พร้อมกันนั้น ให้สมัครรับ
เว็บฮุก telephony.complete —
วิธีที่รวดเร็วที่สุดในการทราบว่าสายสิ้นสุดแล้ว นอกจากนี้ยังสามารถสมัครรับ
call.status_changed เพื่อรับการอัปเดต
ความคืบหน้าแบบเรียลไทม์ เช่น กำลังโทร รับสายแล้ว ข้อความเสียง และการเปลี่ยนแปลงการพักสาย
หากไม่สามารถรับเว็บฮุกขาเข้าได้ ให้โพล GET /v1/calls/{call_id} ทุก ๆ
ไม่กี่วินาที ระเบียนจะมี end_reason, duration_seconds
และ URL ของไฟล์บันทึกเสียงเมื่อสายสิ้นสุดแล้ว
หากตั้งค่าเอเจนต์ให้ดึงข้อมูลที่มีโครงสร้างหลังการโทร ข้อมูลนั้นจะถูกส่งแยกต่างหากหลังจากการประมวลผลขั้นสุดท้ายเสร็จสิ้น
ส่งตัวแปรรายสายไปยังเอเจนต์ที่บันทึกไว้
เอเจนต์ที่บันทึกไว้สามารถใช้ตัวแทนค่า เช่น {{name}} หรือ {{name|there}} ใน
ข้อความพรอมป์ต์ได้ เมื่อโทรออกด้วย agent_id ให้ส่ง
variables พร้อมค่าของสายโทรนั้น:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}ใช้ค่าสตริงที่มีชื่อตามตัวแทนค่า ตัวแปรเหล่านี้ใช้กับ
เอเจนต์ที่บันทึกไว้ ตัวอย่าง config แบบอินไลน์ในคู่มือนี้ไม่ได้ใช้ตัวแปรเหล่านี้
รูปแบบความล้มเหลวที่ควรจัดการ
| ข้อผิดพลาด | วิธีแก้ไข |
|---|---|
402 Payment Required | เติมยอดคงเหลือหรือเปิดใช้การเติมเงินอัตโนมัติ |
400 พร้อม code: destination_not_allowed | ThunderPhone ไม่โทรไปยังหมายเลขนั้น: หมายเลขไม่ถูกต้อง หมายเลขฉุกเฉิน หมายเลขอัตราค่าบริการพิเศษ รหัสสั้น ประเทศที่ถูกคว่ำบาตร หรือรัฐในสหรัฐฯ ที่องค์กรของคุณบล็อกการโทรออก จากหมายเลข ThunderPhone สามารถโทรไปยังหมายเลขทั่วไปในสหรัฐฯ และแคนาดาได้ และสามารถโทรไปยังปลายทางระหว่างประเทศบางแห่งได้โดยคิดค่าบริการตามอัตราของปลายทาง reason ระบุสาเหตุ ดู ปลายทางที่ถูกบล็อก |
409 พร้อม retryable: false สำหรับหมายเลข ThunderPhone | ดำเนินการตาม code: ขอเปิดใช้การโทรออกในหน้าหมายเลขโทรศัพท์ รอการตรวจสอบที่กำลังดำเนินการอยู่ หรือใช้หมายเลขอื่นที่มีสิทธิ์ |
429 พร้อม code: platform_outbound_daily_limit_reached | องค์กรใช้โควต้าการโทรออกประจำวันจากหมายเลข ThunderPhone หมดแล้ว รอจนถึง resets_at (00:00 UTC) ขอเพิ่มขีดจำกัดในหน้าหมายเลขโทรศัพท์ หรือโทรจากหมายเลขบนการเชื่อมต่อ VoIP ของคุณเอง |
429 พร้อม code: concurrent_call_limit_reached | องค์กรมีสายที่กำลังดำเนินอยู่เท่ากับขีดจำกัดสายพร้อมกันแล้ว (ค่าเริ่มต้นคือ 20 โดยนับสายเข้า สายออก สายเว็บ และสายทดสอบ) ลองใหม่หลังจากจำนวนวินาทีในส่วนหัว Retry-After หรือเมื่อสายสิ้นสุดลง ส่งอีเมลไปที่ support@thunderphone.com เพื่อเพิ่มขีดจำกัด |
429 พร้อม code: outbound_queue_full | องค์กรมีสายที่อยู่ในคิว 50 สายที่กำลังรออยู่ ลองใหม่หลังจากจำนวนวินาทีในส่วนหัว Retry-After |
429 พร้อม code: same_number_too_soon | คุณโทรไปยัง to_number เดียวกันเมื่อไม่ถึง 10 วินาทีที่ผ่านมา ลองใหม่หลังจากจำนวนวินาทีในส่วนหัว Retry-After |
409 พร้อม retryable: false สำหรับหมายเลข VoIP ของลูกค้า | แก้ไขสถานะที่ระบุโดย code; สำหรับการยืนยันที่ล้มเหลว ให้เรียกใช้ POST /v1/phone-numbers/{id}/verify-voip |
ความขัดแย้งด้าน idempotency 409 | ใช้คีย์เดิมซ้ำกับคำขอที่ปรับรูปแบบแล้วต้นฉบับเท่านั้น หรือส่งคีย์ใหม่ |
404 from_number is not registered to this organization | ยืนยันว่า from_number ตรงกับหมายเลขโทรศัพท์ที่ใช้งานอยู่ในองค์กรของคุณ หมายเลขที่กำลังจัดเตรียม ล้มเหลว กำลังยกเลิก หรือถูกยกเลิกแล้วก็จะส่งการตอบกลับนี้เช่นกัน |
500 ที่มีเพียงฟิลด์ detail | ยังไม่ได้กำหนดค่า trunk สำหรับการโทรออก ติดต่อฝ่ายสนับสนุน ปัญหานี้ไม่ใช่ปัญหาสถานะหมายเลขที่คุณแก้ไขได้ |
502 Bad Gateway | ความล้มเหลวชั่วคราวของ SIP / LiveKit; สามารถลองใหม่ได้อย่างปลอดภัย |
ดูข้อมูลอ้างอิงการโทรออก
สำหรับรายการรหัสคุณสมบัติที่เสถียรฉบับสมบูรณ์และรูปแบบการตอบกลับ 409 ทั้งสองแบบ
หากหมายเลขที่ใช้งานอยู่ไม่มีสิทธิ์หลังจากรับคำขอแล้วแต่ก่อน
เริ่มโทร การตรวจสอบขั้นสุดท้ายจะส่งเพย์โหลด 409 ที่ลองใหม่ไม่ได้
ควบคุมเวลารอสาย
สายโทรออกที่ใช้เวลานานเนื่องจากผู้รับสายตอบสนองช้า
(ผัง IVR คิวรอสาย) สามารถจำกัดได้ด้วย max_hold_seconds ในสายโทร หรือกำหนดค่าในเอเจนต์ที่บันทึกไว้:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}เอเจนต์จะวางสายหากไม่ได้รับเสียงมนุษย์ภายใน N วินาทีที่ผ่านมา ค่าเริ่มต้นคือ 900 วินาที (15 นาที)
หากคุณกำหนด max_hold_seconds ทั้งในเอเจนต์ที่บันทึกไว้และคำขอสายโทรออก ระบบจะใช้ค่าต่อสายสำหรับสายนั้น