> ## Documentation Index > Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt > Use this file to discover all available pages before exploring further. # API Notifiche WhatsApp > Documentazione ufficiale per utilizzare l'API di Lovi con WhatsApp tramite Postman ## Introduzione Questa sezione fornisce la documentazione ufficiale per utilizzare l'API di Lovi con WhatsApp tramite Postman. Include istruzioni dettagliate su come configurare e testare le richieste API per l'integrazione con WhatsApp, garantendo una comunicazione fluida attraverso la piattaforma. L'autenticazione viene effettuata utilizzando token che abilitano l'autenticazione di base per i servizi API. Per ulteriori dettagli su come autenticarsi, consulta la pagina [Autenticazione](./authentication). L'API di Lovi supporta le notifiche WhatsApp con contenuti multimediali, segnaposto dinamici, consegna programmata e integrazione con flussi di conversazione. ### Funzionalità principali: * Notifiche WhatsApp con supporto multimediale * Personalizzazione dinamica dei contenuti con segnaposto * Consegna programmata dei messaggi con supporto fuso orario * Integrazione con flussi di conversazione * Due formati di struttura dati (annidata e piatta) *** ## 📣 Invia notifica WhatsApp Per inviare una notifica tramite l'API di Lovi, effettua una richiesta POST all'endpoint con i parametri necessari e l'autenticazione. > **Metodo**: POST **Formato**: JSON ### Endpoint ``` POST https://cloud.lovi.ai/functions/v1/notify?access_key={YOUR_ACCESS_KEY} ``` ### Parametri di query | Parametro | Obbligatorio | Descrizione | | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access_key` | Sì | La tua chiave di accesso API unica. | | `unflatten` | No | Se impostato su `true`, il corpo deve contenere variabili piatte (nessun oggetto annidato). Se impostato su `false` o omesso, il corpo può contenere oggetti annidati. | **URL di esempio:** ``` POST https://cloud.lovi.ai/functions/v1/notify?access_key=your-api-key POST https://cloud.lovi.ai/functions/v1/notify?access_key=your-api-key&unflatten=true ``` ### Header | Chiave | Valore | Obbligatorio | Descrizione | | ------------ | ---------------- | ------------ | ------------------------------------------------------ | | Content-Type | application/json | Sì | Indica che il corpo della richiesta è in formato JSON. | **Nota**: L'autenticazione è gestita tramite il parametro `access_key` nell'URL, non tramite gli header. *** ## 📋 Parametri della richiesta L'API supporta due formati di struttura dati controllati dal parametro `unflatten`. ### Parametri obbligatori | Parametro | Tipo | Descrizione | Esempio | | ---------------------- | -------------- | ------------------------------------------------------------------------------- | --------------------------------------------- | | `contact` O `contacts` | Object O Array | **Scegli uno**: Singolo contatto (oggetto) O Contatti multipli (array, max 100) | Vedi sotto | | `language_template` | String | Codice lingua per il template | `"es_ES"`, `"en_US"` | | `name_template` | String | Nome del template approvato | `"welcome_user"` | | `recipient_id` | String | ID o numero di telefono del destinatario | `"34666033135"` | | `notification_type` | String | Tipo per le analisi | `"marketing"`, `"transactional"`, `"utility"` | | `campaign_name` | String | Nome identificativo della campagna | `"Black Friday 2024"` | **Importante**: Devi usare `contact` (per singolo destinatario) O `contacts` (per destinatari multipli), ma NON entrambi. ### Parametri opzionali | Parametro | Tipo | Descrizione | Quando usarlo | Esempio | | ------------------- | -------- | ------------------------------------------- | ---------------------------------------------- | ----------------------- | | `contact.name` | String | Nome del contatto per personalizzazione | Per messaggi personalizzati | `"Juan Pérez"` | | `contact.email` | String | Email del contatto | Per dati aggiuntivi del contatto | `"juan@email.com"` | | `name_event` | String | Evento per attivare flussi di conversazione | Quando vuoi avviare un flusso specifico | `"intent-general-push"` | | `datetime_sending` | DateTime | Orario di consegna programmato (ISO 8601) | Quando vuoi programmare il messaggio per dopo | `"2024-12-25T10:30:00"` | | `timezone` | String | Fuso orario per la consegna programmata | Quando usi `datetime_sending` | `"Europe/Madrid"` | | `components_push.*` | Mixed | Componenti del template (testo, media) | Quando il template richiede contenuto dinamico | Vedi sezione componenti | *** ## 👥 Singolo vs destinatari multipli ### Usando `contact` - Invia a una persona Usa `contact` quando vuoi inviare una notifica a **un destinatario**. **Struttura**: ```json theme={null} { "contact": { "number": "34666033135", "name": "John", "email": "john@example.com" } } ``` * `contact` è un **oggetto** (non una lista) * Campo obbligatorio: `number` * Campi opzionali: `name`, `email` e qualsiasi campo personalizzato *** ### Usando `contacts` - Invia a più persone (Invio massivo) Usa `contacts` quando vuoi inviare la stessa notifica a **più destinatari** contemporaneamente. **Struttura**: ```json theme={null} { "contacts": [ { "number": "34666033135", "name": "John" }, { "number": "34777044246", "name": "Sarah" }, { "number": "34888055357", "name": "Michael" } ] } ``` * `contacts` è una **lista/array** (non un singolo oggetto) * **Massimo**: 100 contatti per richiesta * Ogni contatto nella lista deve avere un `number` * Campi opzionali: `name`, `email` e qualsiasi campo personalizzato **Restrizioni importanti**: * ⚠️ **Non è possibile usare `unflatten=true` con `contacts`** - L'invio massivo funziona solo con struttura annidata * ⚠️ **Non è possibile usare sia `contact` che `contacts`** nella stessa richiesta - scegli uno * ⚠️ **La lista `contacts` non può essere vuota** - deve avere almeno 1 contatto *** ## 🔄 Formati della struttura dati L'API supporta due formati basati sul parametro `unflatten`: ### Struttura annidata (unflatten=false o omesso) Quando `unflatten=false` o non specificato, usa oggetti annidati: ```json theme={null} { "contact": { "number": "34666033135", "name": "Juan Pérez", "email": "juan@email.com" }, "components_push": { "header_text_0": "Welcome Message", "body_text_0": "Hello {{name}}", "body_text_1": "Your order is ready!", "footer_text_0": "Support Team" }, "language_template": "es_ES", "name_template": "order_ready", "recipient_id": "34666033135", "notification_type": "transactional", "campaign_name": "Order Notifications" } ``` ### Struttura piatta (unflatten=true) Quando `unflatten=true`, tutti gli oggetti annidati devono essere appiattiti usando la notazione con punto: ```json theme={null} { "contact.number": "34666033135", "contact.name": "Juan Pérez", "contact.email": "juan@email.com", "components_push.header_text_0": "Welcome Message", "components_push.body_text_0": "Hello {{name}}", "components_push.body_text_1": "Your order is ready!", "components_push.footer_text_0": "Support Team", "language_template": "es_ES", "name_template": "order_ready", "recipient_id": "34666033135", "notification_type": "transactional", "campaign_name": "Order Notifications" } ``` ### Quando usare ciascun formato * **Struttura annidata (`unflatten=false`)**: Raccomandata per una migliore leggibilità e quando il tuo sistema supporta oggetti annidati * **Struttura piatta (`unflatten=true`)**: Usa quando il tuo sistema non supporta oggetti annidati o richiede una struttura dati piatta *** Per la documentazione completa su componenti e multimediali, variabili dei template, programmazione, codici di risposta, errori comuni e migliori pratiche, consulta le pagine dedicate: ## 📚 Documentazione correlata * **[Autenticazione](./authentication)** - Come ottenere token di accesso e chiavi API * **[Notifiche vocali](./voice_notifications)** - Invia chiamate vocali automatizzate * **[Gestione template](./template_management)** - Crea e gestisci template WhatsApp * **[Programmazione](./scheduling)** - Programmazione avanzata e gestione fusi orari * **[Gestione errori](./error_handling)** - Codici di errore completi e strategie di gestione * **[Migliori pratiche](./best_practices)** - Linee guida su sicurezza e prestazioni