ThunderPhone v3 вече е тук.Започнете самостоятелно — от 2 цента/мин.Прочетете съобщението

Connect tools & data

Използвайте ThunderPhone като MCP сървър

Създавайте, тествайте, валидирайте и управлявайте гласови агенти на ThunderPhone от Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code или друг Streamable HTTP MCP клиент.

ThunderPhone предоставя HTTP сървър с поточно предаване за Протокола за контекст на модела на:

https://api.thunderphone.com/v1/mcp

Това е обратната посока спрямо свързването на отдалечен MCP сървър с гласов агент:

ПосокаРезултат
Отдалечен MCP сървър → агент на ThunderPhoneГласов агент може да извиква инструментите на отдалечения сървър.
ThunderPhone → вашият MCP клиентВашият агент за програмиране може да създава, тества и управлява ThunderPhone.

Удостоверяване

Използвайте OAuth по подразбиране за клиенти от директорията: влезте, изберете организация и одобрете заявените разрешения. Прекъснете връзката от Настройки → Сигурност → Свързани приложения. Промяната или нулирането на паролата ви, както и промяната на имейла на акаунта ви, също отменят връзката, затова след това свържете клиента отново.

За клиенти, конфигурирани с API ключ, създайте ключ sk_live_ в Интеграции → API ключове и го предоставете на вашия MCP клиент като THUNDERPHONE_API_KEY. Ключът е обвързан с една организация; идентификатор, притежаван от друга организация, се третира като несъществуващ.

Организации, които обработват PHI

Ако обажданията на вашата организация може да съдържат защитена здравна информация (PHI), защото имате BAA с ThunderPhone или вашите агенти са определени като обработващи PHI, горният URL адрес никога не връща съдържание на обаждания: преписи, записи, оценки, списъци с обаждания, експортирания, резултати от кампании, анализи на обаждания и статистики, разговори, създадени от реални обаждания, и резултати от повторно възпроизвеждане. Тези инструменти връщат грешка с code: "phi_content_unavailable". Създаването, тестването и конфигурирането на агенти работи както обикновено.

Този URL адрес е посочен в публичните директории на асистенти, които не може да съдържат PHI. Ако вашата организация има собствен BAA с доставчика на асистента, обхващащ работното пространство, което използвате:

  1. Администратор на организацията отваря Организация → Общи → Достъп до AI асистент в ThunderPhone и потвърждава това покритие.
  2. Вместо това свържете асистента като персонализиран конектор с този URL адрес:
https://api.thunderphone.com/v1/mcp/baa

Тогава съдържанието на обажданията е налично там, включително обаждания, които може да съдържат PHI. Оттеглянето на потвърждението го спира при следващата заявка на асистента. Обаждане, което вашата организация е обработила като несъдържащо PHI, е налично и на двата URL адреса.

Алтернативи с CLI и stdio

CLI на ThunderPhone може да запише конфигурация на клиента, като запази несвързаните сървъри:

npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user

След глобална инсталация на @thunderphone/mcp използвайте thunderphone-mcp setup със същите опции. Настройката поддържа Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop и Windsurf. Директният HTTP е предпочитан; Desktop използва stdio.

За всеки клиент, който поддържа stdio, конфигурирайте command: "npx" с args: ["-y", "@thunderphone/mcp"]. Обвивката първо използва THUNDERPHONE_API_KEY, след това идентификационните данни от thunderphone login, като обновява изтеклите токени, а после OAuth чрез mcp-remote. Влизането от устройство и OAuth изискват съответното внедряване на API OAuth. Пътят с API ключ не го изисква. Директните HTTP конфигурации не четат хранилището за идентификационни данни на CLI; използвайте обвивката stdio, за да използвате повторно влизането от устройство.

Това са алтернативи на ръчните конфигурации на клиенти по-долу.

Конфигуриране на клиента

Claude и ChatGPT влизат чрез OAuth; не се използва API ключ. Ако все още нямате акаунт в ThunderPhone, изберете Създаване на акаунт на страницата за вход и след потвърждаване на имейла си ще се върнете към екрана за одобрение.

Claude (уеб, настолен компютър и мобилно устройство)

  1. Отворете Персонализиране → Конектори (Настройки → Конектори в по-стари версии). Ако ThunderPhone се показва в директорията с конектори, изберете го. В противен случай изберете Добавяне на персонализиран конектор, наименувайте го ThunderPhone и въведете https://api.thunderphone.com/v1/mcp.
  2. Изберете Свързване, влезте в ThunderPhone, изберете организацията и одобрете разрешенията.
  3. В чат активирайте ThunderPhone от менюто с инструменти и поискайте това, от което се нуждаете, например „Изброй моите агенти“.

Claude пита, преди да използва всеки инструмент за първи път. За да пропуснете повечето от тези подкани, отворете Персонализиране → Конектори → ThunderPhone и настройте Инструменти само за четене да бъдат винаги разрешени. Тези инструменти само извличат информация: агенти, обаждания, транскрипции, салда, документация. Оставете Инструменти за записване/изтриване с изискване за одобрение, ако искате да виждате всяка промяна, преди да се извърши.

Персонализираните конектори изискват платен план за Claude. При планове Team и Enterprise собственикът първо добавя конектора в настройките за конектори на организацията, след което всеки член свързва собствения си акаунт в ThunderPhone.

Какво е различното в Claude

