ThunderPhone v3 พร้อมให้ใช้งานแล้วเริ่มใช้งานได้ด้วยตัวเอง ราคาเริ่มต้น 2 เซนต์ต่อนาที.อ่านประกาศเปิดตัว

Function Tools

เครื่องมือฟังก์ชัน

มอบเครื่องมือฟังก์ชันให้ AI เอเจนต์ของคุณเพื่อเรียกใช้ API ภายนอกระหว่างการสนทนา — ดึงข้อมูลลูกค้า จองนัดหมาย อัปเดตระเบียน — ด้วยพารามิเตอร์ที่กำหนดประเภท

เครื่องมือฟังก์ชันช่วยให้ AI เอเจนต์ของคุณเรียกใช้ API ภายนอกระหว่างการสนทนาทางโทรศัพท์ ใช้เพื่อค้นหาข้อมูลลูกค้า ตรวจสอบเวลาว่าง จองนัดหมาย หรือดำเนินการใดๆ ที่แบ็กเอนด์ของคุณรองรับ

วิธีการทำงาน

  1. กำหนดเครื่องมือด้วยสคีมา (อาร์กิวเมนต์ที่เครื่องมือรับได้)
  2. ระบุการกำหนดค่า endpoint (ตำแหน่งที่ ThunderPhone เรียก API ของคุณ) หรือไม่ระบุก็ได้เพื่อรับการเรียกใช้เครื่องมือผ่านเว็บฮุกขององค์กร
  3. ระหว่างการสนทนา AI จะตัดสินใจว่าเมื่อใดควรใช้เครื่องมือตามบทสนทนา
  4. ThunderPhone เรียก endpoint ของคุณพร้อมอาร์กิวเมนต์ของเครื่องมือ
  5. ระบบส่งการตอบกลับจาก 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

ฟิลด์ประเภทจำเป็นคำอธิบาย
urlstringใช่URL endpoint ของ API คุณ
methodstringไม่เมธอด HTTP (ค่าเริ่มต้น: POST)
headersobjectไม่เฮดเดอร์แบบกำหนดเองที่จะรวมไว้

เส้นทางการเรียกใช้สองแบบ

คำขอที่เซิร์ฟเวอร์ของคุณได้รับขึ้นอยู่กับว่าเครื่องมือมี 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 วินาทีข้อความเริ่มเครื่องมือ ตามด้วยเพลงพักสายจนกว่าผลลัพธ์จะมาถึง
ค่าสูงสุดของ timeout180 วินาที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 นาที:

Python
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}
Node.js
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 จะขอข้อมูลที่จำเป็นจากผู้ใช้ก่อนเรียกใช้เครื่องมือ


ที่เกี่ยวข้อง