> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # telephony.incoming / web.incoming > Webhook חוסם שמעצב את תצורת השיחה הנכנסת בזמן אמת. כאשר שיחת טלפון נכנסת מגיעה למספר **ללא סוכן מוקצה**, או שסשן של וידג'ט אינטרנט מתחיל במפתח publishable במצב `mode="webhook"`, ThunderPhone שולחת בקשת `telephony.incoming` / `web.incoming` **חוסמת** אל [כתובת ה-webhook הישנה שלכם](/api-reference/organizations#legacy-single-url-webhook) וממתינה עד **10 שניות** לתגובת תצורה. השתמשו בהחלפה זו כדי לבחור באופן דינמי הנחיה, קול וכלים לכל שיחה — עיינו ב[מדריך לתצורת שיחה דינמית](/he/guides/dynamic-call-config) לתבנית המלאה מקצה לקצה. [נקודות קצה של webhook](/he/webhooks/endpoints) שנרשמתם אליהן מקבלות גם `telephony.incoming` / `web.incoming` — עבור **כל** שיחה נכנסת וסשן אינטרנט, בין אם הוגדר להם סוכן ובין אם לא — אך מסירות אלה הן התראות שליחה-ושכחה עם `event_id`, ולעולם אינן חוסמות. רק ה-webhook הישן בעל כתובת ה-URL היחידה נושא את החלפת התצורה בדף זה. מבני התראות נקודות הקצה מופיעים ב [קטלוג האירועים](/he/webhooks/events). להחלפה החוסמת אין חלופה: אם המטפל שלכם מחזיר סטטוס שאינו 2xx, חורג מזמן ההמתנה או מחזיר תצורה שנכשלת באימות, השיחה נדחית (שיחת הטלפון אינה מתחברת; בקשת סשן הווידג'ט נכשלת עם `502`/`422`). השיבו במהירות — המתקשר שומע צליל חיוג בזמן שאתם מחליטים. ## מטען הבקשה עבור שיחות טלפון (`telephony.incoming`): ```json theme={null} { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | שדה | סוג | תיאור | | ------------- | -------- | ----------------------------------------------- | | `call_id` | מספר שלם | מזהה שיחה — יציב בכל האירועים עבור שיחה זו | | `from_number` | מחרוזת | מספר המתקשר בפורמט E.164 | | `to_number` | מחרוזת | יעד בפורמט E.164 (אחד ממספרי ThunderPhone שלכם) | עבור סשנים של וידג'ט אינטרנט (`web.incoming`), `data` מזהה את הדף המטמיע במקום מספרי טלפון: ```json theme={null} { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | שדה | סוג | תיאור | | ------------------------------ | -------- | --------------------------------------------------- | | `call_id` | מספר שלם | מזהה שיחה | | `origin_domain` | מחרוזת | מקור הדף שמארח את הווידג'ט | | `publishable_key_prefix` | מחרוזת | התווים הראשונים של המפתח ה-publishable שפתח את הסשן | | `language`, `primary_language` | מחרוזת | קיים כאשר סשן הווידג'ט ביקש דריסת שפה | | `voice` | מחרוזת | קיים כאשר סשן הווידג'ט ביקש דריסת קול | | `website_context` | מחרוזת | קיים כאשר הווידג'ט העביר הקשר דף לכל סשן | וידג'טים במצב webhook מוסרים בקשה זו אל `webhook_url` משלהם של המפתח ה-publishable כאשר הוא מוגדר, וחוזרים אל כתובת ה-webhook ברמת הארגון אם לא. בכל מקרה, היא נחתמת באמצעות `secret` של ה-webhook בארגון. *** ## סכמת תגובה החזירו אובייקט JSON המתאר את תצורת הסוכן עבור שיחה זו. `prompt` ו-`voice` הם שדות חובה; כל השאר אופציונליים. ```json theme={null} { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | שדה | סוג | חובה | תיאור | | ----------------------------- | --------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | string | כן | הנחיית המערכת שמפעילה את הסוכן | | `voice` | string | כן | מזהה קול מתוך [`GET /v1/voices`](/api-reference/agents#voices), לדוגמה `john`. ‏`voice_name` מתקבל ככינוי. קולות לא מוכרים נכשלים באימות ודוחים את השיחה | | `product` | string | לא | ברירת המחדל היא `spark`. ערכים מותרים: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | לא | `minimal`, ‏`base` (ברירת מחדל), או `extra`. עבור מוצרי Storm הערך נדרס: `storm-extra*` כופה `extra`, ומוצרי `storm-*` אחרים כופים `base` | | `audio_context_mode` | string | לא | `full` (ברירת מחדל) או `reduced` | | `watchdog_enabled` | boolean | לא | הפעילו פיקוח עבור שיחה זו. ברירת המחדל היא `false` | | `storm_feedback_mode` | string | לא | `none`, ‏`acknowledgement` (ברירת מחדל), או `tick` | | `language` | string | לא | קיצור עבור `primary_language` | | `primary_language` | string | לא | קוד שפה, מנורמל (ברירת המחדל היא `en`). קודים שלא ניתן לפענח דוחים את השיחה | | `has_additional_languages` | boolean | לא | ברירת המחדל היא `false` | | `additional_languages` | array of string | לא | שפות נוספות שהסוכן יכול לעבור אליהן | | `background_track` | string \| null | לא | מזהה שמע סביבתי או `null` | | `acknowledgement_prompt_mode` | string | לא | `auto` (ברירת מחדל) או `manual` (מוצרי Storm-with-ack) | | `acknowledgement_prompt` | string | לא | בשימוש כאשר `acknowledgement_prompt_mode="manual"` | | `silence_interval_seconds` | integer \| null | לא | 5–120. שניות של שקט מצד המתקשר לפני בדיקה | | `silence_max_checkins` | integer \| null | לא | 1–10 | | `silence_checkins_enabled` | boolean | לא | ברירת המחדל היא `true` | | `connect_tone_enabled` | boolean | לא | ברירת המחדל היא `false` | | `voicemail_action` | string | לא | `prompt` (ברירת מחדל), `hangup`, או `message` | | `voicemail_message` | string | לא | בשימוש כאשר `voicemail_action="message"` | | `agent_name` | string | לא | שם תצוגה המדווח ללוחות הבקרה ולווידג'ט | | `org_name` | string | לא | שם התצוגה של הארגון עבור דמות הסוכן | | `tools` | array | לא | סכמות מוטמעות של כלי פונקציה (ראו [כלי פונקציה](/he/tools/overview)) | | `call_id` | integer | לא | הד אופציונלי של מזהה השיחה בבקשה; המערכת מתעלמת ממנו | מפתחות עליונים לא מוכרים **מתעלמים** מהם בשקט — שם שדה עם שגיאת הקלדה לא דוחה את התצורה, הוא פשוט לא מוחל. סדר הדיבור ו-`max_hold_seconds` אינם מתקבלים כאן; ניתן להגדיר אותם רק ב-[סוכן](/api-reference/agents) עצמו. מכיוון ש-`prompt` ו-`voice` הם שדות חובה, החזרת `{}` או כל תגובה שנכשלת באימות דוחה את השיחה עם `422` — אין נתיב חלופי של סוכן סטטי במסלול זה (למספר או למפתח במצב webhook אין סוכן מוקצה). ## מטפל לדוגמה ```python Python (FastAPI) theme={null} import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, signature: str) -> bool: expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature or "") @app.post("/thunderphone-webhook") async def webhook(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(status_code=401) event = json.loads(body) if event["type"] == "telephony.incoming": caller = event["data"]["from_number"] prompt = ( "Greet the caller as a San Francisco local…" if caller.startswith("+1415") else "You are a friendly customer support agent…" ) return { "prompt": prompt, "voice": "john", "product": "spark", } if event["type"] == "web.incoming": return { "prompt": "You are the website's helpful voice assistant…", "voice": "john", "product": "spark", } return {} ``` ```javascript Node.js (Express) theme={null} import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, signature) { const expected = crypto .createHmac("sha256", SECRET) .update(body) .digest("hex"); return signature && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } app.post( "/thunderphone-webhook", express.raw({ type: "application/json" }), (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); if (event.type === "telephony.incoming" || event.type === "web.incoming") { const caller = event.data.from_number || "web"; const prompt = caller.startsWith("+1415") ? "Greet the caller as a San Francisco local…" : "You are a friendly customer support agent…"; return res.json({ prompt, voice: "john", product: "spark", }); } res.json({}); }, ); ``` *** ## תגובה עם כלי פונקציות צרפו כלים כדי שה-AI יוכל לקרוא לממשקי ה-API שלכם במהלך השיחה: ```json theme={null} { "prompt": "You are a booking assistant. Use the available tools to help customers schedule appointments.", "voice": "john", "product": "spark", "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": "your-key" } } } ] } ``` בקשות לנקודות קצה של כלים נחתמות באמצעות **אותו סוד webhook של הארגון** שחתם על חילוף זה. עיינו ב-[כלי פונקציות](/he/tools/overview) למבנה המדויק ולפורמט הבקשה החתומה. *** ## דף עזר לרמות מוצר | מוצר | זמן השהיה | יכולות הסקה | אישור | | ---------------------- | ----------- | ----------- | ----------------------------- | | `spark` | הנמוך ביותר | בסיסי | — | | `bolt` | נמוך | משופר | — | | `storm-base` | בינוני | חזק | — | | `storm-base-with-ack` | בינוני | חזק | תוכן מילוי אוטומטי בזמן חשיבה | | `storm-extra` | גבוה יותר | מעמיק | — | | `storm-extra-with-ack` | גבוה יותר | מעמיק | תוכן מילוי אוטומטי בזמן חשיבה | *** ## קשור אירוע סיום השיחה שאינו חוסם. סכמת JSON מלאה עבור `tools[]` וחוזה נקודת הקצה החתום. הירשמו מספר כתובות URL ל-`telephony.incoming` / `web.incoming`. תבניות להנחיות, כלים ובדיקות A/B לכל מתקשר.