Open in
Запускайте звонки из 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, может настроить сторону агента (конечную точку вебхука, инструмент и строки промпта) и написать начальный код для бота в чате.