Open in
telephony.incoming / web.incoming
Блокиращ webhook, който конфигурира входящо обаждане в реално време.
Когато входящо телефонно обаждане достигне номер без назначен
агент (вижте Обратни обаждания за обаждащи се, които връщат
вашите изходящи обаждания), или сесия на уеб уиджет започне с публикуем ключ в
mode="webhook", ThunderPhone изпраща блокираща
заявка telephony.incoming / web.incoming към вашия
стар webhook URL
и изчаква отговор с конфигурация: до 13 секунди за
телефонно обаждане, включително един повторен опит, и до 10 секунди за сесия
на уиджет (вижте Време за изчакване и повторни опити). Използвайте този
обмен, за да избирате динамично подкана, глас и инструменти за всяко обаждане —
вижте ръководството за динамична конфигурация на обаждания
за цялостния модел.
Номер с назначен агент отговаря с този агент. Когато агентът има собствен уебхук за настройка на обаждане, същият блокиращ обмен се изпълнява първо на URL адреса на агента, за да попълни променливите на агента и контекста на обаждането.
Време на изчакване и повторни опити
Отговорете бързо: обаждащият се чака на линията, докато решавате.
За телефонно обаждане (telephony.incoming):
- Първият опит може да отнеме до 10 секунди.
- Ако изтече времето му, не може да се осъществи връзка или получи отговор
5xx,408или429, ThunderPhone опитва още веднъж. Повторният опит получава оставащата част от 13-секундния бюджет за целия обмен: около 3 секунди след първи опит, при който е изтекло времето, и почти всичките 13 след бърз неуспех. Няма повторен опит, когато биха останали по-малко от 2 секунди. - Всеки друг отговор
4xx, отговор над ограничението за размер или2xx, чието тяло не е валидна конфигурация, е окончателен и не се повтаря. - И двата опита изпращат едно и също тяло, един и същ хедър
X-ThunderPhone-Signatureи един и същ хедърX-ThunderPhone-Idempotency-Key(telephony-incoming-<call_id>), така че обработчик със странични ефекти може да разпознае повторния опит.
Ако не бъде получена използваема конфигурация, обаждането се прекратява веднага,
вместо обаждащият се да остава на тиха линия. То се показва в
историята на обажданията като неуспешно, нетаксувано обаждане с end_reason
inbound_config_webhook_failed, като се изпраща и обичайното
събитие telephony.complete. Страницата на обаждането
в таблото и config_webhook_failure в
GET /v1/calls/{call_id} посочват какво е направил вашият уебхук:
{kind, attempts, http_status, host, source}, където kind е http_error,
timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json или
invalid_config, host е името на хоста на вашия уебхук, а source е
number (този уебхук) или agent_setup (уебхук за настройка на обаждане на агент).
При invalid_config reason посочва защо отговорът не може да бъде използван, а
fields посочва полетата, за които се отнася: no_agent (няма нито agent_id, нито
prompt; fields изброява ключовете, които са били игнорирани, например грешно изписан
agentId), agent_not_found, agent_id_not_integer, unexpected_fields
(ключове, различни от variables, context, timezone и language до
agent_id), invalid_variables, invalid_context, invalid_language,
unsupported_language, invalid_config_fields или agent_settings_invalid.
В противен случай reason е null, а fields е празно. Единственото
изключение е обаждащ се, който връща едно от вашите изходящи обаждания, когато
самият обмен е неуспешен: вижте Обратни обаждания.
Сесия на джаджа (web.incoming) получава един опит с продължителност до 10
секунди. Ако той е неуспешен, заявката за сесията е неуспешна с 502 или 422.
Полезен товар на заявката
За телефонни обаждания (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Поле | Тип | Описание |
|---|---|---|
call_id | цяло число | Идентификатор на обаждането — непроменлив във всички събития за това обаждане |
from_number | низ | Номер на обаждащия се във формат E.164 |
to_number | низ | Целеви номер във формат E.164 (един от вашите номера на ThunderPhone) |
returning_call | обект | Налице е само когато този номер е позвънил на обаждащия се през последните 30 дни. Вижте Обратни обаждания |
sip_headers | обект | Налице е само когато обаждането е постъпило чрез ръчна SIP връзка със SIP заглавки X-* или User-to-User: име на заглавката с малки букви → стойност. Вижте SIP заглавки |
За сесии на уеб уиджет (web.incoming) data идентифицира
страницата, в която е вграден уиджетът, вместо телефонни номера:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Поле | Тип | Описание |
|---|---|---|
call_id | цяло число | Идентификатор на обаждането |
origin_domain | низ | Произходът на страницата, хостваща уиджета, както е изпратен от браузъра. Клиент извън браузър може да изпрати произволна стойност, затова не го приемайте като доказателство откъде е дошла заявката |
publishable_key_prefix | низ | Първите знаци от публикуемия ключ, който е отворил сесията |
language, primary_language | низ | Налице, когато сесията на уиджета е заявила замяна на езика |
voice | низ | Налице, когато сесията на уиджета е заявила замяна на гласа |
website_context | низ | Налице, когато уиджетът е предал контекст на страница за конкретната сесия |
Полетата за замяна (language, voice, website_context и всички
браузърни variables) пристигат само когато публикуемият ключ ги позволява в
своите замени от браузъра. Заявка за
сесия, съдържаща такава, която ключът не позволява, се отхвърля, преди да бъде извикан
този webhook.
Схема на отговора
Върнете JSON обект, описващ конфигурацията на агента за това обаждане.
prompt и voice са задължителни; всичко останало не е задължително.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Поле | Тип | Задължително | Описание |
|---|---|---|---|
prompt | низ | да | Системна подкана, която управлява агента |
voice | низ | да | Идентификатор на глас от GET /v1/voices, например john. voice_name се приема като псевдоним. Непознатите гласове не преминават проверката и заявката за обаждане се отхвърля |
product | низ | не | Изпратете bolt. По подразбиране е spark — по-стара стойност, която все още се приема заедно с 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: какво чува обаждащият се, докато се подготвя по-бавен отговор, когато audio_tier е plus или max |
language | низ | не | Съкратен запис за primary_language. Допуска се и редом с agent_id, където това е езикът, на който започва обаждането и който се говори с гласа на агента за този език; вижте Задаване на езика за всяко обаждане |
primary_language | низ | не | Нормализиран езиков код (по подразбиране en). Неразпознаваемите кодове отхвърлят обаждането |
has_additional_languages | булева стойност | не | По подразбиране е false |
additional_languages | масив от низове | не | Допълнителни езици, към които агентът може да превключи |
native_voice_switching | булева стойност | не | По подразбиране е false. Когато обаждането превключи към друг език, сменя гласа с глас, който е роден за този език (със същия пол), вместо да запази конфигурирания глас |
language_switching | низ | null | не | ask_first (по подразбиране) или follow_caller; null е същото като ask_first. Определя как многоезичният агент обработва случая, когато другият човек говори на друг негов език. ask_first превключва веднага, когато човекът поиска езика или каже цяло изречение на него, и пита дали да продължи на този език след нещо кратко, като „sí“. follow_caller превключва към всеки конфигуриран език, на който човекът говори, дори само с една дума. Прилага се само когато е зададено additional_languages |
audio_tier | низ | null | не | Само за product: "bolt". Слушане: колко внимателно агентът чува обаждащия се. standard (по подразбиране; "" и null означават едно и също) е подходящ за повечето обаждания (обажданията, които обработват PHI, използват само доставчици, покрити от BAA). lite е най-евтиният и чува грешно по-често. plus слуша по-внимателно при трудни ходове, които отнемат с около 1–2 секунди повече. max е за най-трудното аудио и редки езици; всеки отговор отнема 3–4 секунди и обаждането използва интелигентност pro (intelligence се игнорира). max не е общодостъпен: за организация, за която не е активиран, обаждането използва plus и посочената от вас intelligence (изходяща заявка за обаждане с него се отказва с 400). По-старите стойности lean (Lite), hearing (Plus) и deep_hearing (Max) все още се приемат. Другите продукти го игнорират |
endpointing | низ | null | не | faster (200 ms), fast (300 ms), normal (500 ms, по подразбиране) или patient (800 ms); null е същото като normal. Колко дълго агент Bolt v2 изчаква, след като обаждащият се спре да говори, преди да поиска отговор от модела. По-краткото изчакване може да отговори по-рано, но изпраща повече заявки, които следващите думи на обаждащия се правят неактуални, което увеличава разхода за модела. Другите продукти го игнорират |
eagerness | низ | null | не | Отпадащо: името на endpointing до 19 октомври 2026 г., все още се чете. Игнорира се, когато е зададено endpointing |
intelligence | низ | null | не | core или pro (по подразбиране); null е същото като pro. Колко надеждно агент bolt в конвейера Bolt v2 следва инструкциите си. core е ~700 ms до първата дума, най-евтин е и е малко по-малко надежден (при обаждания, обработвани като PHI — ~900 ms и по-малко надежден); pro е ~900 ms; отговорите на Core, които биха извикали само инструмент, се предават на Pro. По-старите стойности lite (Core) и standard (Pro) все още се приемат, а оттеглените plus и max работят с pro. Игнорира се, когато audio_tier е max. Другите продукти го игнорират |
faster_replies | булева стойност | null | не | Ускоряване. По подразбиране е true. При агент bolt в конвейера Bolt v2 отговорите започват малко по-рано срещу малко по-висока цена. false го изключва. Другите продукти го игнорират |
background_track | низ | null | не | Идентификатор на фоново аудио или null |
acknowledgement_prompt_mode | низ | не | auto (по подразбиране) или manual (по-стари стойности на продукта -with-ack) |
acknowledgement_prompt | низ | не | Използва се, когато acknowledgement_prompt_mode="manual" |
silence_interval_seconds | цяло число | null | не | 5–120. Секунди мълчание на обаждащия се преди проверка |
silence_max_checkins | цяло число | null | не | 1–10 |
silence_checkins_enabled | булева стойност | не | По подразбиране е true |
silence_final_action | низ | не | След последната проверка: hang_up (по подразбиране) или transfer към silence_transfer_destination |
silence_transfer_destination | низ | не | Име на запис в transfer_destinations на тази конфигурация; задължително при transfer. Без transfer_destinations прехвърлянето не може да се извърши и агентът прекратява разговора |
silence_final_message | низ | не | ≤ 300 знака, прочита се както е написано; "" (по подразбиране) използва реда по подразбиране |
connect_tone_enabled | булева стойност | не | По подразбиране е false |
pronunciation_dicts | булева стойност | null | не | По подразбиране е false; null е същото като false. Когато е true, синтезираната реч на Cartesia за обаждането използва речника за произношение на ThunderPhone за езика на обаждането, когато такъв съществува. Работи за телефонни обаждания и обаждания чрез уиджета. Прилага се само за собствените гласове на Cartesia на ThunderPhone, а не за гласове чрез ваш собствен API ключ за Cartesia. Не се използва с agent_id, където се прилагат настройките на запазения агент |
words | масив | null | не | Как агентът произнася конкретни думи — същите записи като words на агент, без support. Запис без language приема езика на тази конфигурация. null и [] означават, че няма такива. Не се използва с agent_id, където се прилагат думите на запазения агент |
voicemail_action | низ | не | prompt (по подразбиране), hangup или message |
voicemail_message | низ | не | Използва се, когато voicemail_action="message" |
agent_name | низ | не | Показвано име, отчитано в таблата за управление и уиджета |
org_name | низ | не | Показвано име на организацията за персоната на агента |
tools | масив | не | Вградени схеми за функционални инструменти (вижте Функционални инструменти) |
transfer_destinations | масив от обекти | null | не | До 50 записа {name, number}, към които това обаждане може да се прехвърли, валидирани като номера за прехвърляне на агент. Агентът прехвърля по име и само към тях; [] означава без прехвърляния. Пропуснете го или изпратете null, за да позволите на агента да прехвърли към номер по свой избор |
timezone | низ | не | Часова зона IANA за това обаждане, например America/Chicago. Агентът съобщава датата и часа в нея с приоритет пред собствената часова зона на агента. Допуска се и редом с agent_id. Стойности, които не са зони IANA, се игнорират. Вижте Задаване на часовата зона за всяко обаждане |
context | низ | null | не | Текст в свободен формат за това обаждане, например бележки, събрани от вашата система, до 20 000 знака. Добавя се след подканата в ограничен блок и не се визуализира като шаблон. Допуска се и редом с agent_id. Стойност, която не е низ или е по-дълга, отхвърля обаждането. Вижте променливи и контекст на обаждането |
call_id | цяло число | не | Незадължително повторение на идентификатора на обаждането от заявката; игнорира се |
Тъй като prompt и voice са задължителни, връщането на {} или на отговор, който не премине валидацията, отхвърля обаждането: телефонното обаждане се прекратява, както е описано в Прекъсвания и повторни опити, а заявката за сесия на уиджета завършва с 422. Това важи и за връщащи се обаждащи се: всеки JSON обект, който вашият уебхук върне, е неговият отговор, а {} е начинът да откажете обаждане.
Уебхук за настройка на обаждането на агент
Агентът може да има собствен уебхук за настройка на обаждането: полето Уебхук за настройка на обаждането
в неговите настройки или call_setup_webhook_url
в API. Присвоете агента на номер и преди всяко входящо обаждане
на този номер, на което агентът отговаря, ThunderPhone заявява от уебхука променливите и контекста
за това обаждане. Номерът запазва своя агент, така че страницата с телефонните
номера и страницата на агента показват кой агент отговаря на него.
Това е настройка като останалите на агента: подготвя се като чернова, публикува се при
внедряване и се съхранява в хронологията на версиите. Номер,
фиксиран към по-стара версия,
заявява URL адреса на тази версия. Заявките се подписват със собствения
call_setup_webhook_signing_secret на агента (не със секрета за уебхука
на организацията), със същия хедър X-ThunderPhone-Signature, таймаути,
повторни опити и ключ за идемпотентност като по-горе. Секретът е
само за запис: задайте такъв, който крайната ви точка проверява (в настройките на агента или чрез
PATCH /v1/agents/{id}); никое извличане не го връща, а
call_setup_webhook_signing_secret_set показва дали е зададен.
Заявката е payload-ът telephony.incoming по-горе плюс агента, който
попълва:
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567",
"variables": null,
"agent": {
"id": 12,
"name": "Front desk",
"version": 7,
"version_pinned": false
}
}
}| Поле | Тип | Описание |
|---|---|---|
agent.id | цяло число | Агентът, присвоен на номера |
agent.name | низ | Неговото име |
agent.version | цяло число | null | Номерът на версията, която ще отговори: фиксираната версия на номера или последната публикувана версия на агента (null, ако няма такава) |
agent.version_pinned | булева стойност | Дали номерът е фиксиран към тази версия |
Отговорете с необходимото за обаждането. Всеки от тези варианти попълва присвоения агент с версията на номера:
{"variables": {...}},{"context": "..."}или и двете- същото, като
"agent_id"е зададен на идентификатора на присвоения агент {}: агентът отговаря, без да е попълнено нищо
timezone и language също са позволени, както до
agent_id. Променливите попълват
{{placeholders}} на агента; контекстът се добавя след подканата.
Или решете за обаждането сами. agent_id на друг агент или пълна
конфигурация с prompt се използва за това конкретно обаждане вместо присвоения
агент (и неговата фиксирана версия). Подробностите за обаждането обозначават всеки случай в
call_setup_webhook: assigned_agent,
other_agent или inline_config. Отговор, който не може да бъде използван (непознат
agent_id, други ключове наред с variables, конфигурация, която
не преминава валидацията), прекратява обаждането, както при уебхука на номер.
Кога уебхукът трябва да отговори. Агентът се нуждае от своя уебхук, когато в
настройките му се използва {{variable}} без стойност по подразбиране: в неговата подкана или повторно
използваеми инструкции, инструкции или редове за стъпка, подкана за потвърждение,
съобщение за гласова поща, съобщение за съгласие или номер за прехвърляне
{{variable}}. call_setup_webhook_variables на агента ги изброява.
- Нуждае се от уебхука: когато уебхукът изтече по таймаут, не може да бъде
достигнат или отговори с грешка или тяло, което не е JSON обект,
обаждането не започва, дори когато то вече съдържа стойност за
една от тези променливи. То се прекратява и записва точно както е описано
в Таймаути и повторни опити (
end_reasoninbound_config_webhook_failed, не се таксува). - Не се нуждае от нищо (няма променливи или всяка има стойност по подразбиране, например
{{first_name|there}}): уебхукът все пак се изпълнява, но когато неуспее, агентът отговаря без него, а подробностите за обаждането показватwebhook_failedс причината за неуспеха.
Контекстът на разговора сам по себе си никога не прави уебхука задължителен: нищо в настройките на агента не указва, че той се нуждае от контекст. Използвайте променлива без стойност по подразбиране, ако разговорът не трябва да започва без отговора на вашия уебхук.
Присвояване и разгръщане. Агент, който се нуждае от своя уебхук, не може да бъде
присвоен на номер без такъв: присвояването се отказва със съобщение, което посочва
променливите. Същата проверка се извършва, когато версията на номер се промени,
включително когато закрепен номер се върне към Най-нова. Докато отговаря на номер със
своите публикувани настройки, разгръщане, което добавя такава променлива без уебхук
(или премахва уебхука), се отказва по същия начин. Записването на черновата винаги е
разрешено, а warnings на агента съдържа
call_setup_webhook_needed, докато проблемът не бъде отстранен.
Уебхукът на агента се изпълнява само за входящи телефонни разговори към номера, към които е присвоен. Изходящите разговори, сесиите на уеб уиджета, SIP адресите, симулациите и тестовите разговори в таблото не го извикват; те получават своите променливи от заявката както преди.
Тестване със запазени примери. За да тествате какво прави вашият агент с даден отговор (повтарящ се обаждащ се, не е намерен запис, испаноговорящ), запазете този отговор в агента като пример: неговите variables, context и по желание language, въведени или копирани от предишно обаждане. Изберете го, когато стартирате тестов разговор в таблото, тестово обаждане към вашия телефон или симулация с агента, и обаждането се изпълнява, сякаш вашият уебкук е отговорил с него. Примерите се споделят от всички версии на агента. Редактирането на пример запазва предишните му версии: когато промяна в агента изисква променлива, която примерът не задава, добавете я към примера, а по-старите версии на агента продължават да използват примера в предишния му вид. Симулациите, които набират телефонен номер, вместо това изпълняват вашия действителен уебкук.
Номерата без присвоен агент продължават да използват уебхука на номера или на организацията точно както е описано по-горе.
Обратни обаждания
Хората често се обаждат обратно на номер, който им се е обадил, например след като вашият агент е оставил гласово съобщение. Когато постъпи телефонно обаждане от номер, на който е било обадено през последните 30 дни, ThunderPhone намира най-скорошното такова изходящо обаждане (при което телефонът е звънял) и го използва по три начина:
-
returning_callв заявката. Блокиращата заявка по-горе и известието от крайната точка го съдържат, така че вашият обработчик може да насочи обаждащия се:{ "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567", "returning_call": { "call_id": 987650001, "agent_id": 13, "started_at": "2026-10-21T19:05:12.402Z", "outcome": "voicemail" } } }Поле Тип Описание call_idцяло число Предишното изходящо обаждане agent_idцяло число | null Агентът, който го е извършил; nullза обаждане, извършено с вградена конфигурация, или когато агентът му е бил изтритstarted_atниз Кога е започнало (ISO 8601, UTC) outcomeниз no_answer(звъняло е без отговор, било е заето или е било отказано),voicemail(гласовата поща е отговорила или никой не е говорил с агента),conversation(някой е говорил с агента) илиanswered(отговорено е; все още не е известно кой е отговорил) -
Контекст за агента. Който и агент да отговори, получава кратка бележка в края на подканата си: кога е извършено предишното обаждане, от кой агент и какъв е резултатът от него. На агента е указано да не я прочита на глас и, тъй като идентификаторът на обаждащия се може да бъде подправен, да не споделя нищо за това обаждане освен че номерът е бил потърсен по-рано.
-
Резервен агент. Когато номерът няма входящ агент и не пристигне конфигурация, защото няма URL адрес на уебхук или вашият уебхук не е дал отговор (изтекло е времето за изчакване, не е могъл да бъде достигнат или е върнал
5xx,408или429и при двата опита), обаждането се насочва към агента, извършил предишното обаждане, вместо да бъде прекратено, стига този агент все още да съществува във вашата организация. То се изпълнява с публикуваните настройки на този агент. Всеки отговор, който вашият уебхук даде, все пак е определящ: друг4xx, тяло, което не е JSON обект,{}, или конфигурация, която не преминава валидацията, прекратява обаждането както преди. Входящ агент за номера винаги отговаря.
Споделяне на подробностите за предишното обаждане. Идентификаторът на обаждащия се може да бъде подправен, затова по
подразбиране нищо от съдържанието на предишното обаждане не достига до новото.
Администратор на организацията може да включи Споделяне на подробностите за предишното обаждане
в Организация → Общи → Обратни обаждания (или да зададе
callback_context_details_enabled).
Когато е включено, бележката на агента цитира и обобщението на предишното обаждане,
а обаждане, насочено към агента, извършил предишното обаждане, се изпълнява с
variables на това обаждане (например името на контакт). Включвайте го само ако
тези подробности могат безопасно да бъдат споделени с всеки, който се обади от този
номер. Дори когато е включено, обаждане, което може да съдържа защитена здравна
информация, никога не предава своето обобщение или променливи на обаждане, което
не е определено за обработка на PHI.
В подробностите за обаждането. Входящо обаждане, което съответства на по-ранно обаждане, има обект callback в GET /v1/calls/{call_id}:
горния returning_call, routed_as_callback (дали резервният вариант
го е приел) и config_webhook_failure ({kind, attempts, http_status, host} когато вашият webhook не е дал отговор и резервният вариант е поел
обаждането, в противен случай null), така че прекъсване на webhook остава видимо, въпреки че
обаждането е било прието.
Ограничение на размера на отговора
Примерен обработчик
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 {}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 по време на разговора:
{
"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"
}
}
}
]
}Кратка справка за настройките
Изпратете product: "bolt" и настройте разговора с тези полета. По-старите
стойности на product (spark и стойностите storm-*) все още се приемат.
| Поле | Стойности | Какъв е компромисът |
|---|---|---|
intelligence | core, pro (по подразбиране) | Core е по-евтин и започва да отговаря по-рано; Pro следва по-надеждно дълги подканвания |
audio_tier | lite, standard (по подразбиране), plus, max | По-високите нива чуват по-добре и струват повече; Plus добавя 1–2 s при някои реплики, всеки отговор на Max отнема 3–4 s (Max не е общодостъпен) |
endpointing | faster, fast, normal (по подразбиране), patient | По-кратките изчаквания водят до по-бързи отговори и струват повече |
faster_replies | true (по подразбиране), false | Ускорение: отговорите идват малко по-рано, срещу малко повече |
Свързани
Неблокиращото събитие при приключване на разговор.
Пълна JSON схема за tools[] и договорът за подписания крайна точка.
Абонирайте няколко URL адреса за telephony.incoming / web.incoming.
Шаблони за подкани, инструменти и A/B тестове за всеки обаждащ се.