Claude (конекторът и плъгинът Claude Code) получава по-ограничен набор от инструменти в съответствие с правилата на директорията за конектори на Claude:

  • Всяко обаждане и текстово съобщение се потвърждават поотделно. place_call и send_sms първо връщат предварителен преглед (агента, номерата „от“ и „до“, а за текстово съобщение — съобщението), както и confirmation_token; нищо не се извършва или изпраща, докато Claude не повтори заявката с токена след вашето потвърждение.
  • Без управление на кампании. create_campaign, add_campaign_contacts и campaign_action не са налични; създавайте, зареждайте и стартирайте кампании в таблото за управление. list_campaigns, get_campaign_stats и check_campaign продължават да работят.
  • Без test_integration. Тествайте заявката на интеграция от нейната страница в таблото за управление.
  • preview_voice възпроизвежда фиксиран примерен поздрав с избрания от вас глас и език; не произнася персонализиран текст.
  • list_voices и list_agents връщат обобщение; get_agent съдържа пълната конфигурация на агент.

Разкриване на използването на AI

Всяко обаждане, което агент на ThunderPhone извършва или приема, започва с устно разкриване на използването на AI. По подразбиране то гласи „Това обаждане е с AI асистент и ще бъде записано и транскрибирано.“ Изключването му (consent_announcement_enabled false или ai_live_processing_disclosure_override off) се отказва, освен ако администратор на организацията предварително не е записал подписана декларация в таблото за управление от който и да е клиент, включително Claude.

ChatGPT

  1. Ако ThunderPhone се показва в директорията с приложения на ChatGPT, изберете го и го свържете.
  2. В противен случай отворете Настройки → Приложения и конектори → Разширени настройки, включете Режим за разработчици и създайте конектор с URL адрес https://api.thunderphone.com/v1/mcp и OAuth удостоверяване.
  3. Влезте в ThunderPhone, изберете организацията и одобрете разрешенията. Добавете ThunderPhone към чат от менюто с инструменти.

Изтриването на агент или телефонен номер, отхвърлянето на чернова, стартирането на кампания и изпращането на тестова заявка, която може да записва във външна система, изискват второ потвърждение и в двете приложения; вижте Потвърждаване на разрушителни действия.

Claude Code

claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"

Codex

Добавете това към ~/.codex/config.toml:

