כלי פונקציות

כלי פונקציה מאפשרים לסוכני ה-AI שלכם להפעיל ממשקי API חיצוניים במהלך שיחות טלפון. השתמשו בהם כדי לחפש נתוני לקוחות, לבדוק זמינות, לקבוע פגישות או לבצע כל פעולה שה-backend שלכם תומך בה.

איך זה עובד

הגדירו כלים באמצעות סכימה (אילו ארגומנטים הכלי מקבל)
ספקו תצורת endpoint (המקום שבו ThunderPhone קורא ל-API שלכם) — או השמיטו אותה כדי לקבל קריאות לכלים ב-webhook של הארגון שלכם
במהלך שיחה, ה-AI מחליט מתי להשתמש בכלי על סמך השיחה
ThunderPhone קורא ל-endpoint שלכם עם ארגומנטי הכלי
תגובת ה-API שלכם מוחזרת ל-AI כדי להמשיך את השיחה

כלי פונקציה הם הנתיב לשימוש ב-API משלכם. ThunderPhone כולל גם כלים המנוהלים על ידי הפלטפורמה ואינם דורשים endpoint: חיבורי אפליקציות (HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, Cal.com), חיבורי API, וכן שרתי 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"
    }
  }
}

הגדרת פונקציה

שדה	סוג	נדרש	תיאור
`name`	string	כן	מזהה ייחודי לכלי
`description`	string	כן	מסביר ל-AI מתי להשתמש בכלי זה
`parameters`	object	כן	סכימת JSON עבור ארגומנטי הכלי

תצורת Endpoint

שדה	סוג	נדרש	תיאור
`url`	string	כן	כתובת ה-endpoint של ה-API שלכם
`method`	string	לא	שיטת HTTP (ברירת מחדל: `POST`)
`headers`	object	לא	כותרות מותאמות אישית שיש לכלול

תצורת ה-endpoint אינה נשלחת למודל ה-AI — היא משמשת את ThunderPhone בלבד להפעלת קריאת הכלי.

שני נתיבי הפעלה

הבקשה שהשרת שלכם מקבל תלויה בשאלה אם לכלי יש endpoint:

	כלי עם `endpoint`	כלי ללא `endpoint`
יעד הבקשה	ישירות אל `endpoint.url`	כתובת ה-webhook הישנה של הארגון שלכם
גוף הבקשה	ארגומנטי כלי בלבד	מעטפת `telephony.tool` / `web.tool`
כותרות	`endpoint.headers` שלכם + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
מפתח חתימה	סוד ה-webhook של הארגון	סוד ה-webhook של הארגון

שני הנתיבים הם חוסמים — ה-AI ממתין באמצע המשפט לתוצאה — עם זמן קצוב של 20 שניות. הקפידו שהמטפלים יהיו מהירים. אפשר לשלב ביניהם: בשיחה שבה לארגון יש כתובת webhook, כלים עם endpoint נקראים ישירות והשאר חוזרים ל-webhook.

קריאות ישירות לנקודות קצה

כאשר ה-AI מפעיל כלי שיש לו endpoint, ThunderPhone שולחת בקשה לכתובת ה-URL שלכם:

כותרות בקשה

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-Api-Key: your-api-key

כותרות מותאמות אישית מתוך endpoint.headers שלכם נכללות תמיד כפי שהן, בנוסף לשתי כותרות במרחב השמות של ThunderPhone:

X-ThunderPhone-Signature — HMAC-SHA256 של הבתים המדויקים של גוף הבקשה, עם מפתח שהוא סוד ה-webhook של הארגון שלכם
X-ThunderPhone-Call-ID — מזהה השיחה הנוכחית

הערך Content-Type: application/json מוגדר אלא אם endpoint.headers שלכם דורסים אותו — Content-Type מותאם אישית גובר.

החתימה משתמשת בסוד ה-webhook ברמת הארגון מתוך GET /v1/webhook. אם הארגון שלכם מעולם לא הגדיר את ה-webhook הישן, אין סוד וקריאות לכלים כוללות רק את X-ThunderPhone-Call-ID — מטפל שנכשל באופן קשיח כאשר חסרה חתימה ידחה אותן. הגדירו את ה-webhook הישן כדי לקבל סוד, או הציבו סוד משותף משלכם ב-endpoint.headers.

גוף הבקשה

עבור POST / PUT / PATCH, הגוף מכיל רק את הארגומנטים של הכלי (ללא מעטפת), בסריאליזציה קנונית (מפתחות ממוינים, מפרידים קומפקטיים):

{"date":"2025-01-02","service":"consultation"}

עבור GET / DELETE, הארגומנטים נשלחים בתור פרמטרים של שאילתה והגוף ריק — החתימה מחושבת אז על מחרוזת בתים ריקה. ראו אימות חתימות webhook.

תגובה

החזירו תגובת JSON עם תוצאת הכלי:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

