ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Developer cookbook

Pokrećite pozive iz Slaka ili aplikacije za chat

Izradite vlastitog bota za Slack, Teams ili web-chat koji pokreće pozive, prati ih uživo, usmjerava agenta i odgovara na njegova pitanja putem javnog API-ja.

Glasovnim agentom možete upravljati iz aplikacije za chat koju vaš tim već koristi. Poruka pokreće poziv. Poziv se odvija uživo u niti. Odgovor u niti usmjerava agenta. Kada agent treba odluku, ondje vas pita i čeka vaš odgovor.

ThunderPhone ne hosta ovaj bot umjesto vas. Vi (ili vaš agent za programiranje) izrađujete mali poslužitelj koji povezuje vašu aplikaciju za chat s javnim API-jem. Ova stranica prikazuje dijelove. Isti su za Slack, Microsoft Teams, Discord ili privatnu web-stranicu za chat; primjeri koriste Slack.

Kako se sve povezuje

Što radite u chatuŠto vaš bot pozivaŠto se događa
Pošaljite "Nazovite Comcast i saznajte procijenjeno vrijeme otklanjanja kvara"POST /v1/call s porukom kao contextAgent bira broj. Vaš bot otvara nit za poziv
Pratite nitPrima webhookove telephony.turnSvaka rečenica koju agent ili druga osoba izgovori pojavljuje se u niti
Odgovorite u niti usred pozivaPOST /v1/calls/{call_id}/whisperAgent privatno prima vašu bilješku i postupa prema njoj. Druga osoba je nikada ne čuje
Odgovorite na pitanje agentaVaša krajnja točka alata vraća vaš odgovor ili ga kasnije isporučuje pomoću POST /v1/calls/{call_id}/tool-resultsAgent nastavlja poziv s njime; u načinu čekanja druga osoba u međuvremenu čuje glazbu čekanja
Pročitajte rezultatPrima webhookove telephony.completeVaš bot objavljuje sažetak i ishod

Vaš bot održava jedno mapiranje: koja nit chata pripada kojem call_id.

Prije početka

  • API ključ, pohranjen na vašem poslužitelju, nikada u pregledniku ili chatu. Izradite ga u odjeljku Postavke organizacije → Ključevi (pogledajte Ključevi).
  • Broj s omogućenim odlaznim pozivima i agent za pozive. Poruka postaje context po pozivu, pa jedan opći agent obrađuje svaki zadatak.
  • Poslužitelj koji može primati webhookove, kao što su Railway, Fly.io, Render ili vaš vlastiti host.
  • Krajnja točka webhoka koja upućuje na taj poslužitelj i pretplaćena je na telephony.turn i telephony.complete. Događaji promjene šalju se samo na krajnje točke koje ih navode. Pogledajte Webhookovi. Za događaje promjene potrebno je uključeno snimanje poziva agenta, a za summary na kraju poziva potrebna je postavka agenta Generiraj sažetak poziva; bez njih ta polja ostaju prazna.
  • Vaša vlastita aplikacija za chat. Za Slack izradite aplikaciju u svom radnom prostoru na api.slack.com/apps.

1. Pokrenite poziv iz poruke

Kada Vaš bot primi poruku (izravnu poruku ili @spominjanje), odmah potvrdite Slackov zahtjev (Slack ponovno pokušava sve što nije potvrđeno u roku od 3 sekunde), a ostatak obradite u pozadini. Provjerite je li pošiljatelj ovlašten upućivati pozive, a zatim pokrenite poziv s porukom kao 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"
  }'

Spremite vraćeni call_id uz Slack nit (channel i ts poruke) te odgovorite u niti („Pozivam…“). Izgradite idempotency_key iz kanala i ts poruke (ts je jedinstven samo unutar svojeg kanala) kako ponovljeni Slack događaj ne bi pokrenuo drugi poziv. Ako je u zahtjevu navedena osoba umjesto broja, Vaš bot najprije pronalazi broj. ThunderPhone bira samo to_number koji pošaljete.

2. Pratite poziv u niti

Svaki webhook telephony.turn sadrži call_id, govornika (role: assistant za agenta, user za drugu osobu), text i position poteza. Pronađite nit prema call_id i objavite redak.

  • Provjerite svaki webhook prije postupanja prema njemu. Pogledajte Provjera potpisa webhookova.
  • Uklonite duplikate prema event_id omotnice i poredajte prema position. Isporuka se obavlja najmanje jednom, a potezi mogu stići neispravnim redoslijedom.
  • Grupirajte retke ako bi aktivan poziv preplavio nit; objava svakih nekoliko sekundi čitljivija je od jedne poruke po retku.

Kada stigne telephony.complete, objavite način završetka poziva (njegove status i end_reason), summary i sve izdvojene podatke te zaključite nit. Polja potražite u odjeljku Završetak poziva.

3. Usmjeravajte poziv iz niti

Kada netko odgovori u niti aktivnog poziva, pošaljite odgovor kao šapat, osim ako agent čeka odgovor na pitanje (korak 4), u kojem je slučaju odgovor ujedno i odgovor na pitanje:

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 ga čuje privatno i uključuje u svoj sljedeći potez; druga osoba nikada ne čuje sam šapat. Šapat ima od 1 do 1000 znakova. Kod 409 znači da poziv više nije aktivan: obavijestite nit da je poziv završio.

