Open in
Kør opkald fra Slack eller en chatapp
Byg din egen Slack-, Teams- eller webchatbot, der starter opkald, følger dem live, styrer agenten og besvarer dens spørgsmål ved hjælp af det offentlige API.
Du kan styre en agent fra den chatapp, dit team allerede bruger. En besked starter et opkald. Opkaldet udfolder sig live i en tråd. Et svar i tråden styrer agenten. Når agenten har brug for en beslutning, spørger den dig der og venter på dit svar.
ThunderPhone hoster ikke denne bot for dig. Du (eller din kodningsagent) bygger en lille server, der forbinder din chatapp med det offentlige API. Denne side viser delene. De er de samme for Slack, Microsoft Teams, Discord eller en privat webchatside; eksemplerne bruger Slack.
Sådan hænger det sammen
| Du gør dette i chatten | Din bot kalder | Hvad der sker |
|---|---|---|
| Send "Ring til Comcast og få forventet tid for udbedring af driftsforstyrrelsen" | POST /v1/call med beskeden som context | Agenten ringer op. Din bot åbner en tråd til opkaldet |
| Følg tråden | Modtager telephony.turn-webhooks | Hver linje, som agenten eller den anden person siger, vises i tråden |
| Svar i tråden midt i opkaldet | POST /v1/calls/{call_id}/whisper | Agenten modtager din note privat og handler på den. Den anden person hører den aldrig |
| Besvar agentens spørgsmål | Dit værktøjsendepunkt returnerer dit svar eller leverer det senere med POST /v1/calls/{call_id}/tool-results | Agenten fortsætter opkaldet med det; i ventetilstand hører den anden person ventemusik imens |
| Læs resultatet | Modtager telephony.complete | Din bot sender oversigten og resultatet |
Din bot gemmer én tilknytning: hvilken chattråd der hører til hvilket call_id.
Før du starter
- En API-nøgle, der opbevares på din server og aldrig i en browser eller chat. Opret en under Integrationer → API-nøgler (se Opret en API-nøgle til serveren).
- Et nummer med udgående opkald og en agent til opkaldene. Beskeden
bliver til
contextpr. opkald, så én generel agent håndterer alle opgaver. - En server, der kan modtage webhooks, f.eks. Railway, Fly.io, Render eller din egen host.
- Et webhook-endpoint, der peger på den server og abonnerer på
telephony.turnogtelephony.complete. Turn-hændelser sendes kun til endpoints, der angiver dem. Se Webhooks. Turn-hændelser kræver, at agentens opkaldsoptagelse er slået til, ogsummaryved opkaldets afslutning kræver agentens indstilling Generer en opkaldsoversigt; uden dem forbliver disse felter tomme. - Din egen chat-app. Til Slack skal du oprette en app i dit arbejdsområde på api.slack.com/apps.
1. Start et opkald fra en besked
Når din bot modtager en besked (en direkte besked eller en @omtale),
skal du straks kvittere for Slacks anmodning (Slack forsøger igen med alt,
der ikke er kvitteret for inden for 3 sekunder), og gøre resten i
baggrunden. Kontrollér, at afsenderen har tilladelse til at foretage opkald,
og start derefter opkaldet med beskeden som 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"
}'Gem det returnerede call_id sammen med Slack-tråden (channel plus
beskedens ts), og svar i tråden ("Ringer..."). Byg
idempotency_key ud fra kanalen og beskedens ts (en ts er kun entydig
i sin egen kanal), så en Slack-hændelse, der forsøges igen, ikke foretager
et andet opkald. Hvis anmodningen angiver en person frem for et nummer,
slår din bot først nummeret op. ThunderPhone ringer kun til det to_number,
du sender.
2. Følg opkaldet i tråden
Hver telephony.turn-webhook indeholder call_id, taleren (role:
assistant for agenten, user for den anden person), text og
turens position. Slå tråden op via call_id, og
send linjen.
- Bekræft hver webhook før du handler på den. Se Bekræft webhook-signaturer.
- Deduplicér på konvoluttens
event_id, og sortér efterposition. Levering sker mindst én gang, og ture kan ankomme i forkert rækkefølge. - Saml linjer i grupper, hvis et travlt opkald ville oversvømme tråden; det er lettere at læse at sende med få sekunders mellemrum end én besked pr. linje.
Når telephony.complete ankommer, skal du sende, hvordan opkaldet sluttede
(dets status og end_reason), summary og eventuelle udtrukne data, og
afslutte tråden. Se Opkald fuldført for felterne.
3. Styr opkaldet fra tråden
Når nogen svarer i et igangværende opkalds tråd, skal du sende svaret som en hvisken, medmindre agenten venter på et spørgsmål (trin 4), hvor svaret i så fald er svaret på spørgsmålet:
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."}'Agenten hører det privat og indarbejder det i sin næste tur; den anden
person hører aldrig selve hviskningen. En hvisken er på 1 til 1000 tegn. En
409 betyder, at opkaldet ikke længere er igangværende: fortæl tråden, at
opkaldet er afsluttet.
4. Lad agenten spørge dig
Giv agenten et værktøj, for eksempel ask_owner med én question-
parameter, der kalder din server. Opret det som en
API-forbindelse, og knyt det til agenten.
Hver værktøjsanmodning indeholder opkaldet i dens X-ThunderPhone-Call-ID-header.
Der er tre måder at få svaret tilbage på.
Sæt opkaldet på pause (op til 10 minutter). Indstil værktøjet til ventetilstand: spec.wait_mode
"hold" og spec.timeout til op til 600 sekunder (uden en timeout varer en pause
20 sekunder) via
API'et, eller bed Zeus om at
indstille dem (appens redigeringsvisninger har endnu ingen af felterne). Dit endpoint sender spørgsmålet til opkaldets tråd og svarer straks
med et afventende resultat:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Den anden person hører én sætning fra agenten og derefter ventemusik. I en
telefonmenu eller på en telefonsvarer bruger agenten i stedet mundtlige opdateringer, og en
fuld-dupleksagent sætter ikke på hold: den modtager det afventende svar som resultat. Når
svaret kommer i tråden, skal du levere det med
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."}}'Musikken toner ud, og agenten fortsætter med dit svar. Hvis ingen
svarer før timeout, får agenten besked om, at der ikke kom et svar, og tilbyder
den anden person næste skridt. Mens et spørgsmål afventer for et opkald, besvarer
det næste svar i tråden det: lever det som værktøjsresultatet, og
send det ikke også som en hvisken (en hvisken når kun agenten, efter
værktøjet returnerer). Se
Lange ventetider.
Vent i anmodningen (op til 3 minutter). Dit endepunkt sender spørgsmålet,
venter på et svar og returnerer det, for eksempel {"answer": "Yes, book Tuesday at 10."}.
Indstil værktøjets spec.timeout via API'et, op til 180 sekunder (standarden
er 20). Giv dit endepunkt sin egen frist, der er nogle sekunder kortere
(for eksempel 170 sekunder), så det stadig returnerer noget, agenten kan handle på,
når ingen svarer, for eksempel
{"answer": null, "note": "No reply yet. Offer to take a message."}. Et værktøj,
der rammer sin timeout, når agenten som en fejl, og din host skal
holde en anmodning åben så længe. Mens det venter, fortæller agenten den anden
person, at den undersøger det, siger efter cirka 12 sekunder, at den stadig arbejder på det,
og giver derefter en kort opdatering cirka hvert 15. sekund. Holdtilstand fungerer
også her: indstil spec.wait_mode til "hold", så hører den anden person musik
i stedet for opdateringerne.
Svar med en hvisken. Dit endepunkt sender spørgsmålet og returnerer straks,
for eksempel {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Når svaret kommer, skal du sende det som en hvisken (trin 3), og agenten
svarer straks på det. Brug dette til svar, der kan tage længere tid end
10 minutter. Opkaldet sættes ikke på hold: din prompt bør fortælle
agenten, hvad den skal gøre imens, for eksempel holde den anden person med selskab eller tilbyde
at ringe tilbage.
I alle tilfælde skal du angive i agentens prompt, hvornår værktøjet skal bruges, og hvad den skal fortælle den anden person, mens den venter:
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.Grænser, du skal planlægge efter
- Dit endepunkt skal svare inden for værktøjets
timeout, højst 180 sekunder. Et værktøj i venteposition kan sætte opkaldet på hold i op til 600 sekunder med et afventende resultat. - Mens et værktøj venter, svarer agenten ikke den anden person. I venteposition hører de musik; ellers korte talte opdateringer.
- En hvisken er højst 1000 tegn.
- Levering af
telephony.turnsker mindst én gang og kan komme i forkert rækkefølge.
Sikkerhedstjekliste
- Opbevar API-nøglen på din server.
- Bekræft ThunderPhones signaturer på webhooks og værktøjsanmodninger samt
Slacks signeringshemmelighed på Slacks anmodninger. De to ThunderPhone-
signaturer bruger forskellige hemmeligheder: webhook-leveringer bruger
webhook-endepunktets egen hemmelighed, og værktøjsanmodninger bruger din
organisations webhook-hemmelighed fra
GET /v1/webhook. - Beslut, hvem der må starte opkald: Kontrollér Slack-bruger-id'et, før du placerer et.
- Udgående opkald følger de samme regler som alle andre. Se Love for udgående opkald.
Byg det med en kodeagent
Lad din kodeagent bruge docs MCP-serveren og denne side, og bed om "en Slack-bot til min ThunderPhone-agent, der følger denne vejledning". Zeus, assistenten i ThunderPhone-appen, kan opsætte agentsiden (webhook-endepunktet, værktøjet og promptlinjerne) og skrive startkode til botten i chatten.