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, 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.
• 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.

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

Python

TypeScript

cURL

Vai alla pagina 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:

Consulta il Riferimento API per lo schema completo della richiesta.

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.

Variabili dinamiche, branch e ambienti

Il campo conversation_initiation_client_data ti consente di impostare variabili dinamiche per la conversazione e vincolarla a un branch dell’agente e a un ambiente specifici:

{
  "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.

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.

Programmare una chiamata in uscita

Le chiamate WhatsApp in uscita richiedono l’autorizzazione dell’utente: consulta le autorizzazioni per le chiamate utente. Crea un modello di messaggio con un componente di richiesta di autorizzazione alla chiamata in WhatsApp Manager. 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

Python

TypeScript

cURL

Vai alla pagina 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:

Consulta il Riferimento API 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.

Campagne e invii in batch

Per chiamare molti utenti, usa le chiamate in batch 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 una volta per destinatario e rispetta i limiti di messaggistica di Meta per il tuo numero: consulta i limiti di messaggistica.