> ## 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 > Gelen bir aramanın yapılandırmasını gerçek zamanlı olarak şekillendiren engelleyici webhook. Bir gelen telefon çağrısı, **atanmış bir ajanı olmayan** bir numaraya ulaştığında veya bir web bileşeni oturumu `mode="webhook"` ayarındaki yayımlanabilir bir anahtarda başladığında ThunderPhone, [eski webhook URL'nize](/api-reference/organizations#legacy-single-url-webhook) **bloklayıcı** bir `telephony.incoming` / `web.incoming` isteği gönderir ve yapılandırma yanıtı için en fazla **10 saniye** bekler. Her çağrı için istemi, sesi ve araçları dinamik olarak seçmek üzere bu alışverişi kullanın — uçtan uca akış için [dinamik çağrı yapılandırma kılavuzuna](/tr/guides/dynamic-call-config) bakın. Abone olunan [webhook uç noktaları](/tr/webhooks/endpoints) da `telephony.incoming` / `web.incoming` alır — yapılandırılmış ajanı olsun ya da olmasın **her** gelen çağrı ve web oturumu için — ancak bu teslimatlar `event_id` içeren, yanıt beklemeden gönderilen bildirimlerdir; hiçbir zaman bloklayıcı değildir. Bu sayfadaki yapılandırma alışverişini yalnızca eski tek URL'li webhook taşır. Uç nokta bildirim biçimleri [olaylar kataloğunda](/tr/webhooks/events) yer alır. Bloklayıcı alışverişin geri dönüşü yoktur: işleyiciniz 2xx olmayan bir durum döndürürse, zaman aşımına uğrarsa veya doğrulamayı geçemeyen bir yapılandırma döndürürse çağrı reddedilir (telefon çağrısı bağlanmaz; bileşen oturumu isteği `502`/`422` ile başarısız olur). Hızlı yanıt verin — karar verirken arayan kişi çalma sesini duyar. ## İstek yükü Telefon çağrıları için (`telephony.incoming`): ```json theme={null} { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | Alan | Tür | Açıklama | | ------------- | ------- | ----------------------------------------------------- | | `call_id` | integer | Çağrı kimliği — bu çağrıya ait tüm olaylarda sabittir | | `from_number` | string | E.164 arayan numarası | | `to_number` | string | E.164 hedefi (ThunderPhone numaralarınızdan biri) | Web bileşeni oturumlarında (`web.incoming`) `data`, telefon numaraları yerine yerleştirme sayfasını tanımlar: ```json theme={null} { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | Alan | Tür | Açıklama | | ------------------------------ | ------- | ------------------------------------------------------------ | | `call_id` | integer | Çağrı kimliği | | `origin_domain` | string | Bileşeni barındıran sayfanın kaynağı | | `publishable_key_prefix` | string | Oturumu açan yayımlanabilir anahtarın ilk karakterleri | | `language`, `primary_language` | string | Bileşen oturumu bir dil geçersiz kılması istediğinde bulunur | | `voice` | string | Bileşen oturumu bir ses geçersiz kılması istediğinde bulunur | | `website_context` | string | Bileşen oturum başına sayfa bağlamı ilettiğinde bulunur | Webhook modundaki bileşenler, ayarlanmışsa bu isteği yayımlanabilir anahtarın kendi `webhook_url` değerine gönderir; aksi durumda kuruluş düzeyindeki webhook URL'sine geri döner. Her iki durumda da kuruluş webhook `secret` değeriyle imzalanır. *** ## Yanıt şeması Bu çağrı için ajan yapılandırmasını açıklayan bir JSON nesnesi döndürün. `prompt` ve `voice` zorunludur; diğer her şey isteğe bağlıdır. ```json theme={null} { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | Alan | Tür | Zorunlu | Açıklama | | ----------------------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `prompt` | string | evet | Ajanı yönlendiren sistem istemi | | `voice` | string | evet | [`GET /v1/voices`](/api-reference/agents#voices) yanıtındaki ses kimliği, ör. `john`. `voice_name` diğer ad olarak kabul edilir. Bilinmeyen sesler doğrulamayı geçemez ve çağrı reddedilir | | `product` | string | hayır | Varsayılan değer `spark`tır. İzin verilenler: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | hayır | `minimal`, `base` (varsayılan) veya `extra`. Storm ürünleri için geçersiz kılınır: `storm-extra*`, `extra` değerini zorlar; diğer `storm-*` ürünleri `base` değerini zorlar | | `audio_context_mode` | string | hayır | `full` (varsayılan) veya `reduced` | | `watchdog_enabled` | boolean | hayır | Bu çağrı için denetimi etkinleştirir. Varsayılan değer `false` | | `storm_feedback_mode` | string | hayır | `none`, `acknowledgement` (varsayılan) veya `tick` | | `language` | string | hayır | `primary_language` için kısa yol | | `primary_language` | string | hayır | Normalleştirilmiş dil kodu (varsayılan `en`). Çözümlenemeyen kodlar çağrıyı reddeder | | `has_additional_languages` | boolean | hayır | Varsayılan değer `false` | | `additional_languages` | string dizisi | hayır | Ajanın geçiş yapabileceği ek diller | | `background_track` | string \| null | hayır | Ortam sesi kimliği veya `null` | | `acknowledgement_prompt_mode` | string | hayır | `auto` (varsayılan) veya `manual` (Storm-with-ack ürünleri) | | `acknowledgement_prompt` | string | hayır | `acknowledgement_prompt_mode="manual"` olduğunda kullanılır | | `silence_interval_seconds` | integer \| null | hayır | 5–120. Kontrol yapılmadan önce arayanın sessiz kaldığı saniye sayısı | | `silence_max_checkins` | integer \| null | hayır | 1–10 | | `silence_checkins_enabled` | boolean | hayır | Varsayılan değer `true` | | `connect_tone_enabled` | boolean | hayır | Varsayılan değer `false` | | `voicemail_action` | string | hayır | `prompt` (varsayılan), `hangup` veya `message` | | `voicemail_message` | string | hayır | `voicemail_action="message"` olduğunda kullanılır | | `agent_name` | string | hayır | Kontrol panellerine ve widget'a bildirilen görünen ad | | `org_name` | string | hayır | Ajanın kişiliği için kuruluş görünen adı | | `tools` | array | hayır | Satır içi işlev aracı şemaları ([Function Tools](/tr/tools/overview) bölümüne bakın) | | `call_id` | integer | hayır | İsteğin çağrı kimliğinin isteğe bağlı yankısı; yoksayılır | Bilinmeyen üst düzey anahtarlar sessizce **yoksayılır** — yazım hatalı bir alan adı yapılandırmayı reddetmez, yalnızca uygulanmaz. Konuşma sırası ve `max_hold_seconds` burada kabul edilmez; yalnızca [Agent](/api-reference/agents) üzerinde yapılandırılabilir. `prompt` ve `voice` zorunlu olduğundan, `{}` veya doğrulamayı geçemeyen herhangi bir yanıt çağrıyı `422` ile reddeder — bu yolda statik ajan geri dönüşü yoktur (webhook modundaki bir numaraya veya anahtara atanmış bir ajan bulunmaz). *** ## Örnek işleyici ```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({}); }, ); ``` *** ## Fonksiyon araçlarıyla yanıt Yapay zekanın görüşme sırasında API'lerinizi çağırabilmesi için araçlar ekleyin: ```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" } } } ] } ``` Araç uç noktası istekleri, bu alışverişi imzalayan **aynı kuruluş webhook gizli anahtarı** ile imzalanır. Tam yapı ve imzalı istek biçimi için [Fonksiyon Araçları](/tr/tools/overview) sayfasına bakın. *** ## Ürün katmanı hızlı başvuru tablosu | Ürün | Gecikme | Muhakeme | Onay | | ---------------------- | ----------- | ------------- | ------------------------- | | `spark` | En düşük | Temel | — | | `bolt` | Düşük | Geliştirilmiş | — | | `storm-base` | Orta | Güçlü | — | | `storm-base-with-ack` | Orta | Güçlü | Düşünürken otomatik dolgu | | `storm-extra` | Daha yüksek | Derin | — | | `storm-extra-with-ack` | Daha yüksek | Derin | Düşünürken otomatik dolgu | *** ## İlgili Engellemeyen çağrı sonu olayı. `tools[]` için tam JSON şeması ve imzalı uç nokta sözleşmesi. Birden fazla URL'yi `telephony.incoming` / `web.incoming` için abone edin. Arayan bazlı istemler, araçlar ve A/B testleri için kalıplar.