ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Developer cookbook

Spúšťajte hovory zo Slacku alebo chatovacej aplikácie

Vytvorte si vlastného bota pre Slack, Teams alebo webový chat, ktorý spúšťa hovory, sleduje ich naživo, usmerňuje agenta a odpovedá na jeho otázky pomocou verejného API.

V chatovacej aplikácii, ktorú váš tím už používa, môžete ovládať agenta. Správa spustí hovor. Hovor prebieha naživo vo vlákne. Odpoveď vo vlákne usmerní agenta. Keď agent potrebuje rozhodnutie, opýta sa vás tam a počka na vašu odpoveď.

ThunderPhone tento bot za vás neprevádzkuje. Vy (alebo váš agent na programovanie) vytvoríte malý server, ktorý prepojí vašu chatovaciu aplikáciu s verejným API. Táto stránka zobrazuje jednotlivé časti. Sú rovnaké pre Slack, Microsoft Teams, Discord alebo súkromnú webovú chatovaciu stránku; príklady používajú Slack.

Ako to funguje spolu

Vy urobíte v chate totoVáš bot zavoláČo sa stane
Pošlete „Zavolaj Comcastu a zisti odhad času odstránenia výpadku“POST /v1/call so správou ako contextAgent vytočí číslo. Váš bot otvorí vlákno pre hovor
Sledujete vláknoPrijíma webhooky telephony.turnKaždý riadok, ktorý povie agent alebo druhá osoba, sa zobrazí vo vlákne
Odpoviete vo vlákne počas hovoruPOST /v1/calls/{call_id}/whisperAgent dostane vašu poznámku súkromne a vykoná ju. Druhá osoba ju nikdy nepočuje
Odpoviete na otázku agentaVáš koncový bod nástroja vráti vašu odpoveď alebo ju doručí neskôr prostredníctvom POST /v1/calls/{call_id}/tool-resultsAgent s ňou pokračuje v hovore; v režime čakania druhá osoba medzitým počuje hudbu počas čakania
Prečítate si výsledokPrijíma telephony.completeVáš bot zverejní súhrn a výsledok

Váš bot uchováva jedno mapovanie: ktoré chatové vlákno patrí ku ktorému call_id.

Skôr než začnete

  • Kľúč API, uložený na vašom serveri, nikdy nie v prehliadači ani v chate. Vytvorte ho v časti Nastavenia organizácie → Kľúče (pozrite si Kľúče).
  • Číslo s povolenými odchádzajúcimi hovormi a agent pre hovory. Správa sa stane context pre konkrétny hovor, takže jeden všeobecný agent spracuje každú úlohu.
  • Server, ktorý môže prijímať webhooky, napríklad Railway, Fly.io, Render alebo váš vlastný hostiteľ.
  • Koncový bod webhooku smerujúci na tento server a prihlásený na odber telephony.turn a telephony.complete. Udalosti turn sa odosielajú iba na koncové body, ktoré ich uvádzajú. Pozrite si Webhooky. Udalosti turn vyžadujú zapnuté nahrávanie hovorov agenta a summary na konci hovoru vyžaduje nastavenie agenta Generovať súhrn hovoru; bez nich zostanú tieto polia prázdne.
  • Vaša vlastná chatovacia aplikácia. Pre Slack vytvorte aplikáciu vo svojom pracovnom priestore na api.slack.com/apps.

1. Spustite hovor zo správy

Keď váš bot prijme správu (priamu správu alebo @zmienku), okamžite potvrďte požiadavku Slacku (Slack opakuje všetko, čo nie je potvrdené do 3 sekúnd), a zvyšok spracujte na pozadí. Overte, že odosielateľ je oprávnený uskutočňovať hovory, potom spustite hovor so správou ako 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átené call_id k vláknu Slacku (channel spolu s ts správy) a odpovedzte vo vlákne („Volám…“). Vytvorte idempotency_key z kanála a ts správy (ts je jedinečné iba v rámci svojho kanála), aby opakovaná udalosť Slacku nespustila druhý hovor. Ak požiadavka uvádza osobu namiesto čísla, váš bot najprv vyhľadá jej číslo. ThunderPhone vytáča iba to_number, ktoré odošlete.

2. Sledujte hovor vo vlákne

Každý webhook telephony.turn obsahuje call_id, hovoriaceho (role: assistant pre agenta, user pre druhú osobu), text a position ťahu. Vyhľadajte vlákno podľa call_id a odošlite riadok.

  • Overte každý webhook pred spracovaním. Pozrite si Overenie podpisov webhookov.
  • Odstraňujte duplicity podľa event_id obálky a zoraďte podľa position. Doručenie prebieha aspoň raz a ťahy môžu prísť v nesprávnom poradí.
  • Zoskupujte riadky, ak by rušný hovor zahltil vlákno; odosielanie každých niekoľko sekúnd sa číta lepšie než jedna správa na riadok.

Keď príde telephony.complete, odošlite spôsob ukončenia hovoru (jeho status a end_reason), summary a všetky extrahované údaje, potom vlákno uzavrite. Polia nájdete v časti Dokončenie hovoru.

3. Usmerňujte hovor z vlákna

Keď niekto odpovie vo vlákne aktívneho hovoru, odošlite odpoveď ako šepot, pokiaľ agent nečaká na odpoveď na otázku (krok 4); v takom prípade je odpoveď odpoveďou na otázku:

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 ho počuje súkromne a zapracuje ho do svojho nasledujúceho ťahu; druhá osoba samotný šepot nikdy nepočuje. Šepot má 1 až 1000 znakov. Kód 409 znamená, že hovor už nie je aktívny: oznámte vo vlákne, že hovor sa skončil.

