Open in
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 chat | Botul 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 context | Agentul vocal apelează. Botul dumneavoastră deschide un fir de discuție pentru apel |
| Urmăriți firul de discuție | Primește webhook-uri telephony.turn | Fiecare 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 apelului | POST /v1/calls/{call_id}/whisper | Agentul 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 vocal | Endpointul dumneavoastră de instrument returnează răspunsul sau îl livrează ulterior cu POST /v1/calls/{call_id}/tool-results | Agentul vocal continuă apelul cu acesta; în modul de așteptare, cealaltă persoană aude între timp muzică de așteptare |
| Citiți rezultatul | Primește telephony.complete | Botul 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
contextpentru 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șitelephony.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, iarsummaryde 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_iddin 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
timeoutal 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.turnare 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.