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