--- title: "Creare una chiamata vocale" description: "Avvia una chiamata in uscita con una sequenza Voice pubblicata o una definizione inline tramite l'API, esamina il risultato e scopri l'anteprima di CLI e MCP." canonical: "https://bird.com/it-it/documentazione/guides/voice/create-calls" --- # Creare una chiamata vocale > **Warning:** Voice sequences are in preview. Steps, entry data, and the sequence definition format can change in ways that break existing sequences and API requests. Usa [`POST /v1/voice/calls`](/docs/api/reference/create-voice-call) per chiamare un numero di telefono e avviare una sequenza pubblicata, o una definizione di sequenza inviata con la richiesta, quando il destinatario risponde. La richiesta effettua una chiamata reale; si applicano i normali costi di chiamata. **Anteprima CLI e MCP:** Queste interfacce richiedono un client compatibile. Verifica che il server MCP esponga `voice_calls_create`, oppure esegui `bird voice --help` per elencare i comandi della tua CLI. Cerca versioni più recenti con `bird update --check` e consulta [Installazione di CLI](/docs/cli). Se lo strumento o il comando non è disponibile, usa l'API HTTP o gli SDK. Nell'anteprima, CLI e MCP preparano la stessa chiamata affinché una persona la esamini e la esegua nel browser. L'agente riceve il risultato di accettazione registrato dopo che la persona esegue la richiesta. ## Prima di iniziare Prepara queste risorse nello stesso spazio di lavoro: - Una sequenza da eseguire: una [sequenza abilitata, non archiviata, con una pubblicazione attiva](/docs/guides/voice/sequences/publishing) creata nella dashboard, oppure una definizione completa inviata con la richiesta. - Una [chiave API](/docs/api/authentication) per le richieste HTTP, oppure un login OAuth per CLI e MCP, con entrambe le autorizzazioni `voice_management:write` e `voice:write`. - Un numero chiamante che lo spazio di lavoro può presentare, ad esempio un [caller ID](/docs/guides/voice/caller-ids) di proprietà o verificato, e un [paese di destinazione](/docs/guides/voice/destinations) abilitato. Preferisci un numero nel paese del destinatario: alcune reti mobili rifiutano una chiamata che presenta un caller ID estero. - Un destinatario che controlli per la prima chiamata. L'oggetto `sequence` accetta esattamente uno tra `sequence.id` o `sequence.definition`. Entrambi richiedono anche `entry_node_id`, lo step **Start call** da cui inizia la chiamata, e `trigger_data`, un oggetto conforme allo schema dati di quell'entry. Usa `{}` quando l'entry accetta dati vuoti. Il [riferimento Create Call](/docs/api/reference/create-voice-call) documenta i limiti della richiesta e il timeout di squillo opzionale. ## Chiamare una sequenza creata nella dashboard Usa `sequence.id` per eseguire una sequenza che hai [creato](/docs/guides/voice/sequences/editor) e [pubblicato](/docs/guides/voice/sequences/publishing) nella dashboard. Create Call esegue sempre la pubblicazione attiva. 1. Apri la sequenza in [**Sequences**](https://bird.com/dashboard/w/voice/sequences). 2. In **How to run this sequence**, seleziona **More details** accanto a **Create a call**. 3. Se la sequenza ha più entry, scegli il **Call trigger** da cui partire. 4. Copia la richiesta. Contiene l'ID della sequenza e l'ID dell'entry. Salva il corpo della richiesta come `call.json`, sostituendo i numeri di esempio con i tuoi: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "id": "YOUR_SEQUENCE_ID", "entry_node_id": "YOUR_ENTRY_NODE_ID", "trigger_data": {} } } ``` Compila `trigger_data` con i campi dichiarati dall'entry, inclusi oggetti annidati e array. Create Call non accetta versioni storiche, bozze o modalità di test. Per testare una bozza salvata, usa i controlli [Effettua una chiamata](/docs/guides/voice/sequences/testing) della dashboard. ## Eseguire una sequenza inline Usa `sequence.definition` per inviare una sequenza completa con la chiamata. Bird la esegue una sola volta senza salvarla, quindi la chiamata non ha un ID di sequenza. Una definizione inline è adatta ai flussi che la tua applicazione genera per ogni chiamata. Una definizione inline deve superare gli stessi controlli della pubblicazione di una sequenza. La sua esecuzione può eseguire al massimo 16 comandi, inclusi i prompt di raccolta; una chiamata che ne richiede un 17° termina con l'errore di trace `call_limit`. Il [riferimento dei nodi](/docs/guides/voice/sequences/node-reference) elenca ogni passaggio utilizzabile, con i relativi campi e risultati. Per partire da un flusso funzionante, costruiscilo e pubblicalo nella dashboard, apri la sequenza e seleziona **Copy JSON** su **Definition JSON** sotto **Published version**. Questo `call.json` chiede al destinatario di premere 1 per gli orari di apertura o 2 per le indicazioni stradali. Il silenzio e qualsiasi altro tasto terminano l'esecuzione con i rispettivi motivi di uscita: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "entry_node_id": "start", "trigger_data": {}, "definition": { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "start", "type": "trigger.start_call", "type_version": 1, "config": {}, "input": {}, "connections": { "event": { "node_id": "menu", "port": "input" } } }, { "id": "menu", "type": "voice.gather", "type_version": 1, "config": {}, "input": { "prompts": [ { "type": "say", "text": "Press 1 for opening hours, or 2 for directions.", "language": "en" } ], "max_digits": 1, "timeout_seconds": 5, "inter_digit_timeout_seconds": 2, "finish_on_key": "#", "private": false, "matches": { "hours": "1", "directions": "2" } }, "connections": { "hours": { "node_id": "hours", "port": "input" }, "directions": { "node_id": "directions", "port": "input" }, "timeout": { "node_id": "no_input", "port": "input" }, "fallback": { "node_id": "other_input", "port": "input" } } }, { "id": "hours", "type": "voice.say", "type_version": 1, "config": {}, "input": { "text": "We are open Monday through Friday, nine to five.", "language": "en" }, "connections": { "next": { "node_id": "done", "port": "input" } } }, { "id": "directions", "type": "voice.say", "type_version": 1, "config": {}, "input": { "text": "Find directions on your appointment confirmation.", "language": "en" }, "connections": { "next": { "node_id": "done", "port": "input" } } }, { "id": "done", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "information_played" }, "input": { "output": {} } }, { "id": "no_input", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "no_input" }, "input": { "output": {} } }, { "id": "other_input", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "unrecognized_input" }, "input": { "output": {} } } ] } } } ``` Il campo `connections` di ogni nodo mappa un esito al nodo successivo. Il campo `matches` del menu elenca le scelte disponibili e `connections` usa gli stessi nomi insieme agli esiti predefiniti `timeout` e `fallback`. ### Personalizzare una sequenza inline Dichiara i campi che invii nel campo `data_schema` dell'entry, poi leggili come `trigger.data.` in un valore `$expr`. Questa chiamata saluta il destinatario per nome e conferma o segnala il suo appuntamento: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "entry_node_id": "start", "trigger_data": { "appointment_id": "apt_2048", "customer_name": "Sam", "appointment_time": "Tuesday at 10 AM" }, "definition": { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "start", "type": "trigger.start_call", "type_version": 1, "config": { "data_schema": { "type": "object", "additionalProperties": false, "required": ["appointment_id", "customer_name", "appointment_time"], "properties": { "appointment_id": { "type": "string", "minLength": 1 }, "customer_name": { "type": "string", "minLength": 1 }, "appointment_time": { "type": "string", "minLength": 1 } } } }, "input": {}, "connections": { "event": { "node_id": "confirm_menu", "port": "input" } } }, { "id": "confirm_menu", "type": "voice.gather", "type_version": 1, "config": {}, "input": { "prompts": [ { "type": "say", "text": { "$template": [ "Hello ", { "$expr": "trigger.data.customer_name" }, ". Press 1 to confirm your appointment on ", { "$expr": "trigger.data.appointment_time" }, ", or 2 if you need help." ] }, "language": "en" } ], "max_digits": 1, "timeout_seconds": 7, "inter_digit_timeout_seconds": 2, "finish_on_key": null, "private": false, "matches": { "confirm": "1", "help": "2" } }, "connections": { "confirm": { "node_id": "confirmed", "port": "input" }, "help": { "node_id": "help_requested", "port": "input" }, "timeout": { "node_id": "no_response", "port": "input" }, "fallback": { "node_id": "no_response", "port": "input" } } }, { "id": "confirmed", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "appointment_confirmed" }, "input": { "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } } } }, { "id": "help_requested", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "appointment_help_requested" }, "input": { "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } } } }, { "id": "no_response", "type": "logic.exit", "type_version": 1, "config": { "status": "failed", "reason": "appointment_no_response" }, "input": { "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } } } } ] } } } ``` I campi `status` e `reason` di ogni uscita distinguono una conferma, una richiesta di assistenza e nessuna risposta. Un oggetto `trigger_data` che non corrisponde a `data_schema` non supera la validazione, con la sua posizione indicata in `/sequence/trigger_data`, e nessuna chiamata viene effettuata. ## Inviare la richiesta Scegli uno dei metodi di richiesta seguenti per il `call.json` che hai salvato. Scegli una chiave di idempotenza univoca e nuova per questa chiamata. Conserva la chiave e l'input originale per i tentativi successivi o il recupero della conferma. Scegli un'altra chiave quando intendi effettuare una nuova chiamata separata, dopo aver risolto qualsiasi esito sconosciuto della chiamata originale. Per gli esempi shell, imposta `IDEMPOTENCY_KEY` sul valore scelto prima dell'invio. Gli esempi si interrompono se il valore non è impostato o è vuoto; non generano un'altra chiave quando vengono ripetuti. Per HTTP, imposta `BIRD_API_KEY` sulla tua chiave e `BIRD_API_URL` sul relativo [URL base regionale](/docs/api/regions), ad esempio `https://eu1.platform.bird.com` per una chiave `eu1`, quindi invia la richiesta: ```bash curl --request POST "$BIRD_API_URL/v1/voice/calls" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" \ --data-binary @call.json ``` Per l'anteprima di [CLI](/docs/cli), accedi con entrambe le autorizzazioni in scrittura e prepara la chiamata usando lo stesso file: ```bash bird auth login --scope voice_management:write --scope voice:write bird voice calls create --body-file call.json \ --idempotency-key "${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" ``` Il comando stampa un link di revisione nel browser e attende il completamento. Apri il link, verifica chiamante, destinatario, sequenza e dati dell'entry, quindi esegui la richiesta tu stesso. Preparare la richiesta non effettua la chiamata. Aggiungi `--dry-run` per ispezionare la richiesta CLI senza creare una conferma. Se la conferma scade, viene annullata o termina senza un risultato registrato, il comando esce con `5`; segui la [guida ai tentativi successivi](#gestire-errori-e-tentativi-successivi) prima di effettuare un'altra richiesta. Per l'anteprima di [MCP](/docs/ai/mcp-server), chiama `voice_calls_create` con i campi di `call.json` e un `idempotency_key` obbligatorio. Sostituisci `` con la chiave scelta: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "id": "YOUR_SEQUENCE_ID", "entry_node_id": "YOUR_ENTRY_NODE_ID", "trigger_data": {} }, "idempotency_key": "" } ``` Segui il link di revisione nel browser restituito per eseguire la richiesta. Sull'endpoint dinamico MCP, seleziona `voice_calls_create` tramite `execute`. Il consenso OAuth concede le autorizzazioni dello spazio di lavoro; la revisione nel browser esegue questa specifica chiamata. Una risposta `202 Accepted` conferma l'ammissione. La sequenza inizia dopo che il destinatario risponde. Pubblicare una versione più recente dopo l'accettazione non modifica la definizione selezionata né i dati dell'entry di questa chiamata. ## Leggere il risultato di accettazione Conserva `id`, `initial_leg_id` e `sequence.run_id` della risposta per la correlazione. Il campo `id` di primo livello identifica la chiamata tra le sue leg; `initial_leg_id` identifica la prima leg. La risposta è uno snapshot di accettazione immutabile. I campi `started_at` e `ended_at` sono `null`, i booleani di osservazione sono `false` e `parties` è vuoto. Questi campi descrivono l'accettazione, quindi non diventano un report di stato in tempo reale quando ripeti la richiesta. Apri le [**Runs**](/docs/guides/voice/sequences/runs) della sequenza per controllare l'avanzamento. Una chiamata inline non appartiene a nessuna sequenza, quindi segui la sua leg; se fallisce prima che la leg venga registrata, non c'è ancora modo di ispezionarla. Quando esiste un record della leg, usa [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg) con `initial_leg_id`, oppure controlla il [registro chiamate](/docs/guides/voice/call-log). La lettura delle leg richiede il permesso `voice:read`, incluso in `voice:write`. Una leg con `status` `rejected` è stata rifiutata prima della connessione, quindi la sua sequenza non è stata eseguita. Senza un motivo di rifiuto, l'estremità remota ha declinato la chiamata; vedi [Chiamate rifiutate](/docs/guides/voice/call-log#rejected-calls). Con CLI, `bird voice calls get YOUR_CALL_ID` mostra la chiamata e le sue parti. `bird voice legs trace YOUR_LEG_ID` mostra quali passi sono stati eseguiti, le cifre raccolte a meno che il gather sia privato, e lo stato e il motivo dell'uscita. La traccia è disponibile poco dopo la fine della chiamata; fino a quel momento il comando restituisce un errore, quindi riprovare. La sequenza di un leg rifiutato non è mai stata eseguita, quindi potrebbe non avere traccia. L'accettazione non garantisce la composizione, una risposta o un record di chiamata leggibile. Una chiamata che fallisce prima della registrazione può comparire nella cronologia delle esecuzioni senza un record di leg. Una chiamata con risposta inoltre non dimostra che la sequenza abbia completato l'operazione di business prevista. ## Gestire errori e tentativi successivi Per le richieste HTTP dirette, l'idempotenza è opzionale. Senza chiave, ogni richiesta accetta un nuovo tentativo di chiamata. Gli SDK generano una chiave per i tentativi automatici. Per proteggere i tentativi successivi tra chiamate separate o richieste HTTP dirette, fornisci una chiave al primo tentativo e riutilizzala con gli stessi byte della richiesta originale. Consulta la [guida all'idempotenza](/docs/guides/idempotency). Una ripetizione identica entro tre ore restituisce l'accettazione originale e `Idempotency-Replay: true`. Un input modificato con la stessa chiave restituisce `409`. Autorizzazione e permessi sul numero chiamante vengono verificati nuovamente in fase di ripetizione. Dopo la finestra di ripetizione, la chiave può ammettere una nuova chiamata: riconcilia il risultato originale prima di reinviare. Per CLI e MCP, fornisci la chiave di idempotenza al primo tentativo. Ripetere la stessa richiesta e chiave con lo stesso grant OAuth restituisce la conferma esistente finché il relativo record è conservato. Conserva l'input originale e l'ID della conferma. Cambiare la chiave può preparare un'altra chiamata fatturabile. Se il comando CLI viene interrotto, riprendi con l'input originale, la chiave e l'ID della conferma restituito: ```bash bird voice calls create --body-file call.json \ --idempotency-key "${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" \ --confirmation-id YOUR_CONFIRMATION_ID ``` Per MCP, ripeti gli argomenti originali del tool, incluso lo stesso `idempotency_key`, insieme allo stato della richiesta restituito. Lo stato identifica la conferma e non sostituisce quegli argomenti. In alternativa, ripeti lo stesso tool e gli stessi argomenti con l'ID restituito nei metadati della richiesta `bird/confirmation-id`. Con MCP dinamico, ripeti la stessa richiesta `execute` e inserisci quei metadati. Il ripristino legge la conferma originale e restituisce il risultato registrato al completamento. Una conferma di Create Call scade dopo 90 minuti. Una conferma `pending` o `expired` senza risultato non dimostra che la chiamata non sia mai stata effettuata. Esamina l'esecuzione della sequenza originale e qualsiasi record di leg prima di decidere di effettuare un'altra chiamata; non creare una nuova chiave per risolvere un esito sconosciuto. Una conferma completata con risultato `202` dimostra l'accettazione: procedi con [i controlli di accettazione](#leggere-il-risultato-di-accettazione) per stabilire l'esito della chiamata. | Sintomo | Cosa verificare | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` o `422` | Leggi i dettagli dei campi nell'errore. Verifica formato del numero, idoneità e proprietà del numero chiamante, ID di sequenza e di entry, oggetto dati esplicito e limiti della richiesta. | | `401` o `403` | Verifica la chiave API o il login OAuth, entrambe le autorizzazioni in scrittura richieste e l'accesso allo spazio di lavoro. | | `404` | Verifica che la sequenza appartenga allo spazio di lavoro selezionato e che la creazione di chiamate sia disponibile sul servizio regionale. | | `409` | Verifica se si tratta di un tentativo con corpo modificato o di una sequenza di produzione attiva non disponibile. Pubblica o riprendi secondo necessità prima di avviare una nuova chiamata. | | `429` | Rispetta le indicazioni sui tentativi nella risposta. Se hai fornito una chiave, riutilizzala per lo stesso tentativo di chiamata. | | Accettata, poi fallita | Esamina l'esecuzione e qualsiasi record di leg per destinazione, limiti, saldo o errori di runtime prima di decidere di effettuare un'altra chiamata. | ## Passaggi successivi - [Riferimento API di Create Call](/docs/api/reference/create-voice-call). - [Definire i dati dell'entry della sequenza](/docs/guides/voice/sequences/data). - [Ispezionare le esecuzioni della sequenza](/docs/guides/voice/sequences/runs). - [Ricevere eventi di chiamata](/docs/guides/voice/events). ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)