Progetti
Creazione dei progetti, chiavi, domini autorizzati, ambienti, pubblicazione, clonazione e limiti per piano.
Un progetto è l'unità di distribuzione della piattaforma: raccoglie modello AI, avatar, knowledge base, strumenti, flussi e webhook, e li espone su uno o più canali attraverso una chiave di progetto.
Un progetto per esperienza, non per sito
Crea un progetto per ogni esperienza distinta: assistenza clienti, prenotazioni, area riservata. Più siti che condividono la stessa esperienza possono usare lo stesso progetto con domini autorizzati diversi.
Prima di iniziare
- Almeno un modello AI configurato
- Ruolo con permesso identity:projects:write
- Elenco dei domini su cui pubblicherai il widget
Creare un progetto
Nome e slug
Inserisci il nome, ad esempio Acme S.r.l. — Assistenza.
Lo slug viene proposto automaticamente (acme-srl) ed è immutabile dopo la creazione:
compare negli URL della Console e nei log.
Ambiente iniziale
Ogni progetto nasce con i tre ambienti development, staging e production.
Le configurazioni sono indipendenti; le chiavi sono diverse per ciascun ambiente.
Componenti
Seleziona modello AI e avatar. La knowledge base e gli strumenti possono essere collegati in un secondo momento.
Domini autorizzati
Inserisci i domini su cui il widget potrà caricarsi. Senza questo passaggio il widget viene bloccato dal browser.
Crea e pubblica
Seleziona Crea progetto, collauda in development, poi Pubblica su production.
Chiave di progetto
La chiave identifica il progetto e l'ambiente nelle chiamate dal browser.
Ha il prefisso bp_proj_ seguito da 16 caratteri esadecimali.
Chiave di progetto — produzione
bp_proj_7f3a9c21Da inserire nell attributo data-project-key dello script BluBot.
| Caratteristica | Dettaglio |
|---|---|
| Formato | bp_proj_ + 16 caratteri esadecimali |
| Visibilità | Pubblica: è esposta nel codice sorgente della pagina |
| Ambito | Un ambiente di un progetto |
| Protezione | Domini autorizzati e limiti di frequenza |
| Rotazione | Immediata, con periodo di grazia configurabile |
La chiave di progetto non è un segreto
La chiave è visibile a chiunque ispezioni la pagina. Non sostituisce l'autenticazione: la protezione reale è data dall'allowlist dei domini e dai limiti di frequenza. Per le chiamate server-to-server usa una API key, descritta in API.
Rotazione della chiave
- Seleziona Ruota chiave e imposta un periodo di grazia (fino a 72 ore).
- Aggiorna lo snippet su tutti i siti.
- Verifica nei log che il traffico sulla chiave precedente sia a zero.
- Seleziona Revoca chiave precedente.
Domini autorizzati
L'allowlist controlla da quali origini il widget può inizializzarsi.
Le richieste provenienti da origini non elencate ricevono 403 origin_not_allowed.
| Voce | Corrisponde a | Non corrisponde a |
|---|---|---|
https://www.acme.it | Solo quell'origine esatta | https://acme.it |
https://*.acme.it | Tutti i sottodomini di primo livello | https://a.b.acme.it |
http://localhost:3000 | Sviluppo locale | Altre porte |
capacitor://localhost | App mobile ibride | — |
Regole applicate:
- Il protocollo è obbligatorio;
httpsè richiesto inproduction. - Il carattere jolly è ammesso solo come primo segmento.
- Massimo 50 voci per ambiente.
- Le modifiche sono attive entro 60 secondi (propagazione CDN).
Errore frequente
Inserire acme.it senza protocollo, oppure dimenticare la variante con e senza www.
Aggiungi entrambe le forme se il sito è raggiungibile in entrambi i modi.
Ambienti
| Ambiente | Scopo | Chiave | Pubblicazione | Dati |
|---|---|---|---|---|
development | Prove e sviluppo | bp_proj_dev_... | Non richiesta | Conversazioni cancellate dopo 7 giorni |
staging | Collaudo e approvazione | bp_proj_stg_... | Richiesta | Conservazione 30 giorni |
production | Pubblico | bp_proj_7f3a9c21 | Richiesta | Politica di conservazione del tenant |
Il selettore in alto a destra cambia l'ambiente su cui stai lavorando. Il colore della barra superiore indica l'ambiente corrente: grigio, ambra, blu.
Non collaudare in produzione
Le conversazioni di prova in production entrano nelle statistiche e nei webhook.
Usa development, oppure marca la sessione come test con BluBot.setUser.
Associazione dei componenti
| Componente | Cardinalità | Effetto se assente |
|---|---|---|
| Modello AI | Esattamente 1 | Il progetto non risponde |
| Avatar | 0 o 1 | Si applica l'avatar predefinito del tenant |
| Knowledge base | 0 o più | Risposte basate solo sul prompt di sistema |
| Strumenti | 0 o più | Nessuna azione sui sistemi esterni |
| Flussi | 0 o più | Solo generazione libera del modello |
| Webhook | 0 o più | Nessuna notifica ai sistemi esterni |
Quando colleghi più knowledge base, la ricerca avviene su tutte le sorgenti e i risultati sono ordinati per rilevanza. Puoi assegnare un peso a ciascuna sorgente.
Pubblicazione e versionamento
La pubblicazione crea uno snapshot immutabile dell'intera configurazione: prompt, avatar, flussi, widget, mappatura degli strumenti.
Verifica le differenze
Il pannello mostra il confronto tra la configurazione corrente e l'ultima pubblicata.
Inserisci una nota di rilascio
Obbligatoria in production. Esempio: "Aggiunto flusso preventivi, temperature 0.3".
Pubblica
La propagazione richiede fino a 60 secondi. Le sessioni in corso terminano con la versione precedente.
Verifica
Apri il sito in finestra anonima e collauda tre percorsi principali.
Rollback
Seleziona una versione precedente e conferma Ripristina. Il ripristino è immediato e viene registrato nell'audit log. Le ultime 50 versioni restano disponibili.
Clonazione
| Elemento | Clonato | Nota |
|---|---|---|
| Modello AI e prompt | Sì | Riferimento allo stesso modello |
| Avatar e messaggi | Sì | — |
| Flussi e widget | Sì | — |
| Strumenti | Sì | Le credenziali vanno reinserite |
| Knowledge base | Solo il collegamento | I documenti non vengono duplicati |
| Domini autorizzati | No | Da inserire manualmente |
| Chiavi di progetto | No | Generate nuove |
| Conversazioni e statistiche | No | — |
La clonazione è il modo consigliato per creare un progetto gemello destinato a un secondo marchio o a un secondo mercato.
Archiviazione
Un progetto archiviato smette di rispondere: le chiamate ricevono
410 project_archived. I dati restano consultabili e il progetto non conta
sul limite del piano.
| Stato | Risponde | Conta sul piano | Dati consultabili |
|---|---|---|---|
| Attivo | Sì | Sì | Sì |
| Sospeso | No | Sì | Sì |
| Archiviato | No | No | Sì, in sola lettura |
| Eliminato | No | No | No, dopo 30 giorni di ripensamento |
Eliminazione definitiva
L'eliminazione rimuove conversazioni, statistiche e configurazioni al termine dei 30 giorni di ripensamento. L'operazione non è reversibile. Esporta i dati prima di procedere: vedi Conformità.
Limiti per piano
| Limite | Starter | Business | Enterprise |
|---|---|---|---|
| Progetti attivi | 1 | 10 | Illimitati |
| Domini per ambiente | 3 | 25 | 50 |
| Ambienti | 2 | 3 | 3 + personalizzati |
| Versioni conservate | 10 | 50 | 200 |
| Knowledge base per progetto | 1 | 5 | 20 |
| Strumenti per progetto | 3 | 25 | 100 |
| Webhook per progetto | 2 | 10 | 50 |
| Messaggi mensili inclusi | 2.000 | 25.000 | Da contratto |
Il piano attivo è visibile nella sezione seguente.
Gestione via API
/identity/v1/projectsBearer JWTCrea un nuovo progetto nel tenant corrente.
/identity/v1/projects/{projectId}Bearer JWTRestituisce configurazione, ambienti e chiavi del progetto.
/identity/v1/projects/{projectId}/publishBearer JWTPubblica la configurazione corrente sull ambiente indicato.
{
"name": "Acme S.r.l. — Assistenza",
"slug": "acme-srl",
"model_id": "mdl_4b81c6de92f14aa7",
"avatar_id": "avt_2e9d5741bc634f80",
"allowed_origins": ["https://www.acme.it", "https://*.acme.it"]
}Passi successivi
- Installazione di BluBot — pubblica il widget sul sito.
- Knowledge base — dai contenuti all'assistente.
- Webhook — notifica i tuoi sistemi.