> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Messaggi in uscita e template ## Panoramica Un agente può inviare messaggi WhatsApp in formato libero solo all'interno di una conversazione attiva. Per contattare per primo un utente, ad esempio per notifiche, ricoinvolgimento o chiamate programmate, invia un **modello di messaggio** approvato da Meta. Questa pagina spiega come creare modelli, inviare messaggi e chiamate in uscita e gestirli su larga scala. ## Creare modelli in WhatsApp Manager I modelli vengono creati e approvati in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates), non in ElevenLabs. Quando crei un modello: * Scegli una categoria: **Utility** per i messaggi transazionali, **Marketing** per i messaggi promozionali o **Authentication** per i codici di verifica. Meta applica prezzi e limiti di frequenza diversi per ogni categoria: consulta i [prezzi di WhatsApp](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing). * Scegli un formato dei parametri: posizionale (`{{1}}`, `{{2}}`) o con nome (`{{customer_name}}`). I parametri con nome richiedono `parameter_name` per ogni valore inviato. * Invia il modello per l'approvazione. L'approvazione richiede in genere da pochi minuti a qualche ora. Un modello in attesa o rifiutato non può essere inviato: l'API accetta la richiesta, ma Meta non consegna mai il messaggio. > **Note** > > Meta limita il numero di [modelli di marketing](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits) > che un singolo utente può ricevere in un determinato periodo. Se un modello di marketing non viene consegnato senza alcuna segnalazione, > questo limite è una causa comune (errore Meta 131049). ## Inviare un messaggio in uscita L'invio di un messaggio modello avvia una nuova conversazione. L'agente rimane in silenzio finché l'utente non risponde: il modello è il primo messaggio e nessun timer della conversazione si avvia finché l'utente non risponde. #### Dashboard Vai alla [pagina WhatsApp](https://elevenlabs.io/app/agents/whatsapp), seleziona il tuo account e fai clic sul pulsante ***In uscita -> Messaggio***. Seleziona un agente, inserisci un ID utente WhatsApp e scegli il modello di messaggio e i relativi parametri: ![Finestra di dialogo per messaggio WhatsApp in uscita](/docs/_fern-img/13913c2ccc1d92cb59e7332b6fdb4a8c8c64760a334d1a311fa2007831eeb986.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_message( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", template_name="welcome", template_language_code="en", template_params=[ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "name", "text": "Daniele", } ], } ], agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundMessage({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", templateName: "welcome", templateLanguageCode: "en", templateParams: [ { type: "body", parameters: [ { type: "text", parameterName: "name", text: "Daniele", }, ], }, ], agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "template_name": "welcome", "template_language_code": "en", "template_params": [ { "type": "body", "parameters": [ {"type": "text", "parameter_name": "name", "text": "Daniele"} ] } ], "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Consulta il [Riferimento API](/docs/it/api-reference/whats-app/outbound-message) per lo schema completo della richiesta. > **Tip** > > Un assistente IA può adattare questi esempi al tuo modello. Indicagli la documentazione di ElevenLabs > [llms.txt](/docs/it/llms.txt) (o il più dettagliato [llms-full.txt](/docs/it/llms-full.txt)), incolla la definizione del tuo > modello da WhatsApp Manager e chiedigli la richiesta: produrrà un comando cURL > o una chiamata SDK con i `template_params` corretti per il tuo modello. ### Parametri del modello `template_params` è un elenco di oggetti **component**, uno per ogni componente del modello che contiene parametri: * `{"type": "body", "parameters": [...]}` per i segnaposto del corpo * `{"type": "header", "parameters": [...]}` per un'intestazione parametrizzata (testo, immagine, documento o posizione) * `{"type": "button", "sub_type": ..., "index": ..., "parameters": [...]}` per i parametri dei pulsanti Ogni voce in `parameters` è un oggetto valore, ad esempio `{"type": "text", "text": "Daniele"}`. Per i modelli con parametri con nome, includi `parameter_name` per ogni valore. L'omissione del wrapper del componente, ad esempio passando `{"type": "text", ...}` direttamente in `template_params`, viene rifiutata. ### Formato del numero del destinatario `whatsapp_user_id` deve contenere solo cifre: il prefisso internazionale seguito dal numero, senza `+`, spazi o trattini. Ad esempio, `14155552671`, non `+1 (415) 555-2671`. > **Warning** > > In alcuni Paesi l'ID che WhatsApp usa per una persona è diverso dal numero composto: ad > esempio, i numeri messicani hanno un ulteriore `1` dopo il prefisso internazionale (`521...`), mentre i > numeri brasiliani possono includere o omettere una nona cifra. Se l'utente ti ha già scritto in precedenza, usa preferibilmente > il `whatsapp_user_id` di quella conversazione, che puoi copiare dalla cronologia > delle conversazioni. ### Variabili dinamiche, branch e ambienti Il campo `conversation_initiation_client_data` ti consente di impostare [variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables) per la conversazione e vincolarla a un [branch dell'agente](/docs/it/eleven-agents/operate/versioning) e a un [ambiente](/docs/it/eleven-agents/integrate/environment-variables) specifici: ```json { "dynamic_variables": { "customer_name": "Daniele" }, "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0", "environment": "staging" } ``` Queste impostazioni persistono per la conversazione: quando l'utente risponde, l'agente riprende sul branch e nell'ambiente richiesti. Il branch e l'ambiente vengono prima convalidati: se uno dei due non esiste, la richiesta non va a buon fine con un errore e non viene inviato alcun messaggio. Questo campo della richiesta consente alle conversazioni in uscita di ricevere variabili dinamiche; le conversazioni in entrata le ricevono invece da un webhook di avvio della conversazione: consulta il [contesto di inizializzazione](/docs/it/eleven-agents/whatsapp#initialization-context). > **Note** > > I parametri del modello compilano solo il testo del modello e non sono esposti all'agente. Se > l'agente ha bisogno di un valore del modello, come il nome del cliente, passalo di nuovo in > `dynamic_variables`. ### Dopo l'invio Una richiesta completata correttamente restituisce un `conversation_id` e la conversazione appare nella tua cronologia con il modello compilato come primo messaggio. L'agente non si avvia finché l'utente non risponde. L'invio del modello non avvia né il timer della durata massima né quello di inattività; entrambi iniziano quando la conversazione riprende. Una risposta `200` indica che ElevenLabs ha accettato la richiesta, ma Meta può comunque rifiutare la consegna in seguito. Se il messaggio non arriva, consulta la sezione [Risoluzione dei problemi](/docs/it/eleven-agents/whatsapp/troubleshooting). ## Programmare una chiamata in uscita Le chiamate WhatsApp in uscita richiedono l'autorizzazione dell'utente: consulta le [autorizzazioni per le chiamate utente](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions). Crea un modello di messaggio con un componente di **richiesta di autorizzazione alla chiamata** in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates). Quando programmi una chiamata, ElevenLabs verifica lo stato dell'autorizzazione: * Autorizzazione già concessa: la chiamata viene effettuata immediatamente. * Autorizzazione non ancora richiesta: viene inviato il modello di richiesta di autorizzazione e la chiamata viene effettuata non appena l'utente approva. * Autorizzazione rifiutata: la conversazione viene registrata come non riuscita con il motivo `User declined the call permission request.` #### Dashboard Vai alla [pagina WhatsApp](https://elevenlabs.io/app/agents/whatsapp), seleziona il tuo account e fai clic sul pulsante ***In uscita -> Chiamata***. Seleziona un agente, inserisci un ID utente WhatsApp e scegli il modello di richiesta di autorizzazione alla chiamata: ![Finestra di dialogo per chiamata WhatsApp in uscita](/docs/_fern-img/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_call( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", whatsapp_call_permission_request_template_name="call_permission", whatsapp_call_permission_request_template_language_code="en", agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundCall({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", whatsappCallPermissionRequestTemplateName: "call_permission", whatsappCallPermissionRequestTemplateLanguageCode: "en", agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "whatsapp_call_permission_request_template_name": "call_permission", "whatsapp_call_permission_request_template_language_code": "en", "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Consulta il [Riferimento API](/docs/it/api-reference/whats-app/outbound-call) per lo schema completo della richiesta. Come per i messaggi in uscita, `conversation_initiation_client_data` imposta le variabili dinamiche e vincola la conversazione a un branch e a un ambiente; un branch o un ambiente sconosciuto viene rifiutato prima che la chiamata sia programmata. > **Note** > > Meta addebita le chiamate in uscita e le richieste di autorizzazione alla chiamata inviate al di fuori di una [finestra del servizio clienti ](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows). > Aggiungi un metodo di pagamento in WhatsApp Manager prima di programmare le chiamate. ## Campagne e invii in batch Per chiamare molti utenti, usa le [chiamate in batch](/docs/it/eleven-agents/phone-numbers/batch-calls) con `whatsapp_params`: fornisci una volta l'ID del numero di telefono e il modello di richiesta di autorizzazione alla chiamata, quindi un `whatsapp_user_id` per destinatario. Non esiste ancora un endpoint batch nativo per i messaggi in uscita. Per le campagne con modelli, chiama l'[endpoint dei messaggi in uscita](/docs/it/api-reference/whats-app/outbound-message) una volta per destinatario e rispetta i limiti di messaggistica di Meta per il tuo numero: consulta i [limiti di messaggistica](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits).