API Notifiche WhatsApp - Lovi AI Documentation

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

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:

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

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

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

{
  "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 - Come ottenere token di accesso e chiavi API
Notifiche vocali - Invia chiamate vocali automatizzate
Gestione template - Crea e gestisci template WhatsApp
Programmazione - Programmazione avanzata e gestione fusi orari
Gestione errori - Codici di errore completi e strategie di gestione
Migliori pratiche - Linee guida su sicurezza e prestazioni

​Introduzione

​Funzionalità principali:

​📣 Invia notifica WhatsApp

​Endpoint

​Parametri di query

​Header

​📋 Parametri della richiesta

​Parametri obbligatori

​Parametri opzionali

​👥 Singolo vs destinatari multipli

​Usando contact - Invia a una persona

​Usando contacts - Invia a più persone (Invio massivo)

​🔄 Formati della struttura dati

​Struttura annidata (unflatten=false o omesso)

​Struttura piatta (unflatten=true)

​Quando usare ciascun formato

​📚 Documentazione correlata