התגובה מעוצבת ומועברת ל-AI כדי להמשיך את השיחה. תגובות שאינן JSON נעטפות בתור {"data": "<text>"}; זמני קצובה וכשלי חיבור מדווחים ל-AI כשגיאות, כך שהסוכן יכול להתנצל ולהמשיך במקום להיתקע.

ניתוב במצב webhook

כלים ללא endpoint מנותבים לכתובת ה-webhook הישנה של הארגון שלכם כבקשת telephony.tool (שיחות טלפון) או web.tool (שיחות web) חתומה. בניגוד להתראות ביקורת שנשלחות לנקודות קצה של 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 — אותו חוזה תגובה כמו בקריאות ישירות לנקודות קצה. הבקשה חתומה עם סוד ה-webhook של הארגון על הגוף הגולמי, כמו כל webhook אחר.

נקודות קצה של webhook שנרשמו לקבלת התראות מקבלות בנוסף התראת telephony.tool / web.tool שאינה חוסמת לאחר שכל כלי מופעל (בכל נתיב שהפעיל אותו), כולל תגובת הכלי — שימושי עבור נתיבי ביקורת. ראו את קטלוג האירועים.

אימות חתימה

קריאות ישירות לכלים נחתמות באותו אופן כמו webhooks:

HMAC-SHA256 על בתים מדויקים של גוף הבקשה (ה-JSON הקנוני — מפתחות ממוינים, ללא רווחים נוספים)
עם המפתח של סוד ה-webhook של הארגון שלכם
כלים מסוג GET / DELETE חותמים על מחרוזת בתים ריקה

import hmac
import hashlib

def verify_tool_call(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    signature = request.headers.get("X-ThunderPhone-Signature", "")

    if not verify_tool_call(body, signature, WEBHOOK_SECRET):
        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}

app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-thunderphone-signature'] || '';
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!signature ||
      signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    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 });
});

המתכונים המלאים — כולל המקרה של גוף ריק וההסתייגות לגבי היעדר סוד — נמצאים ב-אימות חתימות webhook.

דוגמה: תהליך הזמנה מלא

הנה מערך כלים למערכת מלאה להזמנת פגישות:

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

שיטות מומלצות

כתבו תיאורים ברורים

השדה description עוזר לבינה המלאכותית להבין מתי להשתמש בכלי. פרטו במדויק מה הוא עושה ומתי מתאים להשתמש בו.

טפלו בשגיאות בצורה תקינה

החזירו הודעות שגיאה שהבינה המלאכותית יכולה להבין: {"error": "No slots available for that date"} במקום שגיאות 500 כלליות.

שמרו על תגובות תמציתיות

החזירו רק את מה שהבינה המלאכותית צריכה כדי להמשיך את השיחה. מטענים גדולים מאטים את זמני התגובה.

השתמשו בשדות חובה בתבונה

סמנו שדות כ-required רק כשזה באמת נחוץ. הבינה המלאכותית תבקש מהמשתמש את המידע הנדרש לפני הקריאה לכלי.

קשור

חיבורי אפליקציות

כלים המנוהלים על ידי הפלטפורמה עבור HubSpot, Salesforce, Slack, Google Calendar, Google Sheets ו-Cal.com — ללא צורך בנקודת קצה.

שרתי MCP

צרפו שרת MCP ואפשרו לסוכן לקרוא לכלים שלו.

חיבורי API

אינטגרציות REST לשימוש חוזר שתוכלו לצרף לסוכנים.

אמתו חתימות webhook

כלי עזר אחד לאימות עבור webhooks וקריאות לכלים.

Webhooks

Function Tools

כלי פונקציות

איך זה עובד

סכימת כלי

הגדרת פונקציה

תצורת Endpoint

שני נתיבי הפעלה

קריאות ישירות לנקודות קצה

כותרות בקשה

גוף הבקשה

תגובה

ניתוב במצב webhook

אימות חתימה

דוגמה: תהליך הזמנה מלא

שיטות מומלצות

קשור

חיבורי אפליקציות

שרתי MCP

חיבורי API

אמתו חתימות webhook

​איך זה עובד

​סכימת כלי

​הגדרת פונקציה

​תצורת Endpoint

​שני נתיבי הפעלה

​קריאות ישירות לנקודות קצה

​כותרות בקשה

​גוף הבקשה

​תגובה

​ניתוב במצב webhook

​אימות חתימה

​דוגמה: תהליך הזמנה מלא

​שיטות מומלצות

​קשור

חיבורי אפליקציות

שרתי MCP

חיבורי API

אמתו חתימות webhook

איך זה עובד

סכימת כלי

הגדרת פונקציה

תצורת Endpoint

שני נתיבי הפעלה

קריאות ישירות לנקודות קצה

כותרות בקשה

גוף הבקשה

תגובה

ניתוב במצב webhook

אימות חתימה

דוגמה: תהליך הזמנה מלא

שיטות מומלצות

קשור