Open in
Esegui chiamate da Slack o da un
Crea il tuo bot per Slack, Teams o chat web che avvia chiamate, le segue in diretta, guida l
Puoi gestire un agente dall'app di chat che il tuo team usa già. Un messaggio avvia una chiamata. La chiamata si svolge in tempo reale in un thread. Una risposta nel thread guida l'agente. Quando l'agente deve prendere una decisione, te lo chiede lì e attende la tua risposta.
ThunderPhone non ospita questo bot per te. Tu (o il tuo agente di programmazione) crei un piccolo server che collega la tua app di chat all'API pubblica. Questa pagina mostra i componenti. Sono gli stessi per Slack, Microsoft Teams, Discord o una pagina di chat web privata; gli esempi usano Slack.
Come funziona
| Cosa fai nella chat | Cosa chiama il tuo bot | Cosa succede |
|---|---|---|
| Invia "Chiama Comcast e ottieni l'orario previsto di ripristino" | POST /v1/call con il messaggio come context | L'agente chiama. Il tuo bot apre un thread per la chiamata |
| Osserva il thread | Riceve webhook telephony.turn | Ogni riga pronunciata dall'agente o dall'altra persona appare nel thread |
| Rispondi nel thread durante la chiamata | POST /v1/calls/{call_id}/whisper | L'agente riceve privatamente la tua nota e agisce di conseguenza. L'altra persona non la sente mai |
| Rispondi alla domanda dell'agente | Il tuo endpoint dello strumento restituisce la tua risposta oppure la invia in seguito con POST /v1/calls/{call_id}/tool-results | L'agente prosegue la chiamata con la risposta; in modalità attesa l'altra persona ascolta musica d'attesa nel frattempo |
| Leggi il risultato | Riceve telephony.complete | Il tuo bot pubblica il riepilogo e l'esito |
Il tuo bot mantiene una mappatura: quale thread di chat appartiene a quale call_id.
Prima di iniziare
- Una chiave API, conservata sul tuo server e mai in un browser o in chat. Creane una in Integrazioni → Chiavi API (vedi Crea una chiave API del server).
- Un numero abilitato alle chiamate in uscita e un agente per le chiamate. Il messaggio
diventa
contextper chiamata, quindi un unico agente generico gestisce ogni attività. - Un server in grado di ricevere webhook, come Railway, Fly.io, Render o il tuo host.
- Un endpoint webhook che punta a quel server e sottoscritto a
telephony.turnetelephony.complete. Gli eventi di turno vengono inviati solo agli endpoint che li elencano. Vedi Webhook. Gli eventi di turno richiedono la registrazione delle chiamate dell'agente attivata e ilsummarydi fine chiamata richiede l'impostazione Genera un riepilogo della chiamata dell'agente; senza queste impostazioni, quei campi restano vuoti. - La tua app di chat. Per Slack, crea un'app nel tuo workspace su api.slack.com/apps.
1. Avvia una chiamata da un messaggio
Quando il tuo bot riceve un messaggio (un messaggio diretto o una @menzione),
conferma subito la richiesta di Slack (Slack ritenta tutto ciò che non viene
confermato entro 3 secondi) e svolgi il resto in background. Verifica
che il mittente sia autorizzato a effettuare chiamate, quindi avvia la chiamata con il
messaggio come 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 il call_id restituito associandolo al thread Slack (channel più il
ts del messaggio) e rispondi nel thread ("Chiamata in corso…"). Crea la
idempotency_key dal canale e dal ts del messaggio (un ts è univoco
solo all'interno del suo canale), in modo che un evento Slack ritentato non avvii una seconda
chiamata. Se la richiesta indica una persona anziché un numero, il tuo bot
cerca prima il numero. ThunderPhone compone solo il to_number che invii.
2. Segui la chiamata nel thread
Ogni webhook telephony.turn contiene il call_id, l'interlocutore (role:
assistant per l'agente, user per l'altra persona), il text e la
position del turno. Cerca il thread tramite call_id e
pubblica la riga.
- Verifica ogni webhook prima di agire. Consulta Verifica le firme dei webhook.
- Elimina i duplicati usando l'
event_iddell'envelope e ordina perposition. La consegna avviene almeno una volta e i turni possono arrivare fuori ordine. - Raggruppa le righe se una chiamata intensa riempirebbe il thread; pubblicare ogni pochi secondi è più leggibile di un messaggio per riga.
Quando arriva telephony.complete, pubblica come si è conclusa la chiamata (il relativo status
e end_reason), il summary e tutti i dati estratti, quindi chiudi il
thread. Consulta Completamento chiamata per i campi.
3. Guida la chiamata dal thread
Quando qualcuno risponde nel thread di una chiamata in corso, invia la risposta come sussurro, a meno che l'agente non stia aspettando una risposta a una domanda (passaggio 4), nel qual caso la risposta è la risposta alla domanda:
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."}'L'agente lo sente privatamente e lo integra nel turno successivo; l'altra
persona non sente mai il sussurro stesso. Un sussurro è composto da 1 a 1000 caratteri. Un
409 significa che la chiamata non è più in corso: comunica al thread che la chiamata è terminata.
4. Lascia che l'agente ti faccia domande
Fornisci all'agente uno strumento, ad esempio ask_owner con un parametro
question, che chiama il tuo server. Crealo come
connessione API e collegalo all'agente.
Ogni richiesta dello strumento include la chiamata nell'header X-ThunderPhone-Call-ID.
Esistono tre modi per ricevere la risposta.
Metti la chiamata in attesa (fino a 10 minuti). Imposta lo strumento in modalità di attesa: spec.wait_mode
"hold" e spec.timeout fino a 600 secondi (senza timeout, un'attesa
dura 20 secondi), tramite l'API oppure chiedi a Zeus di
impostarli (gli editor dell'app non dispongono ancora di nessuno dei due campi). Il tuo endpoint pubblica la domanda nel thread della chiamata e risponde
subito con un risultato in sospeso:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}L'altra persona sente una frase dell'agente, poi la musica di attesa. In un
menu telefonico o nella segreteria telefonica, l'agente usa invece aggiornamenti vocali, e un
agente full-duplex non mette in attesa: riceve la risposta in attesa come risultato. Quando la
risposta arriva nel thread, inviala con
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."}}'La musica si attenua e l'agente prosegue con la tua risposta. Se nessuno
risponde prima del timeout, l'agente viene informato che non è arrivata alcuna risposta e propone
all'altra persona i passaggi successivi. Mentre una domanda è in attesa per una chiamata,
la risposta successiva nel relativo thread risponde alla domanda: inviala come risultato dello strumento e
non inviarla anche come sussurro (un sussurro raggiunge l'agente solo dopo
la restituzione dello strumento). Consulta
Attese lunghe.
Attendi nella richiesta (fino a 3 minuti). Il tuo endpoint pubblica la domanda,
attende una risposta e la restituisce, ad esempio {"answer": "Yes, book Tuesday at 10."}.
Imposta il spec.timeout dello strumento tramite l'API, fino a 180 secondi (il
valore predefinito è 20). Assegna al tuo endpoint una propria scadenza di qualche secondo più breve
(ad esempio 170 secondi), così, quando nessuno risponde, restituisce comunque
qualcosa su cui l'agente può agire, ad esempio
{"answer": null, "note": "No reply yet. Offer to take a message."}. Uno strumento
che raggiunge il proprio timeout arriva all'agente come errore e il tuo host deve
mantenere aperta una richiesta per tutto quel tempo. Mentre attende, l'agente dice all'altra
persona che sta verificando, comunica che sta ancora lavorando dopo circa 12 secondi, e
poi fornisce un breve aggiornamento circa ogni 15 secondi. Anche qui funziona la modalità di
attesa: imposta spec.wait_mode su "hold" e l'altra persona sente la musica
invece degli aggiornamenti.
Rispondi tramite sussurro. Il tuo endpoint pubblica la domanda e restituisce subito,
ad esempio {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Quando arriva la risposta, inviala come sussurro (passaggio 3) e l'agente
risponde immediatamente. Usa questa opzione per risposte che potrebbero richiedere più di
10 minuti. La chiamata non viene messa in attesa: il tuo prompt deve indicare all'
agente cosa fare nel frattempo, ad esempio intrattenere la persona o proporre
di richiamarla.
In ogni caso, indica nel prompt dell'agente quando usare lo strumento e cosa dire all'altra persona durante l'attesa:
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.Limiti da considerare
- Il tuo endpoint deve rispondere entro il
timeoutdello strumento, al massimo 180 secondi. Uno strumento in modalità di attesa può mantenere la chiamata in attesa per un massimo di 600 secondi con un risultato in sospeso. - Mentre uno strumento attende, l'agente non risponde all'altra persona. In modalità di attesa, sente della musica; altrimenti, brevi aggiornamenti vocali.
- Un sussurro è lungo al massimo 1000 caratteri.
- La consegna di
telephony.turnavviene almeno una volta e può non rispettare l'ordine.
Checklist di sicurezza
- Mantieni la chiave API sul tuo server.
- Verifica le firme di ThunderPhone su webhook e richieste degli strumenti, e
il segreto di firma di Slack sulle richieste di Slack. Le due firme di ThunderPhone
usano segreti diversi: le consegne webhook usano il segreto dell'endpoint
webhook stesso, mentre le richieste degli strumenti usano il segreto webhook della tua organizzazione
da
GET /v1/webhook. - Decidi chi può avviare le chiamate: controlla l'ID utente Slack prima di effettuarne una.
- Le chiamate in uscita seguono le stesse regole di qualsiasi altra chiamata. Consulta Norme sulle chiamate in uscita.
Crealo con un agente di programmazione
Indirizza il tuo agente di programmazione al server MCP della documentazione e a questa pagina, quindi chiedigli di creare "un bot Slack per il mio agente ThunderPhone che segua questa guida". Zeus, l'assistente nell'app ThunderPhone, può configurare la parte dell'agente (l'endpoint webhook, lo strumento e le righe del prompt) e scrivere il codice iniziale del bot nella chat.