ThunderPhone v3 уже доступен.Самостоятельный запуск — от 2 ¢/мин.Читать анонс

Developer cookbook

Запускайте звонки из Slack или чат-приложения

Создайте собственного бота для Slack, Teams или веб-чата, который запускает звонки, отслеживает их в реальном времени, направляет голосового агента и отвечает на его вопросы с помощью публичного API.

Вы можете управлять агентом из приложения для чата, которым уже пользуется ваша команда. Сообщение запускает звонок. Звонок развивается в реальном времени в треде. Ответ в треде направляет агента. Когда агенту нужно решение, он задаёт вам вопрос там и ждёт вашего ответа.

ThunderPhone не размещает этого бота за вас. Вы (или ваш агент для программирования) создаёте небольшой сервер, который подключает ваше приложение для чата к публичному API. На этой странице показаны компоненты. Они одинаковы для Slack, Microsoft Teams, Discord или частной веб-страницы чата; в примерах используется Slack.

Как это устроено

Что вы делаете в чатеЧто вызывает ваш ботЧто происходит
Отправляете «Позвони в Comcast и узнай ожидаемое время устранения сбоя»POST /v1/call с сообщением в качестве contextАгент звонит. Ваш бот открывает тред для звонка
Следите за тредомПолучает вебхуки telephony.turnКаждая реплика агента или другого человека появляется в треде
Отвечаете в треде во время звонкаPOST /v1/calls/{call_id}/whisperАгент получает вашу заметку конфиденциально и действует согласно ей. Другой человек её не слышит
Отвечаете на вопрос агентаВаша конечная точка инструмента возвращает ваш ответ или передаёт его позже через POST /v1/calls/{call_id}/tool-resultsАгент продолжает звонок с этим ответом; в режиме ожидания другой человек тем временем слышит музыку ожидания
Читаете результатПолучает telephony.completeВаш бот публикует сводку и результат

Ваш бот хранит одно сопоставление: какой тред чата относится к какому call_id.

Перед началом

  • Ключ API, хранящийся на вашем сервере, но никогда не в браузере или чате. Создайте его в разделе Интеграции → Ключи API (см. Создание серверного ключа API).
  • Номер с поддержкой исходящих звонков и агент для звонков. Сообщение становится context для конкретного звонка, поэтому один универсальный агент выполняет любые задачи.
  • Сервер, который может получать вебхуки, например Railway, Fly.io, Render или ваш собственный хост.
  • Конечная точка вебхука, указывающая на этот сервер и подписанная на telephony.turn и telephony.complete. События хода разговора отправляются только в конечные точки, которые их перечисляют. См. Вебхуки. Для событий хода разговора должна быть включена запись звонков агента, а для итогового summary нужна настройка агента Создавать сводку звонка; без них эти поля остаются пустыми.
  • Собственное чат-приложение. Для Slack создайте приложение в своём рабочем пространстве на api.slack.com/apps.

1. Запустите звонок из сообщения

Когда ваш бот получает сообщение (личное сообщение или @упоминание), сразу подтвердите запрос Slack (Slack повторяет всё, что не было подтверждено в течение 3 секунд), а остальное выполните в фоновом режиме. Проверьте, что отправителю разрешено совершать звонки, затем запустите звонок, передав сообщение как context:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

Сохраните возвращённый call_id для ветки Slack (channel вместе с ts сообщения) и ответьте в ветке («Звоним…»). Сформируйте idempotency_key из канала и ts сообщения (ts уникален только в пределах своего канала), чтобы повторно отправленное событие Slack не создало второй звонок. Если в запросе указано имя человека, а не номер, ваш бот сначала найдёт номер. ThunderPhone звонит только на переданный вами to_number.

2. Отслеживайте звонок в ветке

Каждый вебхук telephony.turn содержит call_id, говорящего (role: assistant для агента, user для другого человека), text и position реплики. Найдите ветку по call_id и опубликуйте строку.

  • Проверяйте каждый вебхук перед выполнением действий. См. Проверка подписей вебхуков.
  • Устраняйте дубликаты по event_id оболочки и упорядочивайте по position. Доставка выполняется как минимум один раз, а реплики могут приходить не по порядку.
  • Объединяйте строки в пакеты, если активный звонок может перегрузить ветку; публикация раз в несколько секунд читается лучше, чем одно сообщение на строку.

Когда приходит telephony.complete, опубликуйте сведения о завершении звонка (его status и end_reason), summary и все извлечённые данные, затем закройте ветку. Сведения о полях см. в разделе Завершение звонка.

3. Направляйте звонок из ветки

Когда кто-то отвечает в ветке активного звонка, отправьте ответ как приватную подсказку, если агент не ждёт ответа на вопрос (шаг 4), — в этом случае ответ и будет ответом на вопрос:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