4. Neka vam agent postavi pitanje

Dajte agentu alat, na primjer ask_owner s jednim parametrom question, koji poziva vaš poslužitelj. Izradite ga kao API vezu i povežite ga s agentom. Svaki zahtjev alata prenosi poziv u zaglavlju X-ThunderPhone-Call-ID.

Postoje tri načina za dobivanje odgovora.

Zadržite poziv (do 10 minuta). Postavite alat u način zadržavanja: spec.wait_mode "hold" i spec.timeout do 600 sekundi (bez vremenskog ograničenja zadržavanje traje 20 sekundi), putem API-ja (uređivač na nadzornoj ploči još nema nijedno od tih polja). Vaša krajnja točka objavljuje pitanje u niti poziva i odmah odgovara rezultatom na čekanju:

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

Sugovornik čuje jednu rečenicu agenta, a zatim glazbu tijekom zadržavanja. U telefonskom izborniku ili govornoj pošti agent umjesto toga koristi govorne obavijesti, a dvosmjerni agent ne zadržava poziv: odgovor na čekanju dobiva kao rezultat. Kada odgovor stigne u nit, isporučite ga putem 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."}}'

Glazba postupno stišava zvuk, a agent nastavlja s vašim odgovorom. Ako nitko ne odgovori prije timeout, agentu se javlja da odgovor nije stigao te sugovorniku nudi sljedeće korake. Dok je pitanje na čekanju za poziv, sljedeći odgovor u njegovoj niti odgovara na njega: isporučite ga kao rezultat alata i nemojte ga dodatno slati kao šapat (šapat stiže do agenta tek nakon povratka alata). Pogledajte Duga čekanja.

Pričekajte u zahtjevu (do 3 minute). Vaša krajnja točka objavljuje pitanje, čeka odgovor i vraća ga, primjerice {"answer": "Yes, book Tuesday at 10."}. Putem API-ja postavite spec.timeout alata na najviše 180 sekundi (zadana vrijednost je 20). Svojoj krajnjoj točki zadajte vlastiti rok nekoliko sekundi kraći (na primjer 170 sekundi), tako da, kada nitko ne odgovori, i dalje vrati nešto na temelju čega agent može postupiti, primjerice {"answer": null, "note": "No reply yet. Offer to take a message."}. Alat koji dosegne svoj timeout stiže do agenta kao pogreška, a vaš poslužitelj mora toliko dugo držati zahtjev otvorenim. Dok čeka, agent sugovorniku kaže da provjerava, nakon otprilike 12 sekundi kaže da još radi, a zatim daje kratku obavijest otprilike svakih 15 sekundi. Način zadržavanja ovdje također funkcionira: postavite spec.wait_mode na "hold" i sugovornik čuje glazbu umjesto obavijesti.

Odgovorite šaptom. Vaša krajnja točka objavljuje pitanje i odmah vraća odgovor, primjerice {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Kada odgovor stigne, pošaljite ga kao šapat (korak 3), a agent na njega odmah odgovara. Upotrijebite ovo za odgovore koji mogu trajati dulje od 10 minuta. Poziv se ne zadržava: vaš upit treba reći agentu što da radi u međuvremenu, primjerice da pravi društvo sugovorniku ili ponudi da mu uzvrati poziv.

U svakom slučaju navedite u upitu agenta kada treba upotrijebiti alat i što treba reći sugovorniku dok čeka:

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.

Ograničenja koja trebate uzeti u obzir

  • Vaša krajnja točka mora odgovoriti unutar timeout alata, najviše 180 sekundi. Alat u načinu čekanja može zadržati poziv na čekanju do 600 sekundi uz rezultat na čekanju.
  • Dok alat čeka, agent ne odgovara drugoj osobi. U načinu čekanja osoba čuje glazbu; u suprotnom, kratka govorna ažuriranja.
  • Šapat ima najviše 1000 znakova.
  • Isporuka telephony.turn događa se najmanje jednom i može biti izvan redoslijeda.

Sigurnosni popis za provjeru

  • API ključ zadržite na svom poslužitelju.
  • Provjerite ThunderPhone potpise na webhookovima i zahtjevima alata te Slackovu tajnu za potpisivanje na Slackovim zahtjevima. Dva ThunderPhone potpisa koriste različite tajne: isporuke webhookova koriste vlastitu tajnu krajnje točke webhooka, a zahtjevi alata koriste tajnu webhooka vaše organizacije iz GET /v1/webhook.
  • Odlučite tko smije pokretati pozive: provjerite Slack korisnički ID prije upućivanja poziva.
  • Odlazni pozivi slijede ista pravila kao i svi ostali. Pogledajte Zakoni o odlaznim pozivima.

Izradite uz pomoć agenta za kodiranje

Usmjerite svog agenta za kodiranje na MCP poslužitelj dokumentacije i na ovu stranicu te zatražite „Slack bota za moj ThunderPhone agent koji slijedi ovaj vodič”. Zeus, pomoćnik u aplikaciji ThunderPhone, može postaviti stranu agenta (krajnju točku webhooka, alat i retke upita) te napisati početni kod za bota u chatu.