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

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

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

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

| Что вы делаете в чате | Что вызывает ваш бот | Что происходит |
|---|---|---|
| Отправляете «Позвони в Comcast и узнай ожидаемое время устранения сбоя» | [`POST /v1/call`](/api-reference/outbound-calls) с сообщением в качестве `context` | Агент звонит. Ваш бот открывает тред для звонка |
| Следите за тредом | Получает вебхуки [`telephony.turn`](/ru/webhooks/events) | Каждая реплика агента или другого человека появляется в треде |
| Отвечаете в треде во время звонка | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Агент получает вашу заметку конфиденциально и действует согласно ей. Другой человек её не слышит |
| Отвечаете на вопрос агента | Ваша [конечная точка инструмента](/ru/guides/build-tool-integration) возвращает ваш ответ или передаёт его позже через [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Агент продолжает звонок с этим ответом; в режиме ожидания другой человек тем временем слышит музыку ожидания |
| Читаете результат | Получает [`telephony.complete`](/ru/webhooks/events) | Ваш бот публикует сводку и результат |

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

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

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

<Tip>
  Используйте приложение Slack, созданное для собственного рабочего пространства, и получайте сообщения
  через Events API Slack, а не читая историю каналов. Slack
  устанавливает строгие ограничения на чтение для приложений, распространяемых в другие рабочие пространства за пределами
  Marketplace; приложение, созданное для собственного рабочего пространства, не подпадает под
  эти ограничения, а события поступают к вам по мере возникновения без каких-либо операций чтения. Типичные
  области доступа бота: `chat:write`, `app_mentions:read`, `im:history` (прямые
  сообщения), `channels:history` и `groups:history` (ответы в тредах
  публичных и частных каналов, в которых состоит бот). Подпишитесь на события бота
  `app_mention`, `message.im`, `message.channels` и `message.groups`, а также
  включите вкладку Messages в разделе App Home, чтобы люди могли отправлять боту личные сообщения.
</Tip>

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

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

```bash
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` и
опубликуйте строку.

- **Проверяйте каждый вебхук** перед выполнением действий. См.
  [Проверка подписей вебхуков](/ru/guides/verify-webhook-signatures).
- **Устраняйте дубликаты по `event_id` оболочки и упорядочивайте по `position`.**
  Доставка выполняется как минимум один раз, а реплики могут приходить не по порядку.
- **Объединяйте строки в пакеты**, если активный звонок может перегрузить ветку; публикация раз в несколько
  секунд читается лучше, чем одно сообщение на строку.

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

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

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

```bash
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-подключение](/ru/guides/build-tool-integration) и свяжите с агентом.
Каждый запрос инструмента передаёт звонок в заголовке `X-ThunderPhone-Call-ID`.

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

**Удерживайте звонок (до 10 минут).** Переведите инструмент в режим удержания: `spec.wait_mode`
`"hold"` и `spec.timeout` до 600 секунд (без тайм-аута удержание
длится 20 секунд) через
[API](/api-reference/integrations#timeout-and-wait-mode) или попросите Zeus
настроить их (в редакторах приложения этих полей пока нет). Ваш эндпоинт публикует вопрос в ветке звонка и сразу отвечает
ожидающим результатом:

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

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

```bash
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`, агенту сообщается, что ответа не было, и он предлагает
собеседнику дальнейшие действия. Пока вопрос ожидает ответа для звонка,
следующий ответ в его треде отвечает на него: доставьте его как результат инструмента и
не отправляйте его также как подсказку (подсказка достигает агента только после
возврата инструмента). См.
[Длительные ожидания](/ru/tools/overview).

**Ждать в запросе (до 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 минут. Звонок не удерживается: в вашем промпте следует указать
агенту, что делать тем временем, например поддерживать беседу с человеком или предлагать
перезвонить ему.

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

```text
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`](/api-reference/organizations#legacy-single-url-webhook).
- Решите, кто может начинать звонки: проверяйте идентификатор пользователя Slack перед совершением звонка.
- Исходящие звонки подчиняются тем же правилам, что и любые другие. См. [Законы об исходящих звонках](/ru/guides/outbound-calling-laws).

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

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