> ## 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 > Блокувальний вебхук, що формує конфігурацію вхідного дзвінка в реальному часі. Коли вхідний телефонний виклик надходить на номер **без призначеного агента**, або сеанс вебвіджета запускається на публічному ключі в `mode="webhook"`, ThunderPhone надсилає **блокувальний** запит `telephony.incoming` / `web.incoming` на вашу [застарілу URL-адресу вебхука](/api-reference/organizations#legacy-single-url-webhook) і очікує до **10 секунд** на відповідь із конфігурацією. Використовуйте цей обмін, щоб динамічно вибирати промпт, голос і інструменти для кожного виклику — повний шаблон дивіться в [посібнику з динамічної конфігурації викликів](/uk/guides/dynamic-call-config). Підписані [кінцеві точки вебхуків](/uk/webhooks/endpoints) також отримують `telephony.incoming` / `web.incoming` — для **кожного** вхідного виклику та вебсеансу, незалежно від того, чи налаштовано агента, — але ці доставки є неблокувальними сповіщеннями типу fire-and-forget з `event_id`. Лише застарілий вебхук з однією URL-адресою передає обмін конфігурацією, описаний на цій сторінці. Структури сповіщень кінцевих точок наведено в [каталозі подій](/uk/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` | integer | Ідентифікатор виклику — незмінний у всіх подіях цього виклику | | `from_number` | string | Номер абонента, що телефонує, у форматі E.164 | | `to_number` | string | Цільовий номер 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` | integer | Ідентифікатор виклику | | `origin_domain` | string | Джерело сторінки, на якій розміщено віджет | | `publishable_key_prefix` | string | Перші символи публічного ключа, що відкрив сеанс | | `language`, `primary_language` | string | Наявні, коли сеанс віджета запитав перевизначення мови | | `voice` | string | Наявний, коли сеанс віджета запитав перевизначення голосу | | `website_context` | string | Наявний, коли віджет передав контекст сторінки для сеансу | Віджети в режимі вебхука надсилають цей запит на власний `webhook_url` публічного ключа, якщо його налаштовано, інакше використовують URL-адресу вебхука рівня організації. В обох випадках запит підписується `secret` вебхука організації. *** ## Схема відповіді Поверніть об’єкт 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 | ні | Вбудовані схеми інструментів функцій (див. [Інструменти функцій](/uk/tools/overview)) | | `call_id` | integer | ні | Необов’язкове віддзеркалення ідентифікатора виклику із запиту; ігнорується | Невідомі ключі верхнього рівня тихо **ігноруються** — поле з помилкою в назві не відхиляє конфігурацію, але просто не застосовується. Порядок реплік і `max_hold_seconds` тут не приймаються; їх можна налаштувати лише для самого [агента](/api-reference/agents). Оскільки `prompt` і `voice` обов’язкові, повернення `{}` або будь-якої відповіді, що не проходить перевірку, відхиляє виклик із кодом `422` — для цього шляху немає резервного статичного агента (номер або ключ у режимі вебхука не має призначеного агента). *** ## Приклад обробника ```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({}); }, ); ``` *** ## Відповідь із функціональними інструментами Додайте інструменти, щоб ШІ міг викликати ваші 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" } } } ] } ``` Запити до кінцевих точок інструментів підписуються тим самим **секретом вебхука організації**, яким підписано цей обмін. Точну структуру та формат підписаного запиту дивіться в розділі [Функціональні інструменти](/uk/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-тестів для кожного абонента.