聊天组件
Integra un widget di live chat nel tuo sito web in pochi minuti. I visitatori possono scrivere direttamente dalla pagina e ricevere risposte in tempo reale — anche con AI se abilitata nel workspace.
Funzionalità
Live Chat
Chat in tempo reale tra visitatori del sito e il tuo team. I messaggi arrivano nell'inbox di NotifyHub come canale web_chat.
Risposte AI
Se l'assistente AI è abilitato nel workspace, il widget risponde automaticamente usando la knowledge base e il system prompt configurato.
Personalizzabile
Colore del brand, posizione (destra/sinistra), messaggio di benvenuto e avatar personalizzabili dalle impostazioni del workspace.
Mobile-ready
Il widget si adatta automaticamente a schermi piccoli. Su mobile occupa la larghezza completa per una migliore esperienza utente.
Anteprima
Ecco come appare il widget sul tuo sito (colori personalizzabili):
Abilita il widget nel workspace
Vai nelle Impostazioni del workspace e abilita la sezione Widget. Configura:
- Messaggio di benvenuto — il primo messaggio mostrato al visitatore
- Colore — il colore principale del widget (default: arancione #f97316)
- Posizione — angolo in basso a destra o sinistra
- Avatar — immagine del profilo mostrata nell'header del widget
Suggerimento: Se l'assistente AI è abilitato nel workspace, il widget risponderà automaticamente ai visitatori con intelligenza artificiale.
Inserisci lo snippet nel sito
Copia e incolla questo codice JavaScript prima della chiusura del tag </body> del tuo sito web. Sostituisci IL-TUO-SLUG con lo slug del tuo workspace.
<script>
(function() {
var s = document.createElement('script');
s.src = 'https://notify.trovido.com/zh/js/notifyhub-widget.js';
s.async = true;
s.onload = function() {
NotifyHubWidget.init({
slug: 'IL-TUO-SLUG',
apiBase: 'https://notify.trovido.com/api/widget'
});
};
document.body.appendChild(s);
})();
</script>
Suggerimento: Lo slug del workspace si trova nella pagina Impostazioni. Ad esempio, se il tuo workspace si chiama "La Ozza B&B", lo slug sarà qualcosa come la-ozza-bb.
Personalizza l'aspetto
Puoi personalizzare il widget direttamente dallo snippet di inizializzazione aggiungendo opzioni:
NotifyHubWidget.init({
slug: 'la-ozza-bb',
apiBase: 'https://notify.trovido.com/api/widget',
// Sovrascritture locali (priorità sulle impostazioni server)
color: '#FF8400', // Colore brand
position: 'right', // 'right' o 'left'
welcomeMessage: 'Ciao!', // Messaggio iniziale
visitorName: 'Ospite', // Nome predefinito visitatore
zIndex: 9999 // z-index del widget
});
Nota: Le opzioni configurate nel workspace (lato server) hanno la precedenza. Le opzioni nello snippet servono come fallback o per test rapidi.
API Reference
Il widget comunica con il backend tramite tre endpoint REST. Puoi usarli anche per integrazioni custom.
GET
/api/widget/config/{slug}
Recupera la configurazione del widget per un workspace.
{
"name": "La Ozza B&B",
"welcome": "Ciao! Come posso aiutarti?",
"color": "#f97316",
"position": "right",
"avatar_url": "https://...",
"ai_enabled": true
}
| Status | Descrizione |
|---|---|
200 | Configurazione del widget |
404 | Workspace non trovato o slug non valido |
403 | Widget disabilitato per questo workspace |
POST
/api/widget/message
Invia un messaggio dal visitatore al workspace. Se l'AI è abilitata, la risposta viene generata automaticamente.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
slug | string | Si | Slug del workspace (max 80 caratteri) |
session | string | Si | ID sessione univoco del visitatore (max 64 caratteri) |
text | string | Si | Testo del messaggio (max 2000 caratteri) |
visitor_name | string | No | Nome del visitatore (default: "Visitatore") |
POST /api/widget/message
Content-Type: application/json
{
"slug": "la-ozza-bb",
"session": "abc123-xyz789",
"text": "Avete disponibilità per il weekend?",
"visitor_name": "Marco"
}
{ "ok": true }
GET
/api/widget/messages/{session}
Recupera i messaggi di risposta (outbound) per una sessione. Usato dal widget per il polling delle risposte.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
slug | query string | Si | Slug del workspace |
after | query string | No | Timestamp ISO 8601 — restituisce solo messaggi successivi |
{
"messages": [
{
"content": "Ciao Marco! Si, abbiamo disponibilità...",
"sender": "ai",
"time": "2026-05-08T14:30:00.000Z"
}
]
}
Rate limit: Il messaggio POST è limitato a 20 richieste/minuto per IP. Gli altri endpoint a 60 richieste/minuto.
Come funziona
Il flusso completo di un messaggio dal widget all'inbox:
POST /api/widget/message
web_chat
GET /api/widget/messages/{session} per mostrare la risposta
Struttura settings JSON
Il widget usa i seguenti campi dal JSON settings del workspace:
{
"widget": {
"enabled": true,
"welcome_message": "Ciao! Come posso aiutarti?",
"color": "#f97316",
"position": "right",
"avatar_url": "https://..."
},
"ai_assistant": {
"enabled": true
}
}
| Campo | Tipo | Default | Descrizione |
|---|---|---|---|
enabled | boolean | false | Abilita/disabilita il widget |
welcome_message | string | null | Primo messaggio mostrato nel widget |
color | string | #f97316 | Colore HEX per header e bottoni |
position | string | right | right o left |
avatar_url | string | null | URL immagine avatar nell'header |
Integrazione WordPress
Se usi WordPress, puoi aggiungere il widget senza toccare codice:
// Aggiungi in functions.php del tuo tema
add_action('wp_footer', function() { ?>
<script>
(function() {
var s = document.createElement('script');
s.src = 'https://notify.trovido.com/zh/js/notifyhub-widget.js';
s.async = true;
s.onload = function() {
NotifyHubWidget.init({
slug: 'il-tuo-slug',
apiBase: 'https://notify.trovido.com/api/widget'
});
};
document.body.appendChild(s);
})();
</script>
<?php });
In alternativa, vai su Aspetto → Widget e aggiungi un blocco "HTML personalizzato" nel footer con lo stesso snippet.
Risoluzione problemi
Il widget non appare
Verifica che il widget sia abilitato nelle impostazioni del workspace. Controlla la console del browser (F12) per eventuali errori di caricamento dello script.
Errore 403 "disabled"
Il widget non è abilitato nel workspace. Vai su Impostazioni → Widget e attiva il toggle.
L'AI non risponde
L'assistente AI deve essere abilitato separatamente nelle impostazioni del workspace (sezione AI). Senza AI, i messaggi appaiono nell'inbox in stato "attesa risposta umana".
Rate limit raggiunto
I messaggi sono limitati a 20/minuto per IP. Questo limite protegge da abusi. In condizioni normali non dovrebbe essere raggiunto.