Open in
เครื่องมือฟังก์ชัน
มอบเครื่องมือฟังก์ชันให้ AI เอเจนต์ของคุณเพื่อเรียกใช้ API ภายนอกระหว่างการสนทนา — ดึงข้อมูลลูกค้า จองนัดหมาย อัปเดตระเบียน — ด้วยพารามิเตอร์ที่กำหนดประเภท
เครื่องมือฟังก์ชันช่วยให้ AI เอเจนต์ของคุณเรียกใช้ API ภายนอกระหว่างการสนทนาทางโทรศัพท์ ใช้เพื่อค้นหาข้อมูลลูกค้า ตรวจสอบเวลาว่าง จองนัดหมาย หรือดำเนินการใดๆ ที่แบ็กเอนด์ของคุณรองรับ
วิธีการทำงาน
- กำหนดเครื่องมือด้วยสคีมา (อาร์กิวเมนต์ที่เครื่องมือรับได้)
- ระบุการกำหนดค่า
endpoint(ตำแหน่งที่ ThunderPhone เรียก API ของคุณ) หรือไม่ระบุก็ได้เพื่อรับการเรียกใช้เครื่องมือผ่านเว็บฮุกขององค์กร - ระหว่างการสนทนา AI จะตัดสินใจว่าเมื่อใดควรใช้เครื่องมือตามบทสนทนา
- ThunderPhone เรียก endpoint ของคุณพร้อมอาร์กิวเมนต์ของเครื่องมือ
- ระบบส่งการตอบกลับจาก API ของคุณกลับไปยัง AI เพื่อดำเนินบทสนทนาต่อ
| ความสามารถ | ตำแหน่งที่ทำงาน | การตั้งค่า |
|---|---|---|
| เครื่องมือในตัว | ThunderPhone | คำสั่งในพรอมป์ต์ เครื่องมือบางรายการต้องมีการตั้งค่าเอเจนต์ด้วย |
| การเชื่อมต่อแอป | ThunderPhone และผู้ให้บริการที่เชื่อมต่อ | เชื่อมต่อบัญชีและแนบการดำเนินการที่อนุมัติแล้ว |
| การเชื่อมต่อ API และเครื่องมือฟังก์ชัน | HTTP API ของคุณ | กำหนด endpoint และสคีมา หรือรับการเรียกใช้ฟังก์ชันผ่านเว็บฮุก |
| เซิร์ฟเวอร์ MCP | เซิร์ฟเวอร์ MCP ระยะไกล | เพิ่มเซิร์ฟเวอร์ ค้นหาเครื่องมือ และแนบเข้ากับเอเจนต์ |
สคีมาเครื่องมือ
เครื่องมือแต่ละรายการมีโครงสร้างดังนี้:
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots for a given date",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"service": {
"type": "string",
"description": "Type of service (e.g., 'consultation', 'follow-up')"
}
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-api-key"
}
},
"timeout": 120
}การกำหนดค่าเครื่องมือ
| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
|---|---|---|---|
timeout | ตัวเลข | ไม่ | เวลาดำเนินการสูงสุดเป็นวินาที (ค่าเริ่มต้น: 20 สูงสุด: 180 หรือ 600 เมื่อใช้ wait_mode: "hold") |
wait_mode | สตริง | ไม่ | สิ่งที่ผู้โทรได้ยินขณะที่เครื่องมือทำงาน: updates (ค่าเริ่มต้น) การแจ้งความคืบหน้าด้วยเสียงแบบสั้น หรือ hold เพลงพักสาย ดู การรอนาน: โหมดพักสายและตอบกลับภายหลัง |
call_start | ออบเจ็กต์ | ไม่ | เรียกใช้เครื่องมือโดยอัตโนมัติเมื่อเริ่มการโทรทุกสาย ก่อนคำทักทาย ดู เรียกใช้เครื่องมือเมื่อเริ่มการโทร |
คำจำกัดความฟังก์ชัน
| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
|---|---|---|---|
name | สตริง | ใช่ | ตัวระบุสำหรับเครื่องมือ ซึ่งไม่ซ้ำกันในบรรดาเครื่องมือของการเรียกหนึ่งครั้ง เอเจนต์แต่ละตัวอาจมีเครื่องมือของตนเองที่ใช้ชื่อเดียวกันได้ |
description | สตริง | ใช่ | อธิบายให้ AI ทราบว่าควรใช้เครื่องมือนี้เมื่อใด |
parameters | ออบเจ็กต์ | ใช่ | JSON Schema สำหรับอาร์กิวเมนต์ของเครื่องมือ |
การกำหนดค่า Endpoint
| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
|---|---|---|---|
url | string | ใช่ | URL endpoint ของ API คุณ |
method | string | ไม่ | เมธอด HTTP (ค่าเริ่มต้น: POST) |
headers | object | ไม่ | เฮดเดอร์แบบกำหนดเองที่จะรวมไว้ |
เส้นทางการเรียกใช้สองแบบ
คำขอที่เซิร์ฟเวอร์ของคุณได้รับขึ้นอยู่กับว่าเครื่องมือมี
endpoint หรือไม่:
เครื่องมือ ที่มี endpoint | เครื่องมือ ที่ไม่มี endpoint | |
|---|---|---|
| ปลายทางที่ส่งคำขอ | ส่งไปยัง endpoint.url โดยตรง | URL เว็บฮุกเดิม ขององค์กรคุณ |
| เนื้อหาคำขอ | รูปแบบคำขอที่เลือกไว้ (ค่าเริ่มต้นคืออาร์กิวเมนต์เปล่า) | ซองข้อมูล telephony.tool / web.tool |
| ส่วนหัว | endpoint.headers ของคุณ + X-ThunderPhone-Call-ID + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature รวมถึงหมายเลขของสายสำหรับการโทรศัพท์ | Content-Type + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature |
| คีย์สำหรับการลงนาม | ซีเคร็ตเว็บฮุกขององค์กร | ซีเคร็ตเว็บฮุกขององค์กร |
ทั้งสองเส้นทางเป็นแบบ บล็อก — AI กำลังรอผลลัพธ์อยู่ระหว่างประโยค
หมดเวลาเริ่มต้นคือ 20 วินาที ให้ตั้งค่า timeout ระดับบนสุดของเครื่องมือ
เพื่ออนุญาตให้ดำเนินการได้นานขึ้น สูงสุดถึงขีดจำกัดของแพลตฟอร์มที่ 180 วินาที ทำให้ตัวจัดการทำงานรวดเร็ว สำหรับการรอบุคคลหรืองานที่ใช้เวลานาน ให้ใช้
โหมดพักสาย สามารถใช้ร่วมกันได้:
ในการโทรที่องค์กรมี URL ของ webhook เครื่องมือที่มี endpoint จะถูก
เรียกโดยตรง และเครื่องมือที่เหลือจะกลับไปใช้ webhook
การเรียกใช้ endpoint โดยตรง
เมื่อ AI เรียกใช้เครื่องมือที่มี endpoint ThunderPhone จะส่ง
คำขอไปยัง URL ของคุณ:
ส่วนหัวคำขอ
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-keyส่วนหัวแบบกำหนดเองจาก endpoint.headers ของคุณจะถูกรวมไว้เสมอ
ตามเดิมทุกประการ พร้อมส่วนหัวที่อยู่ในเนมสเปซ ThunderPhone เหล่านี้:
X-ThunderPhone-Signature-V2— HMAC-SHA256 ที่มีการประทับเวลา ครอบคลุมเมธอด พาธ คิวรี และเนื้อความ โดยใช้ ซีเคร็ตเว็บฮุกขององค์กร เป็นคีย์ ตรวจสอบรายการนี้และปฏิเสธคำขอที่เก่ากว่า 5 นาที ดู ตรวจสอบลายเซ็นเว็บฮุกX-ThunderPhone-Signature— HMAC-SHA256 รุ่นเก่าของไบต์เนื้อความคำขอที่ตรงกันทุกประการ ใช้คีย์เดียวกัน และยังส่งให้ตัวตรวจสอบที่มีอยู่X-ThunderPhone-Call-ID— ID สายปัจจุบันX-ThunderPhone-From-NumberและX-ThunderPhone-To-Number— หมายเลข From และ To ของสายในรูปแบบ E.164 มีความหมายเดียวกับfrom_numberและto_numberในtelephony.complete: สำหรับสายขาออก From คือหมายเลขของเอเจนต์ และ To คือบุคคลที่โทรหา ระบบจะไม่ใส่หมายเลขเมื่อมีการปิดบังหมายเลขผู้โทรหรือเมื่อไม่ใช่หมายเลขโทรศัพท์X-ThunderPhone-Call-Direction—inboundหรือoutboundเพื่อให้คุณทราบว่าหมายเลขใดเป็นของลูกค้า
เฮดเดอร์หมายเลขสายจะส่งเฉพาะในการโทรศัพท์เท่านั้น การทดสอบผ่านเว็บ วิดเจ็ต เรียลไทม์ และ Talk ในเบราว์เซอร์ไม่มีหมายเลขโทรศัพท์ จึงไม่ส่งเฮดเดอร์เหล่านี้ การทดสอบสายจากเอดิเตอร์เอเจนต์และการจำลอง AI จะมีหมายเลขของผู้โทรที่จำลองไว้ ลายเซ็นไม่ครอบคลุมเฮดเดอร์: V2 ลงลายเซ็นบนการประทับเวลา เมธอด พาธ คิวรี และเนื้อความ หากต้องการให้หมายเลขมีลายเซ็น ให้อ่านจากเนื้อความแทน: รูปแบบคำขอ retell มีทั้งสามรายการ และ vapi มีหมายเลขของลูกค้า
จะตั้งค่า Content-Type: application/json เว้นแต่ endpoint.headers
ของคุณจะแทนที่ค่า — Content-Type แบบกำหนดเองจะมีผลเหนือกว่า
รูปแบบคำขอ
การเชื่อมต่อ API แต่ละรายการมีการตั้งค่า request_format เลือก vapi หรือ
retell เมื่อต้องการให้เครื่องมือที่นำเข้ายังคงเรียกใช้เอนด์พอยต์ที่สร้างมาเพื่อ
แพลตฟอร์มนั้น การเชื่อมต่อใหม่และการเชื่อมต่อที่มีอยู่จะใช้ค่าเริ่มต้นเป็น standard
สำหรับ POST / PUT / PATCH ThunderPhone จะซีเรียลไลซ์
envelope ที่เลือกในรูปแบบมาตรฐาน (เรียงลำดับคีย์ ตัวคั่นแบบกระชับ) ลายเซ็นทั้งสองรายการ
ครอบคลุมไบต์เหล่านี้อย่างแม่นยำ
มาตรฐาน
standard ส่งเฉพาะอาร์กิวเมนต์ของเครื่องมือโดยไม่มีตัวครอบ นี่คือค่าเริ่มต้นและคงเนื้อหาคำขอเดิมของ ThunderPhone ไว้ทุกไบต์:
{"date":"2025-01-02","service":"consultation"}Vapi
vapi ส่งข้อความเซิร์ฟเวอร์ tool-calls ของ Vapi
ในรูปแบบที่ Vapi ระบุไว้ call.id คือ ID การโทรของ ThunderPhone
ในการโทรศัพท์ call.customer.number คือหมายเลขของอีกฝ่าย เช่นเดียวกับใน
ออบเจ็กต์การโทรของ Vapi: ผู้โทรในการโทรเข้า และบุคคลที่ถูกโทรในการโทรออก ระบบจะไม่รวมฟิลด์นี้เมื่อหมายเลขดังกล่าวถูกปกปิดหรือไม่ใช่
หมายเลขโทรศัพท์ id ของ tool-call จะไม่ซ้ำกันสำหรับการเรียกใช้งานแต่ละครั้ง และ
นำกลับมาใช้เพื่อจับคู่กับผลลัพธ์ของเอนด์พอยต์ การโทรจะปรากฏทั้งใน toolCallList และ
toolWithToolCallList โดยมี function.arguments เป็นออบเจ็กต์ JSON:
{
"message": {
"type": "tool-calls",
"timestamp": 1725000000123,
"call": { "id": "987654321" },
"toolCallList": [
{
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"function": { "name": "search_appointments" },
"toolCall": {
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
}
]
}
}ระบบจะไม่ส่งฟิลด์เฉพาะของ Vapi เช่น assistant artifact และออบเจ็กต์ call
แบบเต็ม
ส่งคืน envelope การตอบกลับของ Vapi พร้อม ID การเรียกใช้เครื่องมือที่ตรงกัน:
{
"results": [
{
"toolCallId": "call_00112233445566778899aabbccddeeff",
"result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
}
]
}ThunderPhone จะส่งสตริง result ที่แกะ envelope แล้วให้ AI นอกจากนี้ยังรองรับ
ค่า JSON เพื่อความเข้ากันได้กับเอนด์พอยต์ที่ส่งคืนค่าอยู่แล้ว error ที่ส่งมาแทน result
จะถูกส่งคืนให้ AI เป็นข้อผิดพลาดของเครื่องมือ หากเอนด์พอยต์ส่งคืน envelope ของ Vapi
ที่มีรูปแบบไม่ถูกต้องหรือไม่ตรงกัน ThunderPhone จะบันทึกคำเตือนและกลับไปใช้การแยกวิเคราะห์
การตอบกลับมาตรฐานแทนที่จะทำให้การโทรล้มเหลว
Retell
retell ส่งคำขอที่ระบุไว้สำหรับฟังก์ชันแบบกำหนดเองของ Retell:
{
"name": "search_appointments",
"call": {
"call_id": "987654321",
"from_number": "+14155550199",
"to_number": "+14155550100",
"direction": "inbound"
},
"args": { "date": "2025-01-02", "service": "consultation" }
}ในการโทรศัพท์ ออบเจ็กต์ call จะมี call_id, from_number,
to_number และ direction (inbound หรือ outbound) ซึ่งเป็นชื่อฟิลด์ที่
ออบเจ็กต์การโทรศัพท์ของ Retell ใช้ โดยตรงกับส่วนหัวหมายเลขการโทร
และต่างจากส่วนหัวตรงที่ทั้งสองลายเซ็นครอบคลุมฟิลด์เหล่านี้ ระบบจะละเว้นหมายเลข
ที่ถูกปกปิดหรือไม่ใช่หมายเลขโทรศัพท์ สำหรับการทดสอบบนเว็บ วิดเจ็ต
เรียลไทม์ และ Talk บนเบราว์เซอร์ จะมีเพียง call_id เท่านั้น ThunderPhone
จะไม่รวมฟิลด์เฉพาะของ Retell ที่ไม่สามารถระบุได้อย่างถูกต้องขณะส่งคำขอ เช่น
agent_id, transcript, transcript_object, metadata หรือตัวแปร
แบบไดนามิก Retell ยอมรับเนื้อหาการตอบกลับทุกแบบ โดย ThunderPhone จะส่งต่อ
ตามการจัดการการตอบกลับมาตรฐาน
สำหรับ GET / DELETE อาร์กิวเมนต์จะถูกส่งเป็น พารามิเตอร์คิวรี
และเนื้อหาคำขอจะว่างเปล่าโดยไม่ขึ้นกับ request_format ลายเซ็น V2
ครอบคลุมสตริงคิวรีตามที่ส่ง ส่วนลายเซ็นแบบเดิมจะคำนวณจากสตริงไบต์ว่าง โปรดดู
ตรวจสอบลายเซ็น webhook
การตอบกลับ
ส่งคืนการตอบกลับ JSON พร้อมผลลัพธ์ของเครื่องมือ:
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}การตอบกลับจะถูกจัดรูปแบบและส่งให้ AI เพื่อสนทนาต่อ
การตอบกลับที่ไม่ใช่ JSON จะถูกห่อเป็น {"data": "<text>"};
การหมดเวลาและการเชื่อมต่อล้มเหลวจะถูกรายงานให้ AI เป็นข้อผิดพลาด เพื่อให้
เอเจนต์สามารถขออภัยและดำเนินการต่อแทนที่จะหยุดชะงัก
การส่งต่อแบบ webhook
เครื่องมือที่ไม่มี endpoint จะถูกส่งต่อไปยัง URL webhook แบบเดิมขององค์กรคุณ
เป็นคำขอ telephony.tool (การโทร) หรือ web.tool
(การโทรผ่านเว็บ) ที่มีลายเซ็น ซึ่งต่างจากการแจ้งเตือนการตรวจสอบ
ที่ส่งไปยัง endpoint ของ webhook หลังการดำเนินการ คำขอนี้คือ
การดำเนินการ — การตอบกลับ HTTP ของคุณคือผลลัพธ์ของเครื่องมือ
{
"type": "telephony.tool",
"data": {
"call_id": 987654321,
"tool_name": "search_appointments",
"arguments": { "date": "2026-04-21" },
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}web.tool มี origin_domain แทน from_number /
to_number ตอบกลับด้วยผลลัพธ์ของเครื่องมือในรูปแบบ JSON — โดยใช้สัญญาการตอบกลับเดียวกับการเรียก endpoint โดยตรง คำขอจะมีลายเซ็นด้วยความลับ webhook ขององค์กร พร้อมส่วนหัวลายเซ็นทั้งสองรายการ เช่นเดียวกับ webhook อื่นทั้งหมด
การรอนาน: โหมดพักสายและตอบภายหลัง
เครื่องมือบางรายการต้องรอบุคคล: ผู้จัดการอนุมัติส่วนลด หรือเจ้าของตอบคำถามใน Slack ตั้งค่า wait_mode เป็น "hold" สำหรับเครื่องมือเหล่านั้น
wait_mode: "updates" (ค่าเริ่มต้น) | wait_mode: "hold" | |
|---|---|---|
| สิ่งที่ผู้โทรได้ยิน | ข้อความเริ่มเครื่องมือ ตามด้วยข้อความสั้นๆ ว่า "ยังดำเนินการอยู่" หลังผ่านไปประมาณ 12 วินาที และอีกข้อความทุกประมาณ 15 วินาที | ข้อความเริ่มเครื่องมือ ตามด้วยเพลงพักสายจนกว่าผลลัพธ์จะมาถึง |
ค่าสูงสุดของ timeout | 180 วินาที | 600 วินาที |
| คำตอบที่รอดำเนินการ | ส่งต่อให้เอเจนต์เป็นผลลัพธ์ | เครื่องมือจะยังเปิดอยู่จนกว่าคุณจะส่งผลลัพธ์ |
ในโหมดพักสาย เอเจนต์จะพูดหนึ่งประโยคเมื่อเครื่องมือเริ่มทำงาน (ใช้คำพูดของเอเจนต์เอง หรือข้อความเริ่มเครื่องมือที่ตั้งค่าไว้บนเอเจนต์) จากนั้นผู้โทรจะได้ยินเพลงพักสาย เพลงจะค่อยๆ เบาลงก่อนที่เอเจนต์จะพูดผลลัพธ์ เครื่องมือที่ตอบภายในหนึ่งหรือสองวินาทีจะไม่มีเพลงเลย เมื่อเอเจนต์กำลังคุยกับเมนูโทรศัพท์หรือกล่องข้อความเสียง จะใช้การอัปเดตด้วยเสียงพูดแทน เนื่องจากเพลงอาจถูกตีความว่าเป็นคำตอบ ซึ่งรวมถึงสายที่ตรวจพบว่าเป็นเมนูหรือกล่องข้อความเสียงระหว่างพักสาย: เพลงจะหยุดและเปลี่ยนเป็นการอัปเดตด้วยเสียงพูด เช่นเดียวกับสายที่ไม่สามารถเล่นเพลงได้
หากผู้โทรพูดระหว่างพักสาย เพลงจะยังเล่นต่อและเอเจนต์จะยังไม่ตอบ เอเจนต์จะได้ยินสิ่งที่ผู้โทรพูดและตอบพร้อมกับผลลัพธ์ การวางสายจะสิ้นสุดสายและปิดเครื่องมือที่ยังเปิดอยู่
ตอบภายหลัง
การตอบกลับของเอนด์พอยต์คุณเองยังคงต้องมาถึงภายใน 180 วินาที หากต้องการพักสายผู้โทรนานกว่านั้น ให้ตอบกลับทันทีด้วยผลลัพธ์ที่รอดำเนินการ:
{ "status": "pending", "request_id": "ask-4471" }request_id คือสตริงใดก็ได้ที่มีความยาวไม่เกิน 200 อักขระ ซึ่งใช้ระบุคำขอนี้ในระบบของคุณ ผู้โทรจะอยู่ระหว่างพักสายจนกว่าคุณจะส่งผลลัพธ์สำหรับคำขอนั้นผ่าน
POST /v1/calls/{call_id}/tool-results
call_id คือส่วนหัว X-ThunderPhone-Call-ID ของคำขอเครื่องมือ
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_id": "ask-4471",
"result": { "answer": "Yes, book Tuesday at 10." }
}'เอเจนต์จะอ่าน result เป็นคำตอบของเครื่องมือ เช่นเดียวกับกรณีที่เอนด์พอยต์ของคุณส่งค่าดังกล่าวกลับมา หากไม่มีผลลัพธ์มาถึงก่อน timeout ของเครื่องมือ ซึ่งนับจากเวลาที่เรียกใช้เครื่องมือ เอเจนต์จะได้รับแจ้งว่าไม่มีคำตอบกลับมา และเสนอขั้นตอนถัดไปให้ผู้โทร เช่น การรับข้อความ
คุณสามารถส่งผลลัพธ์ได้ทันทีที่ต้องการ แม้ก่อนที่การตอบกลับแบบรอดำเนินการของคุณจะไปถึง ThunderPhone ค่า 202 หมายความว่าสายยอมรับผลลัพธ์แล้ว: คำขอที่เปิดอยู่รับผลลัพธ์นั้น หรือคำขอของเครื่องมือเองยังอยู่ระหว่างดำเนินการและคำตอบแบบรอดำเนินการของเครื่องมือจะรับผลลัพธ์นั้น ผลลัพธ์ที่ไม่มีคำขอใดรับไปเลย (เอนด์พอยต์ของคุณตอบสิ่งอื่นที่ไม่ใช่สถานะรอดำเนินการสำหรับ request_id นั้น) จะถูกทิ้ง
หากการเชื่อมต่อมีการแปลงการตอบกลับ (โค้ดที่เขียนการตอบกลับของเอนด์พอยต์คุณใหม่ก่อนที่เอเจนต์จะเห็น) การแปลงจะทำงานกับการตอบกลับของเอนด์พอยต์คุณเอง ก่อนที่ ThunderPhone จะตรวจหาคำตอบแบบรอดำเนินการ ดังนั้นการตอบกลับแบบรอดำเนินการต้องคง status และ request_id ไว้ การแปลงจะไม่ทำงานกับผลลัพธ์ที่คุณส่งภายหลัง: เอเจนต์จะได้รับผลลัพธ์นั้นตามที่คุณส่ง
เอเจนต์ฟูลดูเพล็กซ์ไม่มีเพลงพักสายหรือข้อความอัปเดต ดังนั้นในสายของเอเจนต์ประเภทนี้ เครื่องมือพักสายจะทำงานเหมือนเครื่องมือ updates: คำตอบแบบรอดำเนินการจะไปถึงเอเจนต์เป็นผลลัพธ์ของเครื่องมือ
การตอบกลับแบบรอดำเนินการจากเครื่องมือในโหมด updates จะไม่ถูกเปิดค้างไว้: เอเจนต์จะได้รับเป็นผลลัพธ์ของเครื่องมือ
การตรวจสอบลายเซ็น
การเรียกใช้เครื่องมือโดยตรงจะลงนามเช่นเดียวกับเว็บฮุก โดยใช้ความลับเว็บฮุกขององค์กรคุณเป็นคีย์:
X-ThunderPhone-Signature-V2ลงนามการประทับเวลา เมธอด พาธ และคิวรีตามที่ส่งมา รวมถึงไบต์ของเนื้อความแบบตรงตามต้นฉบับ ปฏิเสธคำขอที่มีการประทับเวลาห่างจากนาฬิกาของคุณเกิน 5 นาทีX-ThunderPhone-Signature(เวอร์ชันเดิม) ลงนามเฉพาะไบต์ของเนื้อความ โดยใช้สตริงไบต์ว่างสำหรับGET/DELETEส่วนหัวนี้ยังคงถูกส่งโดยไม่มีการเปลี่ยนแปลง
ตัวช่วยของ SDK จะตรวจสอบส่วนหัว V2 รวมถึงช่วงเวลา 5 นาที:
import json
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
app = FastAPI()
@app.post("/appointments/search")
async def search_appointments(request: Request):
body = await request.body()
query = request.scope.get("query_string", b"").decode("latin-1")
path = request.url.path + (f"?{query}" if query else "")
if not verify_signature(
request.headers.get("X-ThunderPhone-Signature-V2"),
secret=WEBHOOK_SECRET,
method=request.method,
path=path,
body=body,
):
raise HTTPException(status_code=401)
data = json.loads(body)
date = data["date"]
# Look up availability
slots = await get_available_slots(date)
return {"available_slots": slots}import express from "express";
import { verifySignature } from "@thunderphone/sdk";
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
const ok = verifySignature({
header: req.header('X-ThunderPhone-Signature-V2'),
secret: WEBHOOK_SECRET,
method: req.method,
path: req.originalUrl,
body: req.body,
});
if (!ok) return res.status(401).send('Invalid signature');
const { date, service } = JSON.parse(req.body);
// Look up availability
const slots = getAvailableSlots(date, service);
res.json({ available_slots: slots });
});สูตรฉบับเต็ม — สตริงที่ลงนาม ตัวอย่างแบบทำตามได้ โค้ดที่ไม่ใช้ SDK กรณี GET / DELETE และข้อควรทราบเมื่อไม่มีความลับ — อยู่ที่ ตรวจสอบลายเซ็นเว็บฮุก
ตัวอย่าง: โฟลว์การจองแบบครบถ้วน
นี่คือชุดเครื่องมือสำหรับระบบจองนัดหมายแบบครบถ้วน:
{
"tools": [
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"service": { "type": "string" }
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "book_appointment",
"description": "Book an appointment at a specific time",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"time": { "type": "string", "description": "HH:MM format" },
"customer_name": { "type": "string" },
"customer_phone": { "type": "string" }
},
"required": ["date", "time", "customer_name"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/book",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "cancel_appointment",
"description": "Cancel an existing appointment",
"parameters": {
"type": "object",
"properties": {
"confirmation_number": { "type": "string" }
},
"required": ["confirmation_number"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/cancel",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
}
]
}เรียกใช้เครื่องมือเมื่อเริ่มการโทร
เครื่องมือสามารถทำงานโดยอัตโนมัติเมื่อเริ่มสายโทรศัพท์ทุกสาย ก่อนที่เอเจนต์จะพูดคำแรก เพื่อให้คำทักทายใช้ผลลัพธ์ได้ กรณีทั่วไปคือการค้นหา CRM ด้วยหมายเลขของผู้โทร: "ยินดีต้อนรับกลับ Arthi! คุณต้องการสั่งรายการเดิมหรือไม่?"
ในแดชบอร์ด ให้เปิดการเชื่อมต่อ API และตั้งค่า เวลาที่ทำงาน เป็น
เมื่อเริ่มสายโทรศัพท์ทุกสาย จากนั้นกรอกค่าที่พารามิเตอร์แต่ละตัวจะได้รับ ผ่าน API ให้ตั้งค่า trigger ของการผสานรวมเป็น
call_start และตั้งค่า call_start_arguments
(การเชื่อมต่อ API) หรือเพิ่มบล็อก call_start
ลงในเครื่องมือแบบอินไลน์:
{
"type": "function",
"function": {
"name": "get_contact_by_phone",
"description": "Look up a customer by phone number.",
"parameters": {
"type": "object",
"properties": {
"business_id": {"type": "string"},
"phone_number": {"type": "string"}
},
"required": ["business_id", "phone_number"]
}
},
"endpoint": {"url": "https://crm.example.com/contacts/lookup"},
"call_start": {
"arguments": {
"business_id": "a0a81c23",
"phone_number": "{{caller_number}}"
}
}
}อาร์กิวเมนต์ต้องมีค่าสำหรับพารามิเตอร์ที่จำเป็นทุกตัว เนื่องจากไม่มีผู้ใดกรอกข้อมูลเมื่อเริ่มสาย ค่าอาจเป็นสตริง ตัวเลข หรือบูลีน ระบบจัดเก็บและส่งคืนค่าเหล่านี้เป็นข้อความธรรมดา และเอเจนต์จะเห็นค่าเหล่านี้ ดังนั้นให้เก็บข้อมูลลับ เช่น คีย์ API ไว้ในส่วนหัวของการเชื่อมต่อ ไม่ใช่ที่นี่ สตริงสามารถใช้ตัวยึดตำแหน่งเหล่านี้ได้:
| ตัวยึดตำแหน่ง | ค่า |
|---|---|
{{caller_number}} | บุคคลอีกฝ่ายในการโทรในรูปแบบ E.164 เช่น +61402122887: ผู้โทรสำหรับสายเรียกเข้า และบุคคลที่ถูกโทรสำหรับสายโทรออก |
{{caller_number_national}} | หมายเลขเดียวกันในรูปแบบภายในประเทศโดยไม่มีช่องว่าง เช่น 0402122887 |
{{agent_number}} | หมายเลขของเอเจนต์เอง |
ลักษณะการทำงาน:
- คำขอจะเหมือนกับคำขอที่การเรียกใช้เครื่องมือของเอเจนต์ส่งทุกประการ โดยมี endpoint ส่วนหัว รูปแบบคำขอ และลายเซ็นเดียวกัน
- เครื่องมือจะเริ่มทำงานเมื่อสายเริ่มต้น และทำงานระหว่างที่มีเสียงเชื่อมต่อ ข้อความแนะนำ หรือประกาศการบันทึกเสียงกำลังเล่นอยู่ คำทักทายจะรอผลลัพธ์ได้นานสูงสุดประมาณ 3 วินาทีนับจากจุดนั้น หากผลลัพธ์ช้ากว่า เอเจนต์จะได้รับผลลัพธ์ทันทีที่มาถึงเพื่อใช้ตลอดช่วงที่เหลือของสาย สำหรับสายโทรออก เครื่องมือจะเริ่มเมื่อมีการโทรออก จึงทำงานกับทุกความพยายาม รวมถึงสายที่ไม่มีผู้รับ
- สำหรับเอเจนต์ที่ผู้โทรพูดก่อน จะไม่มีคำทักทายให้รอ เอเจนต์จะได้รับผลลัพธ์ทันทีที่มาถึง
- ผลลัพธ์จะส่งให้เอเจนต์เป็นบริบทสำหรับทั้งสาย ระบุในพรอมต์ของคุณว่าเอเจนต์ควรใช้ผลลัพธ์อย่างไร มิฉะนั้นเอเจนต์จะไม่อ่านผลลัพธ์ออกเสียง
- หากเครื่องมือล้มเหลวหรือหมดเวลา เอเจนต์จะทักทายผู้โทรตามปกติและจะไม่กล่าวถึงเรื่องนี้
- เอเจนต์ยังสามารถเรียกใช้เครื่องมือนี้เองในภายหลังระหว่างสายได้
- เครื่องมือทำงานกับสายโทรศัพท์ รวมถึงสายทดสอบจากแดชบอร์ดไปยังโทรศัพท์ของคุณ และการจำลอง AI ซึ่งจะส่งหมายเลขของผู้โทรที่จำลองไปยัง endpoint ของคุณ เครื่องมือจะไม่ทำงานในการทดสอบ สนทนา บนเบราว์เซอร์หรือเซสชันวิดเจ็ตเว็บ ซึ่งไม่มีหมายเลขผู้โทร ในสายที่ปิดการแสดงหมายเลขผู้โทร หรือกับเอเจนต์ที่มีขั้นตอน
- เอเจนต์หนึ่งตัวเรียกใช้เครื่องมือเมื่อเริ่มสายได้สูงสุดสามรายการ โดยทำงานพร้อมกันทั้งหมด
ระบุผลลัพธ์ในพรอมต์ของคุณเพื่อให้เอเจนต์ทราบวิธีใช้ ตัวอย่างเช่น: "หากการค้นหาเมื่อเริ่มสายพบผู้โทร ให้ทักทายด้วยชื่อแรก"
แนวทางปฏิบัติที่ดีที่สุด
เขียนคำอธิบายให้ชัดเจน
ฟิลด์ description ช่วยให้ AI เข้าใจว่าเมื่อใดควรใช้เครื่องมือ โปรดระบุให้ชัดเจนว่าเครื่องมือทำอะไรและเหมาะจะใช้เมื่อใด
จัดการข้อผิดพลาดอย่างเหมาะสม
ส่งข้อความข้อผิดพลาดที่ AI เข้าใจได้ เช่น {"error": "No slots available for that date"} แทนข้อผิดพลาด 500 แบบทั่วไป
กระชับการตอบกลับ
ส่งคืนเฉพาะข้อมูลที่ AI ต้องใช้เพื่อสนทนาต่อไป ผลลัพธ์ของเครื่องมือจะคงอยู่ในการสนทนาและถูกอ่านซ้ำในทุกเทิร์นถัดไป ดังนั้นผลลัพธ์ขนาดใหญ่จะเพิ่มค่าใช้จ่ายและความล่าช้าตลอดช่วงที่เหลือของการโทร ผลลัพธ์ที่มีความยาวเกิน 100,000 อักขระจะถูกตัดให้เหลือเป็นตัวอย่างที่ AI ทราบว่าไม่สมบูรณ์ และในการโทรที่ยาวมาก ผลลัพธ์เก่าอาจถูกลบออกได้ (AI สามารถเรียกใช้เครื่องมืออีกครั้ง) เพิ่มพารามิเตอร์เพื่อให้ AI ค้นหาทีละรายการหรือหมวดหมู่ และใส่เนื้อหาอ้างอิงขนาดใหญ่ เช่น เมนูหรือแค็ตตาล็อก ไว้ในฐานความรู้ ปุ่ม ส่งคำขอทดสอบ ในแดชบอร์ดจะแสดงขนาดของแต่ละผลลัพธ์และเตือนเมื่อมีขนาดใหญ่
ใช้ฟิลด์ที่จำเป็นอย่างรอบคอบ
กำหนดฟิลด์เป็น required เฉพาะเมื่อจำเป็นจริง ๆ AI จะขอข้อมูลที่จำเป็นจากผู้ใช้ก่อนเรียกใช้เครื่องมือ
ที่เกี่ยวข้อง
สั่งการดำเนินการโทรที่แพลตฟอร์มจัดการให้ โดยไม่ต้องกำหนดเอนด์พอยต์
เครื่องมือที่แพลตฟอร์มจัดการให้สำหรับ HubSpot, Salesforce, Google Calendar, Google Sheets และ Cal.com — ไม่ต้องมีเอนด์พอยต์
เชื่อมต่อเซิร์ฟเวอร์ MCP และให้เอเจนต์เรียกใช้เครื่องมือของเซิร์ฟเวอร์
การผสานรวม REST ที่ใช้ซ้ำได้ ซึ่งคุณสามารถเชื่อมต่อกับเอเจนต์ได้
ตัวช่วยตรวจสอบเพียงรายการเดียวสำหรับ webhook และการเรียกใช้เครื่องมือ