ThunderPhone v3 er live.Selvbetjening fra 2 cent pr. minut.Læs mere om lanceringen

Developer cookbook

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 chattenDin bot kalderHvad der sker
Send "Ring til Comcast og få forventet tid for udbedring af driftsforstyrrelsen"POST /v1/call med beskeden som contextAgenten ringer op. Din bot åbner en tråd til opkaldet
Følg trådenModtager telephony.turn-webhooksHver linje, som agenten eller den anden person siger, vises i tråden
Svar i tråden midt i opkaldetPOST /v1/calls/{call_id}/whisperAgenten modtager din note privat og handler på den. Den anden person hører den aldrig
Besvar agentens spørgsmålDit værktøjsendepunkt returnerer dit svar eller leverer det senere med POST /v1/calls/{call_id}/tool-resultsAgenten fortsætter opkaldet med det; i ventetilstand hører den anden person ventemusik imens
Læs resultatetModtager telephony.completeDin 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 context pr. 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.turn og telephony.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, og summary ved 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 efter position. 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.turn sker 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.