mode="webhook"의 공개 키에서 시작되면 ThunderPhone은
레거시 웹훅 URL로 차단형
telephony.incoming / web.incoming 요청을 보내고 구성 응답을 최대 10초 동안 기다립니다. 이
교환을 사용하여 통화별로 프롬프트, 음성, 도구를 동적으로 선택합니다.
전체 패턴은 동적 통화 구성 가이드를 참조합니다.
차단형 교환에는 대체 동작이 없습니다. 핸들러가
2xx가 아닌 상태를 반환하거나, 시간 초과되거나, 검증에 실패하는 구성을 반환하면
통화가 거부됩니다(전화 연결은 되지 않으며, 위젯
세션 요청은
502/422로 실패합니다). 빠르게 응답해야 합니다. 결정하는 동안 발신자는 통화 연결음을 듣고 있습니다.
요청 페이로드
전화 통화의 경우(telephony.incoming):
웹 위젯 세션의 경우(
web.incoming) data는 전화번호 대신
위젯을 삽입한 페이지를 식별합니다.
웹훅 모드 위젯은 설정된 경우 공개 키 자체의
webhook_url로 이 요청을 전달하고, 그렇지 않으면 조직 수준
웹훅 URL을 사용합니다. 어느 경우든 조직 웹훅 secret으로 서명됩니다.응답 스키마
이 통화의 에이전트 구성을 설명하는 JSON 객체를 반환합니다.prompt와 voice는 필수이며, 나머지는 모두 선택 사항입니다.
알 수 없는 최상위 키는 자동으로 무시됩니다. 즉, 필드 이름에 오타가 있어도
구성이 거부되지는 않지만 적용되지 않습니다. 여기서는 발화 순서와
max_hold_seconds를 사용할 수 없습니다. 이는 Agent에서만
구성할 수 있습니다.prompt와 voice는 필수이므로, {} 또는 유효성 검사에 실패하는 응답을 반환하면
422와 함께 통화가 거부됩니다. 이 경로에서는 정적 에이전트 대체가 제공되지 않습니다
(웹훅 모드의 번호 또는 키에는 할당된 에이전트가 없습니다).
예시 핸들러
함수 도구를 포함한 응답
AI가 대화 중에 API를 호출할 수 있도록 도구를 연결합니다.제품 티어 요약
관련 문서
telephony.complete / web.complete
차단하지 않는 통화 종료 이벤트입니다.
함수 도구
tools[]의 전체 JSON 스키마와 서명된 엔드포인트 계약입니다.Webhook 엔드포인트
여러 URL을
telephony.incoming / web.incoming에 구독합니다.동적 통화 구성
발신자별 프롬프트, 도구 및 A/B 테스트를 위한 패턴입니다.