4. Nechajte agenta opýtať sa vás

Poskytnite agentovi nástroj, napríklad ask_owner s jedným parametrom question, ktorý volá váš server. Vytvorte ho ako pripojenie API a prepojte ho s agentom. Každá požiadavka nástroja obsahuje hovor v hlavičke X-ThunderPhone-Call-ID.

Existujú tri spôsoby, ako získať odpoveď späť.

Podržte hovor (až 10 minút). Nastavte nástroj do režimu podržania: spec.wait_mode "hold" a spec.timeout až na 600 sekúnd (bez časového limitu trvá podržanie 20 sekúnd) prostredníctvom API (editor na ovládacom paneli ešte nemá ani jedno pole). Váš endpoint odošle otázku do vlákna hovoru a ihneď odpovie výsledkom so stavom čakania:

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

Druhá strana počuje jednu vetu od agenta a potom hudbu počas podržania. V telefónnom menu alebo hlasovej schránke agent namiesto toho používa hovorené aktualizácie a agent s plným duplexom hovor nepodrží: odpoveď so stavom čakania dostane ako výsledok. Keď odpoveď dorazí do vlákna, odošlite ju pomocou 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 postupne stíchne a agent pokračuje s vašou odpoveďou. Ak nikto neodpovie pred uplynutím timeout, agent dostane informáciu, že odpoveď neprišla, a ponúkne druhej strane ďalšie kroky. Kým je otázka pre hovor nevybavená, nasledujúca odpoveď v jeho vlákne ju zodpovie: odošlite ju ako výsledok nástroja a neodosielajte ju zároveň ako šepot (šepot sa k agentovi dostane až po vrátení výsledku nástroja). Pozrite si Dlhé čakania.

Počkajte v požiadavke (až 3 minúty). Váš endpoint odošle otázku, počíta na odpoveď a vráti ju, napríklad {"answer": "Yes, book Tuesday at 10."}. Nastavte spec.timeout nástroja prostredníctvom API až na 180 sekúnd (predvolená hodnota je 20). Nastavte vlastný časový limit endpointu o niekoľko sekúnd kratší (napríklad 170 sekúnd), aby pri neodpovedaní stále vrátil niečo, s čím môže agent pracovať, napríklad {"answer": null, "note": "No reply yet. Offer to take a message."}. Nástroj, ktorý dosiahne svoj timeout, sa k agentovi dostane ako chyba a váš hostiteľ musí požiadavku držať otvorenú tak dlho. Kým čaká, agent druhej strane povie, že to overuje, približne po 12 sekundách povie, že na tom stále pracuje, a potom poskytne krátku aktualizáciu približne každých 15 sekúnd. Režim podržania funguje aj tu: nastavte spec.wait_mode na "hold" a druhá strana namiesto aktualizácií počuje hudbu.

Odpovedzte šepotom. Váš endpoint odošle otázku a ihneď sa vráti, napríklad {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Keď odpoveď dorazí, odošlite ju ako šepot (krok 3) a agent na ňu ihneď zareaguje. Použite to pri odpovediach, ktoré môžu trvať dlhšie než 10 minút. Hovor nie je podržaný: vaša výzva by mala agentovi povedať, čo má zatiaľ robiť, napríklad robiť druhej strane spoločnosť alebo ponúknuť, že jej zavoláte späť.

V každom prípade v pokyne agenta uveďte, kedy má nástroj použiť a čo má povedať druhej strane počas čakania:

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, s ktorými treba počítať

  • Váš endpoint musí odpovedať v rámci hodnoty timeout nástroja, najneskôr do 180 sekúnd. Nástroj v režime podržania môže ponechať hovor podržaný až 600 sekúnd s čakajúcim výsledkom.
  • Kým nástroj čaká, agent neodpovedá druhej osobe. V režime podržania počuje hudbu; inak krátke hovorené aktualizácie.
  • Šepot môže mať najviac 1000 znakov.
  • Doručenie telephony.turn prebieha aspoň raz a môže byť mimo poradia.

Bezpečnostný kontrolný zoznam

  • Uchovávajte kľúč API na svojom serveri.
  • Overujte podpisy ThunderPhone vo webhookoch a požiadavkách nástrojov a podpisové tajomstvo Slacku v požiadavkách Slacku. Dva podpisy ThunderPhone používajú odlišné tajomstvá: doručenia webhookov používajú vlastné tajomstvo endpointu webhooku a požiadavky nástrojov používajú tajomstvo webhooku vašej organizácie z GET /v1/webhook.
  • Rozhodnite, kto môže začať hovory: pred uskutočnením hovoru skontrolujte ID používateľa Slacku.
  • Odchádzajúce hovory sa riadia rovnakými pravidlami ako všetky ostatné. Pozrite si Zákony o odchádzajúcich hovoroch.

Vytvorte to pomocou programovacieho agenta

Naveďte svojho programovacieho agenta na server MCP dokumentácie a na túto stránku a požiadajte ho o „Slack bota pre môjho agenta ThunderPhone, ktorý sa riadi týmto návodom“. Zeus, asistent v aplikácii ThunderPhone, môže nastaviť stranu agenta (endpoint webhooku, nástroj a riadky výzvy) a napísať v chate počiatočný kód pre bota.