[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"

Cursor

Създайте .cursor/mcp.json:

{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

Claude Desktop

Добавете мост mcp-remote към конфигурацията на Claude Desktop:

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code

Създайте .vscode/mcp.json и въведете ключа чрез подканата за въвеждане на VS Code:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}

Инструменти

Всеки инструмент съдържа MCP анотации. В таблиците R означава само за четене, D — деструктивен, I — идемпотентен, а O — взаимодействие с външния свят/мрежата. Тире означава, че няма зададена подсказка.

Връзка

ИнструментОсновни аргументиАнотацииКакво прави
get_connection_identity—R, IВалидира идентификационните данни и връща организацията и безопасни метаданни за идентификационните данни.

Агенти

ИнструментОсновни аргументиАнотацииКакво прави
list_agents—R, IИзвежда списък с агенти.
get_agentagent_idR, IПолучава един агент.
create_agentконфигурация на агент—Създава агент. Приема същите настройки като update_agent, включително steps, handoffs, intro_clip и intro_ring_count.
update_agentagent_id, променени полета, незадължителни prompt_edits, expected_prompt_sha256DПодготвя полета в черновата на агента, като заменя съществуващите в черновата. Изпълнява се без стъпка за потвърждение: внедреният агент остава непроменен до deploy_agent, а discard_agent_draft връща черновата към предишното ѝ състояние. Можете също да зададете max_hold_seconds, system_tool_settings и words. За да промените част от подканата, изпратете prompt_edits (вижте Редактиране на подкана на място).
deploy_agentagent_id, незадължителен if_updated_atD, IПубликува черновата в продукционна среда.
discard_agent_draftagent_id, незадължителен if_updated_at, confirmation_token при втората заявкаD, IОтхвърля подготвените промени. Изпълнява се в две стъпки, вижте Потвърждаване на разрушителни действия.
duplicate_agentagent_id, незадължително name—Копира агент в рамките на организацията.
delete_agentagent_id, confirmation_token при втората заявкаD, IИзтрива окончателно агент. Изпълнява се в две стъпки.
list_agent_versionsagent_idR, IИзвежда списък с внедрените версии на конфигурацията.
list_prompt_revisionsagent_id, незадължителни source, limit, offsetR, IИзвежда всяка промяна в текста на подканата на агента, включително черновите, всяка с разлика спрямо ревизията, която е заменила. Налично е, когато наборът инструменти за итерации на агенти е достъпен за вашата връзка (вижте по-долу).
review_promptagent_id, незадължителни prompt, previous_prompt, quote_id, max_cost_cents—Преглежда черновата на подканата (или текста, който изпращате) спрямо ръководството за стил на подканите. За всяко откритие цитира откъса, посочва насоката и предлага редакция за търсене и замяна; резултатът също изброява поведенията, които подканата изисква, със стабилни идентификатори, дали е необходимо преструктуриране и, за собствената подкана на агента, дали тестовите му разговори трябва да бъдат обновени. Не променя нищо по агента; списъкът се запазва с ревизията на подканата му. Платено е, затова не е отбелязано като само за четене: първо поискайте оферта с dry_run, след това го изпълнете отново без dry_run, с върнатите от него quote_id и max_cost_cents. Тези платени изпълнения вече се отчитат към същия лимит на набора инструменти за организацията като останалите изпълнения на набора инструменти. Налично е, когато наборът инструменти за итерации на агенти е достъпен за вашата връзка (вижте по-долу).
refactor_promptagent_id, незадължителни prompt, inventory, instructions, quote_id, max_cost_cents—Пренаписва подканата във формата от ръководството за стил и съпоставя всяко поведение като запазено, обединено, преформулирано или премахнато. Връща новия текст и разлика, като по подразбиране го прочита отново, за да отчете behavior_changes (добавени, премахнати или променени) и behavior_preserved; приложете го с update_agent. Платено: поискайте оферта с dry_run, след което го изпълнете веднъж с върнатите от него quote_id и max_cost_cents. Налично е, когато наборът инструменти за итерации на агенти е достъпен за вашата връзка (вижте по-долу).
list_reusable_instructions—R, IИзвежда списък с повторно използваеми инструкции: споделени правила за подкани, свързани с много агенти чрез reusable_instruction_ids на update_agent.
create_reusable_instructionname, content—Създава несвързана повторно използваема инструкция. Само за администратори.

Телефонни номера и оператори

ИнструментОсновни аргументиАнотацииКакво прави
list_phone_numbers—R, IИзвежда номерата и маршрутизирането на организацията.
get_phone_number_limits—R, IПолучава използването и лимитите на управляваните номера.
provision_phone_numberнезадължителни area_code, city, state, idempotency_keyD, OЗакупува входящ номер, управляван от ThunderPhone.
list_voip_connections—R, IИзвежда свързаните телекомуникационни доставчици на клиента.
search_voip_numbersconnection_id, country, type, незадължителен area_codeR, I, OТърси в наличностите на доставчика.
import_voip_numbersconnection_id, numbersD, OИмпортира номера, които вече са притежавани при доставчика.
update_phone_numberphone_number_id, полета за маршрутизиране/етикет/webhookDАктуализира маршрутизирането на номера, включително назначаването на агент.
delete_phone_numberphone_number_id, confirm, незадължителен release_at_provider, confirmation_token при втората заявкаD, I, OОсвобождава номер. В две стъпки.
get_voip_setup_sessionнезадължителен session_idR, IПрочита водена настройка на доставчик (статус, контролен списък, въпроса, който очаква), или извежда отворените настройки. Настройката започва в таблото, защото изисква паролата за доставчика. Само за администратори.
answer_voip_setup_questionsession_id, question_id, answerOПредава отговора на потребителя към настройката. Пароли, съгласие за тестово обаждане, адресът на сървъра, потребителското име и разрешението ThunderPhone да влезе в акаунта при доставчика се попълват само в съветника за настройка; за тях връща връзката към съветника и не изпраща нищо.
save_voip_setupsession_id, незадължителен name, confirmation_token при втората заявкаD, I, OЗапазва свързана чернова на връзка, за да може да се използва. В две стъпки.
check_phone_numberphone_number или phone_number_idR, I, OДиагностицира един от собствените номера на организацията въз основа на данни: маршрутизиране, връзка, потвърждение, скорошни обаждания от доставчика и тестови обаждания, както и къде доставчикът го насочва.

SMS

ИнструментОсновни аргументиАнотацииКакво прави
send_smsfrom_number, to, body, idempotency_keyD, I, OИзпраща едно SMS съобщение с обикновен текст чрез свързан номер на Twilio или Telnyx.

Обаждания

ИнструментОсновни аргументиАнотацииКакво прави
list_callsнезадължителни филтри, limit, offsetR, IИзвежда обажданията с филтрите за REST хронология на обажданията, включително exclude_test_calls.
get_callcall_idR, IИзвлича статуса и метаданните на обаждането.
get_call_transcriptcall_id, незадължително liveR, IИзвлича транскрипцията на обаждането.
get_call_audio_urlcall_id, незадължително downloadR, I, OВръща подписан URL за аудио; никога не предава аудио поточно чрез MCP.
get_call_gradecall_idR, IИзвлича най-новата оценка на обаждането.
place_callagent_id, from_number, to_numberD, OИзвършва едно неизпълняващо се идемпотентно изходящо обаждане.
export_callsфилтри за обаждания, export_formatR, IЕкспортира до ограничението на REST крайна точка като JSON или CSV.
get_call_analyticsнезадължителни since_days, agent_idR, IАгрегира реалните обаждания по статус, посока, резултат, оценка и проблем, като тестовите обаждания се отчитат отделно.
get_call_insightscall_ids (до 10)R, IИзвлича едновременно оценката, резултата, обобщението и откритите проблеми на няколко обаждания.

Тестване и валидиране

ИнструментОсновни аргументиАнотацииКакво прави
list_test_scenariosagent_idR, IИзвежда тестовите сценарии.
create_test_scenarioagent_id, title, scenario_prompt, незадължителни условия—Създава сценарий.
generate_test_scenariosagent_id, незадължителни count, include_edge_cases, localeOГенерира сценарии от подканата на агента.
run_agent_testsagent_id, channel, consent_to_charge, незадължителен избор/матрицаD, OИзпълнява сценарии чрез уеб или телефония.
get_test_runagent_id, batch_idR, IПолучава състоянието на пакета и резултатите за всеки сценарий.
test_my_agentagent_id, consent_to_charge, незадължителни scenario_ids, count, wait_secondsD, OТества агент с едно извикване: изпълнява запазените му сценарии (като генерира някои, когато няма такива) и изчаква до една минута за заключенията или връща batch_id за get_test_run. Таксува се като run_agent_tests.
test_in_textagent_id, callers (1 до 3 описания), незадължителни version, directionOБезплатен текстов тест: симулирани обаждащи се разговарят с черновата на агента (или с активната версия) чрез текст през реалния конвейер, а транскрипциите се връщат след около минута. Резултатите от инструмента са симулирани.
run_simulationagent_id, consent_to_charge, незадължителни scenario_prompt, direction, languageD, OСтартира едно симулирано телефонно обаждане между AI обаждащ се и черновата на агента, за да може човек да чуе промяна. Връща изпълнението със състояние in_progress. Записва се, когато агентът записва обаждания, и се оценява след приключването му. Таксува се като тестово обаждане, първо от безплатния бюджет за тестове.
get_simulationsimulation_idR, IПолучава състоянието на симулирано обаждане и, след като приключи, създаденото от него: URL за запис с кратък срок на валидност и транскрипцията, когато агентът записва обаждания, както и оценката след приключване на оценяването (null преди това).
list_validation_runsagent_idR, IИзвежда последните изпълнения за валидиране на черновата.
get_validation_statusagent_idR, IПолучава най-новото състояние на валидирането и съответствието на черновата.
list_conversationsagent_id, незадължителни split, sourceR, IИзвежда разговорите, спрямо които се тества агентът. Изисква набора от инструменти за итерация на агенти.
get_conversationconversation_idR, IПолучава един тестов разговор с текущите му ходове. Изисква набора от инструменти за итерация на агенти.
get_conversation_revisionsconversation_id, незадължителни limit, offsetR, IИзвежда всяка версия на тестов разговор: как и защо е променен (обновен за промяна в подканата, възстановен от по-ранна версия), добавените, премахнатите и променените поведения, преместените или оттеглените примери и разликите между редовете. Изисква набора от инструменти за итерация на агенти.
generate_conversationsagent_id, незадължителни count, styleOСъздава симулирани тестови разговори спрямо черновата на агента и превръща най-трудните им моменти в примери за валидиране с ключове за отговорите. Първо поискайте оферта с dry_run; реално изпълнение изисква неговите quote_id и max_cost_cents. Изисква набора от инструменти за итерация на агенти.
import_conversationsagent_id, незадължителни since_days, max_callsOПревръща последните обаждания на агента в тестови разговори (най-много по два на обаждащ се, като обажданията без запис се пропускат) и най-трудните им моменти в примери. Първо поискайте оферта с dry_run; реално изпълнение изисква неговите quote_id и max_cost_cents. Изисква набора от инструменти за итерация на агенти.
refresh_conversationsagent_id, незадължителни conversation_ids, from_prompt_revision_idOАктуализира тестовите разговори на агента спрямо текущата му подкана, след като поведения са добавени, премахнати или променени: пренасочва, възстановява по-ранна версия (включително реално аудио) или пренаписва остарелите ходове и оттегля примери, чийто ход на обаждащия се вече липсва. Първо поискайте оферта с dry_run; реално изпълнение изисква неговите quote_id и max_cost_cents. Изисква набора от инструменти за итерация на агенти.
get_conversation_jobjob_idR, IПолучава задача за генериране, импортиране или обновяване: състояние, натрупани разходи спрямо лимита и какво е създала или обновила. Изисква набора от инструменти за итерация на агенти.
run_replaysagent_id, незадължителни overrides, split, engine, sample_size, sample_seed, max_cost_cents, quote_id, dry_runD, OВъзпроизвежда извадка от примерите на агента с неговата чернова или със заместващи настройки като кандидат-подкана, глас или ниво и оценява всеки отговор спрямо ключа за отговор на примера. Точните възпроизвеждания изпълняват записаното аудио на хода, както би го изпълнило реално обаждане; процентите на успешно преминаване се отчитат за всеки механизъм. Възпроизвежданията на PHI обаждания се изпълняват като PHI, а конфигурация, която не могат да изпълнят (глас на ElevenLabs, експериментален продукт), се отказва. dry_run връща оценка, избрания sample_seed и quote_id; реално изпълнение изпраща същата заявка с този quote_id и sample_seed, както и max_cost_cents — твърд лимит: всяка заявка заделя горната си граница преди изпращане, а изпълнението спира, вместо да изпрати заявка, която не се побира, затова оставете резерв според largest_reservation_cents от оценката за всеки работник. Точно възпроизвеждане заделя най-лошия си случай — около 85 цента до $1.25 за всяко активно възпроизвеждане при типичен ход (две се изпълняват едновременно), при реална цена от няколко цента; изпълнението се таксува с действителната цена на възпроизвежданията, затова задайте max_cost_cents с резерв. Точното възпроизвеждане работи с бюджет, оразмерен за нормален ход плюс едно повторно изпълнение от вида, който се случва в продукционна среда (състезанието за отговор отново и повторен опит от наблюдател); ход, който изисква повече, се записва като грешка replay_budget_exhausted, отчита се отделно като budget_exhausted, изключва се от процента на успешно преминаване и при тестовия дял не изразходва кохорта. При тестовия дял кохорта със записано аудио на обаждащия се под конфигурация, различна от Bolt v2, се отказва (test_needs_exact_replay) и остава неизползвана: измерете тази конфигурация в дяла за разработка. Изисква набора от инструменти за итерация на агенти.
compare_configsagent_id, configs (2 до 4, първата е базовата), незадължителни sample_size, sample_seed, max_cost_cents, quote_id, dry_runOВъзпроизвежда едни и същи примери при всяка конфигурация и отчита процента на успешно преминаване, примерите, поправени и счупени спрямо базовата конфигурация, закъснението до първото аудио, колко често обаждащият се е чакал потвърждение, сигнали или тишина, и цената на ход за всеки механизъм. Поискайте оферта с dry_run както при run_replays. Само за дела за разработка: при тестовия дял се отказва (comparison_dev_only); сравнете в дела за разработка, след което измерете избраното с run_replays. Изисква набора от инструменти за итерация на агенти.
get_replay_runrun_id, незадължителен include_traceR, IПолучава общите резултати, промените и резултатите за всеки пример от изпълнение на възпроизвеждане, както и неговата група за сравнение. Точните възпроизвеждания, които са изисквали повече от бюджета си, се отчитат отделно (budget_exhausted), извън процента на успешно преминаване. Изисква набора от инструменти за итерация на агенти.
create_talk_linkagent_id, незадължителни variant_id, language, expires_in_minutesOСъздава връзка за еднократна употреба, която човек отваря в браузър, за да разговаря с текущата чернова на агента, подобно на бутона „Разговор“ в таблото. Връзката изтича по подразбиране след 30 минути (най-много 120); разговорът се таксува като тестово обаждане „Разговор“. Вижте връзки за разговор.

Инструментите, отбелязани като изискващи набора инструменти за итерация на агента, са част от него; наборът инструменти се активира за всяка организация, докато е в бета версия, а без него те връщат feature_not_enabled с указания какво да направите след това. Всеки разговор на агент е в неговия дял за разработка или в неговия тестов дял. Тестовият дял е за измерване на промяна, а не за нейното настройване, затова инструментите за разговори връщат разговор от тестовия дял само с неговите идентификатор, дял, източник, статус и броячи. Изпълнение на повторения в тестовия дял повтаря една цяла тестова кохорта (sample_size и sample_seed се игнорират), като изпълнява всеки пример с механизма, който данните му позволяват, определен преди изпълнението според примера (точен за записано аудио на обаждащия се, текстов за пример само с текст; конфигурация, различна от Bolt v2, няма точен път, така че кохорта със записано аудио се отказва за нея с test_needs_exact_replay и остава неизползвана; engine се пропуска или е auto, тъй като exact или text се отказват с test_engine_per_example и нищо не преминава към текстов режим), и връща само обобщени данни за всеки механизъм: процент на преминаване, неуспехи по сериозност и вид, забавяне и цена. Първият му резултат, който съхранява повторение, изразходва кохортата, така че следващото тестово изпълнение, за всяка подкана, взема друга, а когато не останат, се отказва с no_test_cohort (импортирането на обаждания или генерирането на разговори създава нови кохорти); изпълнение, което приключи преди да съхрани повторение (Core не може да повтори точно неговите аудио примери, exact_replay_unavailable, капацитетът му за повторения остава зает, core_busy, или всеки ход е изчерпал бюджета си, replay_budget_exhausted), оставя кохортата неизползвана. В дела за разработка точно повторение, което Core не може да изпълни, преминава към текстов режим и изпълнението се маркира като degraded. Сравненията се изпълняват само в дела за разработка. Всеки платен инструмент приема quote_id от своето пробно изпълнение, валиден за едно изпълнение: той се изразходва еднократно и трайно при стартиране на изпълнението, а старт, който бъде отказан или се провали преди това, го оставя използваем; изпълнение, което се провали след това, го посочва и се повтаря с ново пробно изпълнение за нов quote_id. С OAuth review_prompt и refactor_prompt изискват обхвата agents:write, включително за пробни изпълнения, а инструментите за разговори и повторения изискват testing:write, за да се изпълняват. Хората виждат целия тестов дял в таблото за управление. Обаждане, чийто обаждащ се е в тестовия дял на агент, е изключено, защото е част от тестовия набор. В организация с набора инструменти list_calls, get_call, get_call_transcript, get_call_audio_url, get_call_grade и export_calls го връщат точно като {"call_id", "start_time", "held_out": true} (started_at вместо start_time в редовете на експортиране), без неговите транскрипция, запис, история, оценка или отчет; всички останали полета на обаждането липсват, затова разчитайте изключен ред по неговото held_out преди всичко друго. REST API прави същото за API ключове и OAuth токени, а изгледите му за множество обаждания (обобщения на отчети, клъстери от проблеми, разследвания, отчети за конвейера) изключват изключените обаждания от своите броячи, клъстери и извадки и скриват всеки текст, който модел е написал от тях. Запис върху изключено обаждане (оценяване, повишаването му до тестов сценарий, повторно генериране на ход) се отказва с held_out_call. Тестов сценарий, който някой е повишил от изключено обаждане, се връща от list_test_scenarios и в тестовите изпълнения точно като {"id", "held_out": true}, а изпълнение на симулация от него, от get_test_run и инструментите за симулации, точно като {"id", "scenario_id", "held_out": true}; неговите симулирани обаждания също са изключени, а тестовите изпълнения все пак го изпълняват. Разговор за разработка, пример или резултат от повторение, копиран от обаждането на изключен обаждащ се (дяловете са за всеки агент, така че този обаждащ се може да е в тестовия дял на друг агент), се чете като такъв от тестовия дял. Хората виждат изключените обаждания изцяло в таблото за управление, а администратор може да позволи на един API ключ да ги вижда изцяло (include_held_out_calls, изключено по подразбиране, задава се само в таблото за управление) за интеграция, която се нуждае от всяко обаждане; MCP никога не го използва. Webhook-ите не са променени. Организациите без набора инструменти не виждат поле held_out и няма промяна.

generate_conversations, import_conversations и refresh_conversations изразходват кредити за модели. Първо ги извикайте с dry_run: true: отговорът е ценова оферта, стъпка по стъпка, с quote_id, и нищо не се изпълнява. Офертата отчита всяка заявка, която изпълнението може да направи при типичен размер. За реално изпълнение са нужни този quote_id (изтича след 15 минути и работи само със същите аргументи) и max_cost_cents, твърд лимит: преди всяка заявка задачата заделя максималната сума, която тя може да струва, и спира, вместо да изпрати заявка, която не се побира, като запазва написаното дотук. Поради това заделяне едно изпълнение може да спре с неизразходвана част от лимита си; largest_reservation_cents в офертата показва колко резерв да оставите. Симулираните обаждащи се се измислят от подсказката на агента; style: "adversarial" създава трудни обаждащи се, които поставят на изпитание слабите места на подсказката, и тези разговори винаги отиват в разделението за разработка. target: "changed_behaviors" насочва обаждащите се към промененото при последното редактиране на подсказката. За всеки агент се изпълнява по една от тези задачи или едно изпълнение на повторения наведнъж, така че опресняването никога не променя примерите, върху които се изпълнява повторение; стартиране, докато другото се изпълнява, връща job_active, replay_run_active или conversation_job_active с информация какво да изчакате.

След редактиране на подсказка, което добавя, премахва или променя поведение, review_prompt върху черновата на агента отчита колко тестови разговора са написани за подсказка с други поведения (conversations.refresh_suggested). След това refresh_conversations ги актуализира спрямо черновата, така че наборите за разработка и тестване да измерват новата подсказка върху истории, които тя би могла да произведе. Опресняването никога не губи нищо: всеки разговор запазва всяка предишна редакция, а когато премахнато правило се върне, се възстановява редакцията от времето, когато е съществувало, с реалното аудио на обаждащия се. Опресняване, стартирано от агент за програмиране, изключва от избора, офертата, напредъка и разхода разговорите от разделението за тестване и разговорите, копирани от изключени от извадката обаждания; посочването на такъв в conversation_ids връща 403 test_conversation. Човек ги опреснява от таблото за управление, а резултатите от тази задача ги показват на агентите за програмиране само като идентификатори и бройки. Пример с active, чиято история, отговор или ключ с верните отговори се пренаписва при опресняване, се връща в pending_review с етикет refreshed_needs_review. Офертата за опресняване калкулира цената на всеки разговор, който прочита, сякаш ще бъде пренаписан, и на всяко извикване на модел при неговия лимит за изход; тя важи за подсказката и разговорите, за които е издадена: ако някое от тях се промени преди изпълнението, поискайте нова оферта; ако подсказката се промени, докато задачата се изпълнява, тя спира като failed, като запазва опресненото дотук.

Знания

ИнструментОсновни аргументиАнотацииКакво прави
list_knowledge_bases—R, IИзвежда списък с бази знания.
create_knowledge_basename, незадължителен description—Създава база знания.
add_knowledge_documentknowledge_base_id, name, content—Добавя текст или Markdown.
import_knowledge_urlurl, незадължителен nameOПоставя публична страница на опашка за безопасно добавяне.
search_knowledgeknowledge_base_id, queryR, IТърси в извличането от продукционната среда.

Интеграции, уебкуки и отдалечени MCP сървъри

ИнструментОсновни аргументиАнотацииКакво прави
list_integrations—R, IИзвежда интеграциите на HTTP функции.
create_integrationdisplay_name, spec на функцията, незадължителни полета за крайна точка—Създава HTTP инструмент. Добавете заглавки за удостоверяване в таблото за управление.
test_integrationurl, незадължителни метод/тяло/изчакване, integration_id с header_names, confirmation_token при втората заявкаD, OИзпраща ограничена тестова заявка, защитена от SSRF. Запазените стойности на заглавките се попълват от интеграцията и се изпращат само до нейния собствен хост. POST (по подразбиране), PUT, PATCH и DELETE са в две стъпки; GET се изпълнява незабавно.
list_webhook_endpoints—R, IИзвежда крайните точки за подписани уебкуки.
list_webhook_deliveriesнезадължителен agent_id, незадължителен endpoint_idR, IИзвежда последните резултати от доставката на уебкуки без полезен товар.
create_webhook_endpointlabel, url, незадължителни събития/статусOСъздава крайна точка за подписан уебкук.
copy_webhook_endpointendpoint_id, target_agent_idIКопира уебкука на агент, включително тайната за подписване, към друг агент на сървъра. Само за администратори.
test_webhook_endpointendpoint_idOИзпраща синтетично събитие чрез обичайната доставка.
list_mcp_servers—R, IИзвежда отдалечени сървъри, извикваеми от гласови агенти.
create_mcp_serverdisplay_name, urlOРегистрира и синхронизира отдалечен сървър. Сървърите, които изискват заглавки за удостоверяване, се добавят в таблото за управление.
sync_mcp_server_toolsserver_idD, OОбновява каталога с инструменти на отдалечен сървър.

Кампании

ИнструментОсновни аргументиАнотацииКакво прави
list_campaigns—R, IИзвежда изходящите кампании.
create_campaignполета на кампанията—Създава чернова на кампания.
add_campaign_contactscampaign_id, contacts—Добавя до 5 000 JSON контакта.
campaign_actioncampaign_id, action, незадължителни consent_to_charge, confirmation_token при втората заявкаD, OИзпълнява start, pause, resume или stop. start и resume са в две стъпки; pause и stop се изпълняват незабавно.
get_campaign_statscampaign_idR, IПолучава броячи и скорошни резултати.
check_campaignнезадължителни campaign_id, contact_phone_number, contact_statusR, IОбяснява защо дадена кампания не се обажда: прозореца ѝ за обаждания в собствената ѝ часова зона, контактите, за които е време да бъдат потърсени сега, и какво спира набирането.

Настройки на организацията и блокирани обаждащи се

ИнструментОсновни аргументиАнотацииКакво прави
get_org_settings—R, IПрочита часовата зона, работното време, тестовите номера, етикетите за резултати от обаждания, имената на статусите и кои известия са изключени, с updated_at.
update_org_settingsпроменени настройки, if_updated_at, confirmation_token при поискванеD, IПроменя ги (само за администратори). Списъците и обектите заменят съхранената стойност. Изключването на известие или добавянето на тестов номер е в две стъпки. Резултатът съдържа старите стойности за отмяна.
get_account_limits—R, IПолучава ограниченията на платформата със собствените стойности на тази организация.
list_blocked_callersнезадължителни number, searchR, IИзвежда списък с блокираните номера на обаждащи се.
block_callersnumbers, незадължителен note, confirmation_token при втората заявкаD, IОтказва обаждания от тези номера, преди който и да е агент да отговори. В две стъпки, само за администратори.
unblock_callersnumbers, confirmation_token при втората заявкаD, IПремахва номера от списъка с блокирани. В две стъпки, само за администратори.

get_org_settings, update_org_settings и get_account_limits изискват org:read или org:write OAuth обхват; при първо използване връзка, създадена преди да съществуват, ще поиска одобрение за него.

Възможности, помощ и импортирания

ИнструментОсновни аргументиАнотацииКакво прави
get_supported_languages—R, IИзвежда езиците, които агентите говорят, с кодове.
get_agent_capabilities—R, IПоказва какво може да прави агент по време на обаждане и кои настройки и интеграции съществуват.
escalate_to_humansummaryOИска помощ от екипа на ThunderPhone. Те отговарят в ThunderPhone. За организации, които може да обработват PHI, от ThunderPhone излиза само неутрална бележка.
request_featuretitle, request, detailsOПодавa заявка за функционалност към екипа на ThunderPhone. Най-много три на организация на ден.
start_agent_importplatformR, IВръща връзката към таблото, където въвеждате своя ключ за Vapi, Retell, ElevenLabs или Bland и избирате агенти. Нито един инструмент не приема ключа.
get_agent_importнезадължителен import_idR, IИзвежда последните импортирания или статуса и съпоставените агенти на едно импортиране.
commit_agent_importimport_id, незадължителни item_idsOСъздава агентите от готово импортиране във фонов режим. Само за администратори.

Гласове, таксуване и документация

ИнструментОсновни аргументиАнотацииКакво прави
list_voices—R, IИзвежда списък с гласове и поддържани езици.
preview_voicevoice, language, textOГенерира пример и връща подписан URL адрес.
list_voice_clones—R, IИзвежда списък с персонализирани гласови клонинги.
get_billing_summary—R, IИзвлича баланса и официалните цени на нивата; не са достъпни промени по плащанията.
search_docsquery, незадължителен limitR, I, OТърси в индекса на публичната документация.
get_doc_pagepathR, I, OИзвлича една публична страница с документация в Markdown.

Резултатите за агент, обаждане, номер, кампания или настройка съдържат web_url — съответната страница в таблото, така че можете да я отворите в ThunderPhone или да продължите със Zeus там.

Всички продуктови инструменти използват същите REST кодови пътища като публичния API. Следователно REST валидирането, обхватът на организацията, ролите, допускането за фактуриране, квотите, потвърждението по TCPA, безопасността на доставчиците и поведението при одит се прилагат без промяна.

Редактиране на подкана на място

update_agent може да промени част от черновата на подканата, без да изпраща целия текст обратно. prompt_edits е подреден списък от двойки за намиране и замяна в същия формат, който връщат review_prompt и refactor_prompt:

{
  "agent_id": 123,
  "expected_prompt_sha256": "9c1f…",
  "prompt_edits": [
    {
      "find": "Ask for their name and their phone number, then tell them we will call back.",
      "replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
    }
  ]
}

Сървърът прилага редакциите по ред към текущата чернова на подканата на агента (разгърнатата подкана, когато няма чернова) и записва резултата в черновата по същия път като при update_agent с цяла подкана. Всеки find трябва да присъства точно веднъж в подканата във вида, в който е, когато дойде редът на съответната редакция. Ако това не е така, не се записва нищо и грешката посочва редакцията:

КодЗначениеКакво да направите
prompt_edit_not_foundТекстът find не е в текущата чернова на подканата. edit_index показва коя редакция.Прочетете агента отново и копирайте пасажа точно.
prompt_edit_ambiguousТекстът find се среща повече от веднъж. occurrences показва колко пъти.Включете повече от околния текст.
stale_promptexpected_prompt_sha256 не е SHA-256 на текущата чернова на подканата: тя се е променила, след като сте я прочели.Прочетете агента отново, пренапишете промяната спрямо текущия текст и изпратете неговия SHA-256.
conflictДруг запис е извършен между прочитането на черновата от сървъра и записването ѝ.Опитайте отново; черновата не е променена от това извикване.

expected_prompt_sha256 не е задължителен и също защитава записването на цяла подкана. Използвайте prompt_sha256 от review_prompt или source_prompt_sha256 от refactor_prompt. Всяко извикване, което променя подканата, връща prompt_sha256 за новия текст, previous_prompt_sha256, когато сървърът първо е прочел черновата, и next_step, предлагаща review_prompt с previous_prompt, зададен на текста преди промяната. REST API приема само цялата подкана: PATCH /v1/agents/{agent_id} с prompt и if_updated_at.

Потвърждаване на разрушителни действия

Инструментите, отбелязани с D, променят или премахват нещо, или започват да набират реални хора. За тези, които не могат да бъдат отменени, са необходими две заявки. Първата заявка не променя нищо и връща:

{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}

Асистентът показва на потребителя какво ще бъде засегнато и иска потвърждение. След това повтаря заявката със същите аргументи плюс confirmation_token. Токенът е валиден 10 минути, работи еднократно (дори ако това извикване е неуспешно) и важи за една организация, едно лице, един инструмент и един точен набор от аргументи, така че изтриването на три агента изисква три потвърждения. campaign_action с pause или stop пропуска тази стъпка, за да може изпълнявана кампания винаги да бъде спряна веднага, както и test_integration с GET. Някои инструменти с D се изпълняват с една заявка, защото D обозначава ефекта им, а не потвърждение от страна на сървъра: update_agent заменя съдържанието на черновата (discard_agent_draft го възстановява), deploy_agent заменя продукционната конфигурация, update_phone_number пренасочва активни обаждания, sync_mcp_server_tools заменя каталога с инструменти на отдалечен сървър, import_voip_numbers пренасочва номерата към вашия оператор, run_agent_tests и run_simulation могат да изразходват кредит, send_sms и place_call достигат до реален човек (place_call запазва собственото си потвърждение за съгласие), а provision_phone_number купува номер. test_my_agent изразходва кредит за тестове и изисква consent_to_charge. run_replays също изразходва средства; неговата оценка от dry_run и ограничението max_cost_cents заместват потвърждението. Вашият MCP клиент все пак може да поиска да ги одобрите.

Някои промени, които могат да бъдат отменени, все пак изчакват потвърждение: винаги block_callers, unblock_callers и save_voip_setup; update_org_settings, когато деактивира предупреждение или добавя тестов номер; и update_agent, когато неговите attention_reasons деактивират едно от предупрежденията на агента. Техният next_step ви подканва да потвърдите точната промяна, вместо да предупреждава, че тя не може да бъде отменена.

Начални подкани

prompts/list предлага дванадесет многократно използваеми работни процеса:

  • create_inbound_receptionist
  • run_agent_tests
  • buy_and_attach_number
  • review_low_grade_calls
  • add_url_to_agent_knowledge
  • improve_agent_from_calls
  • check_change_before_deploy
  • test_my_agent
  • diagnose_phone_number
  • why_campaign_not_calling
  • call_report
  • import_agents

Използвайте prompts/get с името на посочената подкана и декларираните ѝ аргументи, за да получите готово за изпълнение потребителско съобщение.

Ресурси

resources/list предоставя публични кеширани справки:

URIСъдържание
thunderphone://docs/llms.txtИндекс на публичната документация.
thunderphone://docs/quickstartMarkdown за бърз старт.
thunderphone://pricingАктуален Markdown с публичните цени.
thunderphone://guides/prompt-styleРъководството за стил на подканите за гласови агенти, спрямо което review_prompt извършва проверка. Идентификаторите на насоките му (P1, W2 и т.н.) са тези, които се цитират в констатациите.
thunderphone://guides/working-with-thunderphoneКак асистентът трябва да работи с тези инструменти: малки итерации върху черновата, проверка преди всяко внедряване, потвърждение от потребителя за всичко, което е активно или се таксува, и никога да не иска тайни.

Прочетете ресурс с resources/read. Публичните извличания използват кратко изчакване, ограничение от 2 MiB и десетминутен кеш в процеса.

Протокол и грешки

Сървърът поддържа версиите на протокола 2025-06-18 и 2025-03-26; връща поддържана версия на клиента, а в противен случай избира 2025-06-18. Той имплементира initialize, ping, инструменти, подкани, ресурси и известия. Известията връщат 202 Accepted. Този сървър без състояние не предоставя SSE слушател или изтриване на сесия, затова GET и DELETE връщат 405 Method Not Allowed с Allow: POST.

Неуспехите на инструменти остават успешни JSON-RPC отговори с isError: true. Текстът им съдържа кратко изречение, последвано от JSON блок:

{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}

Отличителният префикс outbound_tcpa_confirmation_required: се запазва за place_call. Непознатите JSON-RPC методи връщат -32601 в HTTP отговор 200. JSON-RPC пакетите не се поддържат от MCP 2025-06-18 и връщат коректна грешка за невалидна заявка -32600.