ThunderPhone v3 je venku.Spustíte sami, od 2 ¢/min.Přečíst oznámení

Developer cookbook

Spouštějte hovory ze Slacku nebo chatovací aplikace

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 chatuCo zavolá váš botCo se stane
Odešlete „Zavolej Comcastu a zjisti odhad času odstranění výpadku“POST /v1/call se zprávou jako contextAgent vytočí číslo. Váš bot otevře vlákno pro hovor
Sledujete vláknoPřijímá webhooky telephony.turnKaždá věta, kterou řekne agent nebo druhá osoba, se zobrazí ve vlákně
Odpovíte ve vlákně během hovoruPOST /v1/calls/{call_id}/whisperAgent vaši poznámku obdrží soukromě a podle ní jedná. Druhá osoba ji nikdy neuslyší
Odpovíte na otázku agentaVáš koncový bod nástroje vrátí vaši odpověď nebo ji doručí později pomocí POST /v1/calls/{call_id}/tool-resultsAgent 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ýsledekPřijímá telephony.completeVáš 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).
  • Čí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. 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.

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:

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ů.
  • 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.

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:

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í 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 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:

{"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:

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

Č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á:

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.
  • 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í.

Vytvořte to pomocí programovacího agenta

Nasměrujte svého programovacího agenta na server MCP dokumentace 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.