ThunderPhone v3 este disponibil.Self-service, de la 2 ¢/min.Citiți anunțul

Developer cookbook

Efectuați apeluri din Slack sau dintr-o aplicație de chat

Creați propriul bot pentru Slack, Teams sau chat web care inițiază apeluri, le urmărește în timp real, ghidează agentul vocal și răspunde la întrebările acestuia, folosind API-ul public.

Puteți controla un agent vocal din aplicația de chat pe care echipa dumneavoastră o folosește deja. Un mesaj inițiază un apel. Apelul se desfășoară în direct într-un fir de discuție. Un răspuns în firul de discuție direcționează agentul vocal. Când agentul vocal are nevoie de o decizie, vă întreabă acolo și așteaptă răspunsul dumneavoastră.

ThunderPhone nu găzduiește acest bot pentru dumneavoastră. Dumneavoastră (sau agentul dumneavoastră de programare) creați un server mic care conectează aplicația de chat la API-ul public. Această pagină prezintă componentele. Sunt aceleași pentru Slack, Microsoft Teams, Discord sau o pagină web de chat privată; exemplele folosesc Slack.

Cum se integrează

Faceți aceasta în chatBotul dumneavoastră apeleazăCe se întâmplă
Trimiteți „Sunați Comcast și aflați ora estimată pentru remedierea întreruperii”POST /v1/call cu mesajul ca contextAgentul vocal apelează. Botul dumneavoastră deschide un fir de discuție pentru apel
Urmăriți firul de discuțiePrimește webhook-uri telephony.turnFiecare replică rostită de agentul vocal sau de cealaltă persoană apare în firul de discuție
Răspundeți în firul de discuție în timpul apeluluiPOST /v1/calls/{call_id}/whisperAgentul vocal primește nota dumneavoastră în mod privat și acționează în consecință. Cealaltă persoană nu o aude niciodată
Răspundeți la întrebarea agentului vocalEndpointul dumneavoastră de instrument returnează răspunsul sau îl livrează ulterior cu POST /v1/calls/{call_id}/tool-resultsAgentul vocal continuă apelul cu acesta; în modul de așteptare, cealaltă persoană aude între timp muzică de așteptare
Citiți rezultatulPrimește telephony.completeBotul dumneavoastră publică rezumatul și rezultatul

Botul dumneavoastră păstrează o singură asociere: ce fir de discuție din chat aparține cărui call_id.

Înainte de a începe

  • O cheie API, păstrată pe serverul dumneavoastră și niciodată într-un browser sau în chat. Creați una în Integrations → API keys (consultați Crearea unei chei API de server).
  • Un număr cu apeluri efectuate activate și un agent vocal pentru apeluri. Mesajul devine context pentru fiecare apel, astfel încât un singur agent vocal general gestionează fiecare sarcină.
  • Un server care poate primi webhookuri, precum Railway, Fly.io, Render sau propriul dumneavoastră host.
  • Un endpoint webhook care indică spre acel server și este abonat la telephony.turn și telephony.complete. Evenimentele de tură sunt trimise doar către endpointurile care le listează. Consultați Webhookuri. Evenimentele de tură necesită activarea înregistrării apelurilor agentului vocal, iar summary de la finalul apelului necesită setarea Generate a call summary a agentului vocal; fără acestea, câmpurile respective rămân goale.
  • Propria aplicație de chat. Pentru Slack, creați o aplicație în spațiul dumneavoastră de lucru la api.slack.com/apps.

1. Începeți un apel dintr-un mesaj

Când botul dumneavoastră primește un mesaj (un mesaj direct sau o mențiune @), confirmați imediat solicitarea Slack (Slack reîncearcă orice solicitare care nu este confirmată în 3 secunde) și efectuați restul în fundal. Verificați dacă expeditorul are permisiunea de a iniția apeluri, apoi începeți apelul folosind mesajul drept 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"
  }'

Salvați call_id returnat asociat cu firul Slack (channel plus ts-ul mesajului) și răspundeți în fir („Se apelează…”). Construiți idempotency_key din canal și ts-ul mesajului (un ts este unic numai în canalul său), astfel încât un eveniment Slack reîncercat să nu inițieze un al doilea apel. Dacă solicitarea numește o persoană în locul unui număr, botul dumneavoastră caută mai întâi numărul. ThunderPhone apelează numai to_number pe care îl trimiteți.

2. Urmăriți apelul în fir

Fiecare webhook telephony.turn conține call_id, vorbitorul (role: assistant pentru agent, user pentru cealaltă persoană), text și position al rândului de dialog. Identificați firul după call_id și publicați rândul.

  • Verificați fiecare webhook înainte de a acționa pe baza lui. Consultați Verificarea semnăturilor webhook.
  • Eliminați duplicatele după event_id din plic și ordonați după position. Livrarea are loc cel puțin o dată, iar rândurile de dialog pot sosi în altă ordine.
  • Grupați rândurile dacă un apel aglomerat ar inunda firul; publicarea la fiecare câteva secunde se citește mai bine decât câte un mesaj pentru fiecare rând.

Când sosește telephony.complete, publicați modul în care s-a încheiat apelul (status și end_reason), summary și orice date extrase, apoi închideți firul. Consultați Finalizarea apelului pentru câmpuri.

3. Direcționați apelul din fir

Când cineva răspunde în firul unui apel activ, trimiteți răspunsul ca mesaj șoptit, cu excepția cazului în care agentul așteaptă răspunsul la o întrebare (pasul 4), caz în care răspunsul este chiar răspunsul la întrebare:

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."}'

