---
title: "Esegui chiamate da Slack o da un'app di chat"
description: "Crea il tuo bot per Slack, Teams o chat web che avvia chiamate, le segue in diretta, guida l'agente e risponde alle sue domande, utilizzando l'API pubblica."
---

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`](/api-reference/outbound-calls) con il messaggio come `context` | L'agente chiama. Il tuo bot apre un thread per la chiamata |
| Osserva il thread | Riceve webhook [`telephony.turn`](/it/webhooks/events) | Ogni riga pronunciata dall'agente o dall'altra persona appare nel thread |
| Rispondi nel thread durante la chiamata | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | 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](/it/guides/build-tool-integration) restituisce la tua risposta oppure la invia in seguito con [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | 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`](/it/webhooks/events) | 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](/it/guides/api-keys)).
- **Un numero abilitato alle chiamate in uscita e un agente** per le chiamate. Il messaggio
  diventa `context` per 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.turn` e `telephony.complete`. Gli eventi di turno vengono inviati solo agli
  endpoint che li elencano. Vedi [Webhook](/it/webhooks/endpoints).
  Gli eventi di turno richiedono la registrazione delle chiamate dell'agente attivata e il
  `summary` di 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](https://api.slack.com/apps).

<Tip>
  Usa un'app Slack creata per il tuo workspace e ricevi i messaggi
  tramite l'API Events di Slack invece di leggere la cronologia del canale. Slack
  applica limiti di lettura rigorosi alle app distribuite ad altri workspace al di fuori
  del suo Marketplace; un'app creata per il tuo workspace non è soggetta a
  tali limiti, e gli eventi ti raggiungono quando si verificano senza alcuna lettura. Ambiti
  tipici del bot: `chat:write`, `app_mentions:read`, `im:history` (messaggi
  diretti), `channels:history` e `groups:history` (risposte nei thread nei
  canali pubblici e privati in cui è presente il bot). Sottoscrivi gli eventi bot
  `app_mention`, `message.im`, `message.channels` e `message.groups`, e
  attiva la scheda Messaggi in Home dell'app affinché le persone possano inviare messaggi diretti al bot.
</Tip>

## 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`:

```bash
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](/it/guides/verify-webhook-signatures).
- **Elimina i duplicati usando l'`event_id` dell'envelope e ordina per `position`.**
  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](/it/webhooks/call-complete) 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:

```bash
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](/it/guides/build-tool-integration) 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](/api-reference/integrations#timeout-and-wait-mode) 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:

```json
{"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`](/api-reference/calls#deliver-a-tool-result):

```bash
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](/it/tools/overview).

**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:

```text
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 `timeout` dello 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.turn` avviene 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`](/api-reference/organizations#legacy-single-url-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](/it/guides/outbound-calling-laws).

## Crealo con un agente di programmazione

Indirizza il tuo agente di programmazione al [server MCP della documentazione](/it/guides/docs-mcp) 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.
