--- title: "telephony.incoming / web.incoming" description: "Блокирајући вебхук који у реалном времену одређује конфигурацију долазног позива." --- Када долазни телефонски позив стигне на број **без додељеног агента**, или када сесија веб виџета започне на објављивом кључу у `mode="webhook"`, ThunderPhone шаље **блокирајући** захтев `telephony.incoming` / `web.incoming` на Ваш [застарели URL веб-хука](/api-reference/organizations#legacy-single-url-webhook) и чека до **10 секунди** на одговор са конфигурацијом. Користите ову размену да динамички изаберете упит, глас и алате за сваки позив — погледајте [водич за динамичку конфигурацију позива](/sr/guides/dynamic-call-config) за образац од почетка до краја. Претплаћене [крајње тачке веб-хука](/sr/webhooks/endpoints) такође примају `telephony.incoming` / `web.incoming` — за **сваки** долазни позив и веб сесију, без обзира на то да ли је агент конфигурисан — али су те испоруке обавештења типа „пошаљи и заборави“ са `event_id`, никада блокирајуће. Само застарели веб-хук са једним URL-ом преноси размену конфигурације на овој страници. Облици обавештења крајњих тачака налазе се у [каталогу догађаја](/sr/webhooks/events). Блокирајућа размена нема резервну опцију: ако Ваш обрађивач врати статус који није 2xx, истекне време или врати конфигурацију која не прође валидацију, позив се одбија (телефонски позив се не повезује; захтев за сесију виџета не успева са `502`/`422`). Одговорите брзо — позивалац чује тон позива док Ви одлучујете. **Позиви конфигурисани путем веб-хука не садрже ThunderPhone обавештење о пристанку.** Позиви конфигурисани кроз ову размену заобилазе обавештење на нивоу агента при почетку позива и изричито су искључени из ThunderPhone оквира за обавештење о пристанку (Услови коришћења, одељак „Снимање и пристанак“). Ваша организација је искључиво одговорна за свако обавештење и пристанак у вези са снимањем, надзором, учешћем AI и идентификацијом позиваоца који су потребни за ове позиве — позиви и даље могу бити снимани, транскрибовани, анализирани и обрађивани помоћу AI. Укључите потребна обавештења у сопствени ток позива пре омогућавања ове путање. ## Тело захтева За телефонске позиве (`telephony.incoming`): ```json { "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 { "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 { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | Поље | Тип | Обавезно | Опис | |-------|------|----------|-------------| | `prompt` | стринг | да | Системски упит који управља агентом | | `voice` | стринг | да | ИД гласа из [`GET /v1/voices`](/api-reference/agents#voices), нпр. `john`. `voice_name` је прихваћен као алијас. Непознати гласови не пролазе валидацију и одбијају позив | | `product` | стринг | не | Подразумевано је `spark`. Дозвољено: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | стринг | не | `minimal`, `base` (подразумевано) или `extra`. Надјачава се за Storm производе: `storm-extra*` приморава `extra`, остали `storm-*` приморавају `base` | | `audio_context_mode` | стринг | не | `full` (подразумевано) или `reduced` | | `watchdog_enabled` | логичка вредност | не | Омогућите надзор за овај позив. Подразумевано је `false` | | `additional_audio_context` | логичка вредност \| null | не | Укључите последњих неколико размена аудио-записа позиваоца уместо само најскорије размене, чиме се побољшавају исправке и прикупљање података са много слова/бројева уз мали додатни трошак кашњења/цене. Подразумевано је укључено за долазне сесије, а искључено за одлазне телефонске позиве; `null` задржава подразумевану вредност | | `storm_feedback_mode` | стринг | не | `none`, `acknowledgement` (подразумевано) или `tick` | | `language` | стринг | не | Скраћеница за `primary_language` | | `primary_language` | стринг | не | Кôд језика, нормализован (подразумевано `en`). Кодови који се не могу разрешити одбијају позив | | `has_additional_languages` | логичка вредност | не | Подразумевано је `false` | | `additional_languages` | низ стрингова | не | Додатни језици на које агент може да се пребаци | | `native_voice_switching` | логичка вредност | не | Подразумевано је `false`. Када се позив пребаци на други језик, замените конфигурисани глас гласом изворног говорника тог језика (усклађеним по полу) | | `background_track` | стринг \| null | не | ИД амбијенталног звука или `null` | | `acknowledgement_prompt_mode` | стринг | не | `auto` (подразумевано) или `manual` (за Storm производе са потврдом) | | `acknowledgement_prompt` | стринг | не | Користи се када је `acknowledgement_prompt_mode="manual"` | | `silence_interval_seconds` | цео број \| null | не | 5–120. Секунде тишине позиваоца пре провере | | `silence_max_checkins` | цео број \| null | не | 1–10 | | `silence_checkins_enabled` | логичка вредност | не | Подразумевано је `true` | | `connect_tone_enabled` | логичка вредност | не | Подразумевано је `false` | | `voicemail_action` | стринг | не | `prompt` (подразумевано), `hangup` или `message` | | `voicemail_message` | стринг | не | Користи се када је `voicemail_action="message"` | | `agent_name` | стринг | не | Приказано име за контролне табле и виџет | | `org_name` | стринг | не | Приказано име организације за персону агента | | `tools` | низ | не | Уграђене шеме алатки функција (погледајте [Алатке функција](/sr/tools/overview)) | | `call_id` | цео број | не | Опциони ехо идентификатора позива из захтева; игнорише се | Непознати кључеви највишег нивоа се тихо **игноришу** — поље са грешком у писању не одбија конфигурацију, већ се једноставно не примењује. Редослед изговарања и `max_hold_seconds` овде нису прихваћени; могу се конфигурисати само на самом [Агенту](/api-reference/agents). Пошто су `prompt` и `voice` обавезни, враћање `{}` или било ког одговора који не прође валидацију одбија позив са `422` — не постоји резервно коришћење статичког агента на овој путањи (број или кључ у вебхук режиму нема додељеног агента). --- ## Ограничење величине одговора Одговори конфигурације ограничени су на **5 MiB**. Ако обрађивач врати већи одговор, укључујући и онај са статусом `2xx`, ThunderPhone пријављује да је одговор премашио ограничење и одбија позив или сесију виџета. У одговору задржите поља потребна за подешавање позива; велике податке хостујте иза функционалних алатки или друге услуге уместо да их уграђујете у конфигурацију. --- ## Пример обрађивача ```python Python (FastAPI) 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) 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 { "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" } } } ] } ``` Захтеви ка крајњој тачки алатке потписују се истом **тајном вредношћу веб-куке организације** којом је потписана ова размена. Погледајте [Функционалне алатке](/sr/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 тестове по позиваоцу.