Agentul îl aude în privat și îl integrează în următorul său rând de dialog; cealaltă persoană nu aude niciodată mesajul șoptit în sine. Un mesaj șoptit are între 1 și 1000 de caractere. Un 409 înseamnă că apelul nu mai este activ: comunicați în fir că apelul s-a încheiat.

4. Permiteți agentului să vă întrebe

Oferiți agentului un instrument, de exemplu ask_owner, cu un parametru question, care apelează serverul dvs. Creați-l ca o conexiune API și conectați-l la agent. Fiecare solicitare de instrument include apelul în antetul său X-ThunderPhone-Call-ID.

Există trei modalități de a primi răspunsul înapoi.

Mențineți apelul în așteptare (până la 10 minute). Setați instrumentul în modul de așteptare: spec.wait_mode "hold" și spec.timeout la maximum 600 de secunde (fără un timeout, o așteptare durează 20 de secunde), prin API sau cereți-i lui Zeus să le seteze (editorii aplicației nu au încă niciunul dintre câmpuri). Endpointul dumneavoastră publică întrebarea în firul apelului și răspunde imediat cu un rezultat în așteptare:

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

Cealaltă persoană aude o replică de la agent, apoi muzică de așteptare. Într-un meniu telefonic sau în mesageria vocală, agentul folosește în schimb actualizări rostite, iar un agent full-duplex nu pune apelul în așteptare: primește răspunsul în așteptare ca rezultat. Când răspunsul ajunge în fir, transmiteți-l cu 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."}}'

Muzica se estompează, iar agentul continuă cu răspunsul dvs. Dacă nimeni nu răspunde înainte de timeout, agentul este informat că nu a venit niciun răspuns și îi oferă celeilalte persoane pașii următori. Cât timp o întrebare este în așteptare pentru un apel, următorul răspuns din firul său îi răspunde: transmiteți-l ca rezultat al instrumentului și nu îl trimiteți și ca șoaptă (o șoaptă ajunge la agent numai după ce instrumentul revine). Consultați Așteptări lungi.

Așteptați în solicitare (până la 3 minute). Endpointul dvs. publică întrebarea, așteaptă un răspuns și îl returnează, de exemplu {"answer": "Yes, book Tuesday at 10."}. Setați spec.timeout al instrumentului prin API, până la 180 de secunde (valoarea implicită este 20). Oferiți endpointului dvs. propriul termen-limită cu câteva secunde mai scurt (de exemplu, 170 de secunde), astfel încât, atunci când nimeni nu răspunde, să returneze totuși ceva asupra căruia agentul poate acționa, de exemplu {"answer": null, "note": "No reply yet. Offer to take a message."}. Un instrument care atinge timeout ajunge la agent ca eroare, iar gazda dvs. trebuie să mențină o solicitare deschisă atât timp. În timp ce așteaptă, agentul îi spune celeilalte persoane că verifică, spune că încă lucrează după aproximativ 12 secunde, apoi oferă o actualizare scurtă aproximativ la fiecare 15 secunde. Modul de așteptare funcționează și aici: setați spec.wait_mode la "hold", iar cealaltă persoană aude muzică în locul actualizărilor.

Răspundeți prin șoaptă. Endpointul dvs. publică întrebarea și revine imediat, de exemplu {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Când sosește răspunsul, trimiteți-l ca șoaptă (pasul 3), iar agentul răspunde imediat la acesta. Folosiți această opțiune pentru răspunsuri care pot dura mai mult de 10 minute. Apelul nu este pus în așteptare: promptul dvs. ar trebui să îi spună agentului ce să facă între timp, de exemplu să țină companie persoanei sau să ofere să o sune înapoi.

În fiecare caz, precizați în promptul agentului când să folosească instrumentul și ce să îi spună celeilalte persoane cât timp așteaptă:

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.

Limite de avut în vedere

  • Endpointul dumneavoastră trebuie să răspundă în timeout al instrumentului, în cel mult 180 de secunde. Un instrument în modul de așteptare poate menține apelul în așteptare până la 600 de secunde cu un rezultat în curs.
  • Cât timp un instrument așteaptă, agentul nu răspunde celeilalte persoane. În modul de așteptare, aceasta aude muzică; în caz contrar, actualizări vocale scurte.
  • O șoaptă are cel mult 1000 de caractere.
  • Livrarea telephony.turn are loc cel puțin o dată și poate fi în altă ordine.

Listă de verificare pentru securitate

  • Păstrați cheia API pe serverul dumneavoastră.
  • Verificați semnăturile ThunderPhone pentru webhookuri și solicitările de instrumente, precum și secretul de semnare Slack pentru solicitările Slack. Cele două semnături ThunderPhone folosesc secrete diferite: livrările prin webhook folosesc secretul propriu al endpointului webhook, iar solicitările de instrumente folosesc secretul webhook al organizației dumneavoastră din GET /v1/webhook.
  • Decideți cine poate iniția apeluri: verificați ID-ul utilizatorului Slack înainte de a plasa un apel.
  • Apelurile efectuate respectă aceleași reguli ca oricare altele. Consultați Legile privind apelurile efectuate.

Construiți-l cu un agent de programare

Indicați agentului dumneavoastră de programare serverul MCP pentru documentație și această pagină și solicitați „un bot Slack pentru agentul meu ThunderPhone care urmează acest ghid”. Zeus, asistentul din aplicația ThunderPhone, poate configura partea agentului vocal (endpointul webhook, instrumentul și liniile de prompt) și poate scrie cod inițial pentru bot în chat.