Installare su TYPO3

Aggiungi il widget di chat botts.ai al tuo sito TYPO3 con poche righe di TypoScript nel backend, senza installare un'estensione.

Questa guida aggiunge a un sito TYPO3 il widget di chat di un deployment botts.ai di tipo sito web. Usa TypoScript, la configurazione di TYPO3: poche righe nel campo Setup del record TypoScript del tuo sito fanno caricare a TYPO3 lo script del widget in ogni pagina, subito prima del tag di chiusura </body>. I passaggi descrivono TYPO3 v14 LTS; dove TYPO3 v13 è diverso, lo trovi indicato.

Prima di iniziare

Ti servono:

• Accesso da amministratore al backend TYPO3 del tuo sito.
• Niente da comprare: TYPO3 è un software open source gratuito e non serve nessuna estensione.
• Il codice di incorporamento del tuo deployment sito web. In botts.ai apri Agenti, scegli il tuo agente, passa alla scheda Implementa e apri il deployment Sito Web. La sezione Installazione in fondo all'editor mostra il codice con un pulsante per copiarlo. Non hai ancora un deployment sito web? Vedi Deployment.

Il codice di incorporamento è fatto così, con la chiave del tuo deployment al posto di YOUR_API_KEY:

<script async src="https://api.botts.ai/widget/chat-widget.js?key=YOUR_API_KEY"></script>

In TYPO3 non incolli il codice di incorporamento così com'è, ma queste righe, che caricano lo stesso script. Sostituisci YOUR_API_KEY con la chiave del tuo codice di incorporamento: i caratteri dopo key=, fino alle virgolette di chiusura.

# botts.ai chat widget
page.includeJSFooter.botts = https://api.botts.ai/widget/chat-widget.js?key=YOUR_API_KEY
page.includeJSFooter.botts.async = 1
page.includeJSFooter.botts.external = 1
page.includeJSFooter.botts.excludeFromConcatenation = 1
page.includeJSFooter.botts.disableCompression = 1

Le ultime tre righe impediscono a TYPO3 v13 e precedenti di unire o comprimere lo script, cosa che bloccherebbe il widget. TYPO3 v14 le ignora, quindi le stesse righe funzionano in entrambe le versioni.

Molti siti TYPO3 sono realizzati da un'agenzia che tiene il TypoScript in file (un site package) invece che nel backend. Se un'agenzia o uno sviluppatore si occupa del tuo sito, non modificarlo tu: manda loro queste righe, oppure vedi Inviare alla tua agenzia web.

Passaggio 1: Accedi al backend di TYPO3

Apri tuo-dominio.ch/typo3 e accedi. Sostituisci tuo-dominio.ch con l'indirizzo del tuo sito. Alcuni siti usano un altro indirizzo per il backend; la tua agenzia o il tuo hosting lo conoscono.

Passaggio 2: Apri il modulo TypoScript

Nel menu a sinistra vai su Sites → TypoScript (in italiano Siti Web → TypoScript). In TYPO3 v13 la voce si chiama Site Management → TypoScript (Gestione Sito → TypoScript). Poi clicca sulla pagina principale del tuo sito nell'albero delle pagine: la pagina più in alto, con l'icona del globo.

Passaggio 3: Scegli «Edit TypoScript Record»

Nel menu in alto nel modulo scegli Edit TypoScript Record (modifica record TypoScript). Ora vedi il record TypoScript del tuo sito, con le righe Title, Description, Constants e Setup (con il backend in italiano: Titolo, Descrizione, Costanti e Configurazione).

Se la pagina dice TypoScript settings have been implicitly generated from site sets includes (in italiano «Le impostazioni TypoScript sono state generate implicitamente dalle dipendenze incluse») e non c'è nessun pulsante Setup (Configurazione), il tuo sito carica il TypoScript da file. Continua con Se il tuo sito usa i site set.

Passaggio 4: Incolla le righe alla fine di Setup

