> ## 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은
[레거시 웹훅 URL](/api-reference/organizations#legacy-single-url-webhook)로 **차단형**
`telephony.incoming` / `web.incoming` 요청을 보내고 구성 응답을 최대 **10초** 동안 기다립니다. 이
교환을 사용하여 통화별로 프롬프트, 음성, 도구를 동적으로 선택합니다.
전체 패턴은 [동적 통화 구성 가이드](/ko/guides/dynamic-call-config)를 참조합니다.
구독된 [웹훅 엔드포인트](/ko/webhooks/endpoints)도 에이전트 구성 여부와 관계없이
**모든** 수신 통화 및 웹 세션에 대해 `telephony.incoming` / `web.incoming`을
수신합니다. 하지만 이러한 전송은 `event_id`가 포함된, 차단하지 않는
실행 후 잊기 알림입니다.
이 페이지의 구성 교환은 레거시 단일 URL 웹훅에서만 전달됩니다. 엔드포인트 알림 형식은
[이벤트 카탈로그](/ko/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 | 통화 ID — 이 통화의 모든 이벤트에서 동일하게 유지됩니다 |
| `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 | 통화 ID |
| `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` | 문자열 | 예 | 에이전트를 구동하는 시스템 프롬프트 |
| `voice` | 문자열 | 예 | [`GET /v1/voices`](/api-reference/agents#voices)의 음성 ID(예: `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`입니다 |
| `storm_feedback_mode` | 문자열 | 아니요 | `none`, `acknowledgement`(기본값), 또는 `tick` |
| `language` | 문자열 | 아니요 | `primary_language`의 축약형 |
| `primary_language` | 문자열 | 아니요 | 언어 코드이며 정규화됩니다(기본값 `en`). 확인할 수 없는 코드는 통화를 거부합니다 |
| `has_additional_languages` | 불리언 | 아니요 | 기본값은 `false`입니다 |
| `additional_languages` | 문자열 배열 | 아니요 | 에이전트가 전환할 수 있는 추가 언어 |
| `background_track` | 문자열 \| null | 아니요 | 배경 오디오 ID 또는 `null` |
| `acknowledgement_prompt_mode` | 문자열 | 아니요 | `auto`(기본값) 또는 `manual`(Storm-with-ack 제품) |
| `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` | 배열 | 아니요 | 인라인 함수 도구 스키마([Function Tools](/ko/tools/overview) 참조) |
| `call_id` | 정수 | 아니요 | 요청의 통화 ID를 선택적으로 에코합니다. 무시됩니다 |
알 수 없는 최상위 키는 자동으로 **무시**됩니다. 즉, 필드 이름에 오타가 있어도
구성이 거부되지는 않지만 적용되지 않습니다. 여기서는 발화 순서와
`max_hold_seconds`를 사용할 수 없습니다. 이는 [Agent](/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({});
},
);
```
***
## 함수 도구를 포함한 응답
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
비밀 키**로 서명됩니다. 정확한 구조와 서명된 요청 형식은
[함수 도구](/ko/tools/overview)를 참조하세요.
***
## 제품 티어 요약
| 제품 | 지연 시간 | 추론 | 맞장구 |
| ---------------------- | ----- | --- | ------------- |
| `spark` | 최저 | 기본 | — |
| `bolt` | 낮음 | 향상됨 | — |
| `storm-base` | 중간 | 강력함 | — |
| `storm-base-with-ack` | 중간 | 강력함 | 생각하는 동안 자동 채움 |
| `storm-extra` | 높음 | 심층 | — |
| `storm-extra-with-ack` | 높음 | 심층 | 생각하는 동안 자동 채움 |
***
## 관련 문서
차단하지 않는 통화 종료 이벤트입니다.
`tools[]`의 전체 JSON 스키마와 서명된 엔드포인트 계약입니다.
여러 URL을 `telephony.incoming` / `web.incoming`에 구독합니다.
발신자별 프롬프트, 도구 및 A/B 테스트를 위한 패턴입니다.