---
title: "Spouštějte hovory ze Slacku nebo chatovací aplikace"
description: "Vytvořte si vlastního bota pro Slack, Teams nebo webový chat, který zahajuje hovory, sleduje je živě, řídí agenta a odpovídá na jeho otázky pomocí veřejného API."
---

Agenta můžete ovládat z chatovací aplikace, kterou váš tým již používá. Zpráva
zahájí hovor. Hovor probíhá živě ve vlákně. Odpověď ve vlákně
směruje agenta. Když agent potřebuje rozhodnutí, zeptá se vás tam a
čeká na vaši odpověď.

ThunderPhone tohoto bota nehostuje za vás. Vy (nebo váš programovací agent) vytvoříte
malý server, který propojí vaši chatovací aplikaci s veřejným API. Tato stránka ukazuje
jednotlivé části. Jsou stejné pro Slack, Microsoft Teams, Discord nebo soukromou
webovou chatovací stránku; příklady používají Slack.

## Jak to funguje dohromady

| Co uděláte v chatu | Co zavolá váš bot | Co se stane |
|---|---|---|
| Odešlete „Zavolej Comcastu a zjisti odhad času odstranění výpadku“ | [`POST /v1/call`](/api-reference/outbound-calls) se zprávou jako `context` | Agent vytočí číslo. Váš bot otevře vlákno pro hovor |
| Sledujete vlákno | Přijímá webhooky [`telephony.turn`](/cs/webhooks/events) | Každá věta, kterou řekne agent nebo druhá osoba, se zobrazí ve vlákně |
| Odpovíte ve vlákně během hovoru | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Agent vaši poznámku obdrží soukromě a podle ní jedná. Druhá osoba ji nikdy neuslyší |
| Odpovíte na otázku agenta | Váš [koncový bod nástroje](/cs/guides/build-tool-integration) vrátí vaši odpověď nebo ji doručí později pomocí [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Agent s ní pokračuje v hovoru; v režimu podržení druhá osoba mezitím slyší hudbu při čekání |
| Přečtete si výsledek | Přijímá [`telephony.complete`](/cs/webhooks/events) | Váš bot zveřejní souhrn a výsledek |

Váš bot udržuje jedno mapování: které chatovací vlákno patří ke kterému `call_id`.

## Než začnete

- **Klíč API**, uložený na vašem serveru, nikdy v prohlížeči ani v chatu.
  Vytvořte jej v části **Integrace → Klíče API** (viz
  [Vytvoření serverového klíče API](/cs/guides/api-keys)).
- **Číslo s povolenými odchozími hovory a agent** pro hovory. Zpráva se
  pro každý hovor stane `context`, takže jeden obecný agent zvládne každý úkol.
- **Server**, který může přijímat webhooky, například Railway, Fly.io, Render
  nebo váš vlastní hosting.
- **Koncový bod webhooku**, který odkazuje na tento server a odebírá události
  `telephony.turn` a `telephony.complete`. Události tahů se odesílají pouze na
  koncové body, které je uvádějí. Viz [Webhooky](/cs/webhooks/endpoints).
  Události tahů vyžadují zapnuté nahrávání hovorů agenta a `summary` na konci
  hovoru vyžaduje nastavení agenta **Generovat souhrn hovoru**; bez nich
  zůstanou tato pole prázdná.
- **Vlastní chatovací aplikace.** Pro Slack vytvořte aplikaci ve svém pracovním
  prostoru na [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Použijte aplikaci Slack, kterou vytvoříte pro vlastní pracovní prostor, a zprávy
  přijímejte prostřednictvím API událostí Slacku namísto čtení historie kanálu. Slack
  uplatňuje přísné limity čtení na aplikace distribuované do jiných pracovních prostorů mimo
  jeho Marketplace; aplikace vytvořená pro vlastní pracovní prostor jim nepodléhá
  a události k vám přicházejí okamžitě bez jakéhokoli čtení. Běžná
  oprávnění bota: `chat:write`, `app_mentions:read`, `im:history` (přímé
  zprávy), `channels:history` a `groups:history` (odpovědi ve vláknech ve
  veřejných a soukromých kanálech, ve kterých bot je). Přihlaste odběr událostí bota
  `app_mention`, `message.im`, `message.channels` a `message.groups` a
  zapněte kartu Zprávy v části Domovská stránka aplikace, aby lidé mohli botovi posílat přímé zprávy.
</Tip>

## 1. Zahájení hovoru ze zprávy

Když váš bot obdrží zprávu (přímou zprávu nebo zmínku pomocí @),
okamžitě potvrďte požadavek Slacku (Slack opakuje vše, co není
potvrzeno do 3 sekund), a zbytek zpracujte na pozadí. Ověřte,
že odesílatel smí uskutečňovat hovory, a poté zahajte hovor se
zprávou jako `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"
  }'
```

Uložte vrácené `call_id` k vláknu Slacku (`channel` spolu s
hodnotou `ts` zprávy) a odpovězte ve vlákně („Volám…“). Sestavte
`idempotency_key` z kanálu a hodnoty `ts` zprávy (hodnota `ts` je jedinečná
pouze v rámci svého kanálu), aby opakovaná událost Slacku nezahájila druhý
hovor. Pokud požadavek uvádí osobu namísto čísla, bot nejprve vyhledá její
číslo. ThunderPhone vytáčí pouze `to_number`, které odešlete.

## 2. Sledování hovoru ve vlákně

Každý webhook `telephony.turn` obsahuje `call_id`, mluvčího (`role`:
`assistant` pro agenta, `user` pro druhou osobu), `text` a
`position` tahu. Vyhledejte vlákno podle `call_id` a
zveřejněte řádek.

- **Ověřte každý webhook**, než podle něj provedete akci. Viz
  [Ověření podpisů webhooků](/cs/guides/verify-webhook-signatures).
- **Deduplikujte podle `event_id` obálky a řaďte podle `position`.**
  Doručení probíhá alespoň jednou a tahy mohou přicházet v nesprávném pořadí.
- **Dávkujte řádky**, pokud by vytížený hovor zahltil vlákno; zveřejňování
  každých několik sekund se čte lépe než jedna zpráva na řádek.

Když dorazí `telephony.complete`, zveřejněte způsob ukončení hovoru (jeho
`status` a `end_reason`), `summary` a veškerá extrahovaná data a vlákno
uzavřete. Informace o polích najdete v části [Dokončení hovoru](/cs/webhooks/call-complete).

## 3. Řízení hovoru z vlákna

Když někdo odpoví ve vlákně aktivního hovoru, odešlete odpověď jako šepot,
pokud agent nečeká na odpověď na otázku (krok 4); v takovém případě je odpověď
řešením otázky:

```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."}'
```

Agent jej slyší soukromě a začlení ho do svého dalšího tahu; druhá
osoba samotný šepot nikdy neuslyší. Šepot má 1 až 1000 znaků. Hodnota
`409` znamená, že hovor už není aktivní: informujte vlákno, že hovor skončil.

## 4. Nechte agenta, aby se vás zeptal

Dejte agentovi nástroj, například `ask_owner` s jedním parametrem
`question`, který volá váš server. Vytvořte jej jako
[API připojení](/cs/guides/build-tool-integration) a propojte jej s agentem.
Každý požadavek nástroje nese hovor v hlavičce `X-ThunderPhone-Call-ID`.

Existují tři způsoby, jak získat odpověď zpět.

**Podržte hovor (až 10 minut).** Nastavte nástroj do režimu podržení: `spec.wait_mode`
`"hold"` a `spec.timeout` až na 600 sekund (bez časového limitu podržení
trvá 20 sekund), prostřednictvím
[API](/api-reference/integrations#timeout-and-wait-mode) nebo požádejte Zeus,
aby je nastavil (editory aplikace zatím nemají ani jedno z těchto polí). Váš koncový bod odešle otázku do vlákna hovoru a ihned odpoví
čekajícím výsledkem:

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

Druhá strana uslyší jednu větu od agenta a poté čekací hudbu. V telefonním
menu nebo hlasové schránce agent místo toho používá mluvené aktualizace a
agent s plným duplexem hovor nepodrží: čekající odpověď obdrží jako výsledek. Když
odpověď dorazí do vlákna, doručte ji pomocí
[`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."}}'
```

Hudba postupně ztichne a agent pokračuje s vaší odpovědí. Pokud nikdo
neodpoví před vypršením `timeout`, agent se dozví, že odpověď nepřišla, a nabídne
druhé straně další kroky. Dokud je otázka pro hovor čekající, následující
odpověď v jeho vlákně ji zodpoví: doručte ji jako výsledek nástroje a
neposílejte ji zároveň jako šeptanou zprávu (šeptaná zpráva se k agentovi dostane až po
vrácení výsledku nástroje). Viz
[Dlouhá čekání](/cs/tools/overview).

**Čekejte v požadavku (až 3 minuty).** Váš endpoint odešle otázku,
čeká na odpověď a vrátí ji, například `{"answer": "Yes, book Tuesday at 10."}`.
Nastavte `spec.timeout` nástroje prostřednictvím API až na 180 sekund (výchozí
hodnota je 20). Dejte svému endpointu vlastní časový limit o několik sekund kratší
(například 170 sekund), aby i v případě, že nikdo neodpoví, stále vrátil
něco, s čím agent může pracovat, například
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Nástroj,
který dosáhne hodnoty `timeout`, se k agentovi dostane jako chyba a váš hostitel musí
požadavek udržet otevřený po celou tuto dobu. Během čekání agent druhé straně řekne,
že to ověřuje, asi po 12 sekundách oznámí, že na tom stále pracuje, a
poté poskytne krátkou aktualizaci přibližně každých 15 sekund. Režim podržení
funguje i zde: nastavte `spec.wait_mode` na `"hold"` a druhá strana uslyší hudbu
místo aktualizací.

**Odpovězte šeptanou zprávou.** Váš endpoint odešle otázku a ihned se vrátí,
například `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Když odpověď dorazí, odešlete ji jako šeptanou zprávu (krok 3) a agent
na ni ihned odpoví. Použijte to pro odpovědi, které mohou trvat déle než
10 minut. Hovor není podržen: vaše výzva by měla agentovi říct,
co má mezitím dělat, například dělat druhé straně společnost nebo jí nabídnout,
že jí zavoláte zpět.

V každém případě v zadání agenta uveďte, kdy má nástroj použít a co má
druhé straně říct, zatímco čeká:

```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.
```

## Limity, se kterými je třeba počítat

- Váš endpoint musí odpovědět v rámci hodnoty `timeout` nástroje, maximálně do **180 sekund**. Nástroj v režimu podržení může hovor podržet až **600 sekund** s čekajícím výsledkem.
- Zatímco nástroj čeká, agent druhé osobě neodpovídá. V režimu podržení slyší hudbu; jinak krátké mluvené aktualizace.
- Šeptání má maximálně **1000 znaků**.
- Doručení `telephony.turn` probíhá alespoň jednou a může být mimo pořadí.

## Kontrolní seznam zabezpečení

- Klíč API uchovávejte na svém serveru.
- Ověřujte podpisy ThunderPhone ve webhookech a požadavcích nástrojů a podpisové tajemství Slacku v požadavcích Slacku. Dva podpisy ThunderPhone používají různá tajemství: doručení webhooků používají vlastní tajemství endpointu webhooku a požadavky nástrojů používají tajemství webhooku vaší organizace z [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Rozhodněte, kdo může zahajovat hovory: před uskutečněním hovoru ověřte ID uživatele Slacku.
- Odchozí hovory se řídí stejnými pravidly jako všechny ostatní. Viz [Právní předpisy pro odchozí volání](/cs/guides/outbound-calling-laws).

## Vytvořte to pomocí programovacího agenta

Nasměrujte svého programovacího agenta na [server MCP dokumentace](/cs/guides/docs-mcp) a na tuto stránku a požádejte jej o „bota pro Slack pro mého agenta ThunderPhone, který se řídí tímto návodem“. Zeus, asistent v aplikaci ThunderPhone, může nastavit část pro agenta (endpoint webhooku, nástroj a řádky promptu) a v chatu napsat počáteční kód pro bota.