Clicca su Setup (Configurazione). Clicca alla fine dell'ultima riga nel campo, premi Invio per iniziare una nuova riga e incolla le righe qui sopra, con la tua chiave. Lascia le righe esistenti come sono.

Passaggio 5: Salva le modifiche

Clicca su Save (Salva) in alto nel modulo.

Passaggio 6: Svuota le cache del frontend

Clicca sull'icona del fulmine nella barra in alto e scegli Flush frontend caches (Svuota le cache del frontend). TYPO3 tiene in cache le pagine già pronte; così le ricrea con il widget.

Passaggio 7: Controlla il widget sul sito

Apri il tuo sito pubblico in una finestra privata, ricarica la pagina e attendi un momento. Il pulsante della chat compare in basso a destra, o dove l'hai posizionato nell'editor del widget. Aprilo e invia una domanda di prova. Controlla anche una sottopagina e la visualizzazione sullo smartphone.

Se il tuo sito usa i site set

I siti TYPO3 più recenti spesso caricano il TypoScript dai site set, cioè da file in un site package. Al passaggio 3 non hanno un campo Setup da modificare. Se un'agenzia o uno sviluppatore si occupa del sito, manda loro le righe qui sopra, così le aggiungono al site package.

Se gestisci tu il sito e vuoi restare nel backend, crea invece un piccolo record TypoScript sulla pagina principale:

1. Nel menu a sinistra vai su Content → Records (Contenuto → Record; TYPO3 v13: Web → List, Web → Lista) e clicca sulla pagina principale del tuo sito nell'albero delle pagine.
2. Clicca su Create new record (crea nuovo record) e poi su TypoScript record (Record TypoScript).
3. Inserisci un titolo come botts.ai widget, incolla le righe nel campo Setup (Configurazione) e clicca su Save (Salva). Lascia le altre schede come sono.
4. Svuota la cache del frontend come al passaggio 6 e controlla il sito come al passaggio 7.

TYPO3 applica questo record in aggiunta al TypoScript dei tuoi site set.

Se il widget non compare

1. Controlla che le righe siano nel campo Setup (Configurazione) del record TypoScript sulla pagina principale, che tu abbia salvato e svuotato la cache del frontend.
2. Controlla la chiave nella prima riga page.includeJSFooter.botts: il segnaposto YOUR_API_KEY va sostituito con la tua chiave, senza spazi né virgolette.
3. Controlla che TYPO3 usi le righe: nel modulo TypoScript scegli Active TypoScript (TypoScript attivo) e cerca includeJSFooter sotto page. Se l'oggetto pagina del tuo sito non si chiama page, chiedi a chi ha configurato il sito.
4. Svuota le altre cache. La cache del tuo hosting o una CDN davanti al sito possono continuare a servire la pagina senza widget.
5. Prova in una finestra privata senza ad blocker. Se il banner dei cookie o lo strumento di consenso blocca gli script, controllane la configurazione. Se il tuo sito invia una Content Security Policy, cosa che TYPO3 può fare, deve consentire api.botts.ai.
6. Controlla che la chiave appartenga al deployment giusto e che il deployment sia attivo nella scheda Implementa.

Modificare o rimuovere il widget

Colori, testi, il launcher e tutte le altre impostazioni del widget si modificano nell'editor di botts.ai. Il tuo sito le riprende senza nessuna modifica in TYPO3. Devi cambiare le righe solo se cambia la chiave del deployment: in quel caso sostituisci la chiave nella prima riga page.includeJSFooter.botts.

Per rimuovere il widget, cancella le righe botts.ai (il commento e tutte le righe che iniziano con page.includeJSFooter.botts) dal campo Setup (Configurazione), salva e svuota di nuovo la cache del frontend.

Altro aiuto

• Documentazione TYPO3: TypoScript backend module (in inglese)
• Riferimento TypoScript: includeJSFooter (in inglese)
• I passaggi generali per qualsiasi sito: Codice di incorporamento

Ultimo aggiornamento: 4 ottobre 2026