Агент слышит её приватно и использует в следующей реплике; другой человек никогда не слышит саму подсказку. Длина приватной подсказки — от 1 до 1000 символов. Код 409 означает, что звонок больше не активен: сообщите ветке, что звонок завершён.

4. Позвольте агенту задать вам вопрос

Дайте агенту инструмент, например ask_owner с одним параметром question, который вызывает ваш сервер. Создайте его как API-подключение и свяжите с агентом. Каждый запрос инструмента передаёт звонок в заголовке X-ThunderPhone-Call-ID.

Есть три способа получить ответ.

Удерживайте звонок (до 10 минут). Переведите инструмент в режим удержания: spec.wait_mode "hold" и spec.timeout до 600 секунд (без тайм-аута удержание длится 20 секунд) через API или попросите Zeus настроить их (в редакторах приложения этих полей пока нет). Ваш эндпоинт публикует вопрос в ветке звонка и сразу отвечает ожидающим результатом:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

Собеседник слышит одну реплику агента, затем музыку ожидания. В телефонном меню или голосовой почте агент вместо этого использует голосовые обновления, а полнодуплексный агент не удерживает звонок: он получает ожидающий ответ как результат. Когда ответ поступает в тред, доставьте его с помощью POST /v1/calls/{call_id}/tool-results:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

Музыка постепенно затихает, и агент продолжает с вашим ответом. Если никто не ответит до timeout, агенту сообщается, что ответа не было, и он предлагает собеседнику дальнейшие действия. Пока вопрос ожидает ответа для звонка, следующий ответ в его треде отвечает на него: доставьте его как результат инструмента и не отправляйте его также как подсказку (подсказка достигает агента только после возврата инструмента). См. Длительные ожидания.

Ждать в запросе (до 3 минут). Ваш эндпоинт публикует вопрос, ожидает ответа и возвращает его, например {"answer": "Yes, book Tuesday at 10."}. Настройте spec.timeout инструмента через API до 180 секунд (по умолчанию — 20). Установите для эндпоинта собственный дедлайн на несколько секунд меньше (например, 170 секунд), чтобы, если никто не ответит, он всё равно возвращал данные, с которыми агент сможет работать, например {"answer": null, "note": "No reply yet. Offer to take a message."}. Инструмент, достигший timeout, поступает агенту как ошибка, а ваш хост должен держать запрос открытым всё это время. Пока он ждёт, агент сообщает собеседнику, что проверяет информацию, примерно через 12 секунд говорит, что всё ещё работает, а затем даёт краткое обновление примерно каждые 15 секунд. Здесь также работает режим удержания: установите для spec.wait_mode значение "hold", и собеседник услышит музыку вместо обновлений.

Отвечать подсказкой. Ваш эндпоинт публикует вопрос и сразу возвращает ответ, например {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Когда ответ поступит, отправьте его как подсказку (шаг 3), и агент сразу на него отреагирует. Используйте этот вариант для ответов, получение которых может занять более 10 минут. Звонок не удерживается: в вашем промпте следует указать агенту, что делать тем временем, например поддерживать беседу с человеком или предлагать перезвонить ему.

Во всех случаях укажите в промпте агента, когда использовать инструмент и что говорить собеседнику во время ожидания:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

Ограничения, которые нужно учесть

  • Ваша конечная точка должна ответить в пределах timeout инструмента, но не позднее чем через 180 секунд. Инструмент в режиме удержания может удерживать звонок до 600 секунд, пока ожидается результат.
  • Пока инструмент ожидает, агент не отвечает собеседнику. В режиме удержания он слышит музыку; в противном случае — короткие голосовые обновления.
  • Подсказка содержит не более 1000 символов.
  • Доставка telephony.turn выполняется как минимум один раз и может происходить не по порядку.

Контрольный список безопасности

  • Храните API-ключ на своём сервере.
  • Проверяйте подписи ThunderPhone в вебхуках и запросах инструментов, а также секрет подписи Slack в запросах Slack. Две подписи ThunderPhone используют разные секреты: для доставок вебхуков используется собственный секрет конечной точки вебхука, а для запросов инструментов — секрет вебхука вашей организации из GET /v1/webhook.
  • Решите, кто может начинать звонки: проверяйте идентификатор пользователя Slack перед совершением звонка.
  • Исходящие звонки подчиняются тем же правилам, что и любые другие. См. Законы об исходящих звонках.

Создайте это с помощью агента для программирования

Укажите вашему агенту для программирования MCP-сервер документации и эту страницу, затем попросите создать «бота Slack для моего агента ThunderPhone, который следует этому руководству». Zeus, помощник в приложении ThunderPhone, может настроить сторону агента (конечную точку вебхука, инструмент и строки промпта) и написать начальный код для бота в чате.