Come implementare un chatbot in un sito web, passo dopo passo
Imparare a implementare un chatbot nei progetti web si riduce a tre parti: una chat box nel browser, un piccolo backend che conserva la tua chiave API e una chiamata a un endpoint compatibile con OpenAI. Questa guida costruisce ogni parte con codice funzionante.
Aggiornato

Punti chiave
- Non chiamare mai l'API dal codice del browser. Tieni la chiave su un server ed esponi il tuo route /api/chat.
- L'API è compatibile con OpenAI, quindi gli SDK standard funzionano dopo aver impostato il base URL e aver usato il modello uncensored.
- Attiva lo streaming delle risposte per rendere la pagina veloce e limita la cronologia sul server.
- Gestisci le risposte 429 e imposta un limite per visitatore, poiché una chiave completa permette 8 richieste parallele.
L'architettura in una foto
Il modo usuale per implementare un chatbot nei progetti web è un relay in tre fasi. Il visitatore digita in una chat box. La tua pagina invia il messaggio al tuo server. Il tuo server chiama l'API del modello con la tua chiave segreta e passa la risposta indietro. Il browser non vede mai la chiave.
Questo è importante perché tutto il JavaScript front-end è pubblico. Se metti la chiave in un tag script, chiunque apra gli strumenti di sviluppo può copiarla e spendere il tuo saldo. Un route backend ti dà anche un unico punto dove aggiungere limiti di richiesta, taglio della cronologia, logging e un controllo dell'età. Per una guida più lunga a una pagina finita, vedi il tutorial della chat web.
Passo 1: ottieni una chiave e testa l'endpoint
Registrati con Google o con email e password, poi richiedi la prova gratuita nella pagina delle chiavi API. La prova è di $0,50 di credito, valida per 7 giorni, una per persona, e non richiede pagamento. Salva la chiave come variabile d'ambiente, non nel codice.
Verifica che funzioni con curl prima di scrivere codice per l'app:
export API_KEY="YOUR_KEY"
curl https://api.uncensoredchatbotapi.com/v1/models -H "Authorization: Bearer $API_KEY"
curl https://api.uncensoredchatbotapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "uncensored", "messages": [{"role": "user", "content": "Say hello in five words."}]}'La prima chiamata elenca i modelli e la seconda restituisce un completamento chat. Se entrambi hanno successo, la chiave e il base URL sono corretti. Un 401 significa che la chiave è errata o manca il prefisso Bearer.
Passo 2: scrivi il route del backend
L'esempio qui sotto usa Node 18 o superiore, Express e il pacchetto ufficiale openai. Installali con npm install express openai e imposta "type": "module" in package.json.
import express from "express";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredchatbotapi.com/v1",
apiKey: process.env.API_KEY,
});
const SYSTEM = "You are a helpful assistant for our website. Keep answers under 150 words.";
const app = express();
app.use(express.json({ limit: "100kb" }));
app.use(express.static("public"));
app.post("/api/chat", async (req, res) => {
const incoming = Array.isArray(req.body.messages) ? req.body.messages : [];
const history = incoming.slice(-10).map((m) => ({
role: m.role === "assistant" ? "assistant" : "user",
content: String(m.content).slice(0, 4000),
}));
try {
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "system", content: SYSTEM }, ...history],
stream: true,
});
res.setHeader("Content-Type", "text/plain; charset=utf-8");
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) res.write(text);
}
} catch (err) {
if (res.headersSent === false) res.status(err.status === 429 ? 429 : 502);
}
res.end();
});
app.listen(3000, () => console.log("Listening on http://localhost:3000"));Tre dettagli fanno il lavoro effettivo qui. Il server ricostruisce la lista dei messaggi da solo, quindi un visitatore non può iniettare un messaggio di sistema falso. Conserva solo gli ultimi 10 messaggi e taglia ciascuno a 4.000 caratteri, il che controlla il costo. E imposta sempre i ruoli esplicitamente, mappando tutto ciò che è sconosciuto a user.
Passo 3: costruisci la chat box
Metti questo in public/index.html. Usa JavaScript puro senza framework, così puoi incollarlo in un template esistente.
<div id="log"></div>
<form id="form">
<input id="input" autocomplete="off" required />
<button>Send</button>
</form>
<script>
const messages = [];
const log = document.getElementById("log");
document.getElementById("form").addEventListener("submit", async (e) => {
e.preventDefault();
const input = document.getElementById("input");
messages.push({ role: "user", content: input.value });
log.insertAdjacentHTML("beforeend", "<p></p>");
log.lastElementChild.textContent = "You: " + input.value;
input.value = "";
const reply = document.createElement("p");
log.appendChild(reply);
const res = await fetch("/api/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ messages }),
});
if (res.ok === false) { reply.textContent = "Busy, please try again in a moment."; return; }
const reader = res.body.getReader();
const decoder = new TextDecoder();
let full = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
full += decoder.decode(value, { stream: true });
reply.textContent = full;
}
messages.push({ role: "assistant", content: full });
});
</script>Usare textContent invece di innerHTML per l'output del modello impedisce alla risposta di iniettare markup nella tua pagina. Mantieni questa abitudine anche quando il modello è ben comportato.
Passo 4: gestisci i limiti e gli errori
Una chiave completa permette 8 richieste parallele e 300 richieste al minuto. Una chiave di prova permette 2 richieste parallele e 60 al minuto. Quando superi il limite, l'API restituisce HTTP 429 con un codice di errore: rate_limited per le richieste al minuto o concurrency per troppe contemporaneamente. In caso di sovraccarico temporaneo restituisce anche 429 con un'intestazione Retry-After: 5.
Seguono due regole pratiche. Primo, riprova il 429 dopo il ritardo con un backoff breve e mostra al visitatore un messaggio amichevole se continua a fallire. Secondo, ricorda che una richiesta streaming occupa il suo slot di concorrenza fino alla fine dello stream. Se dieci visitatori fanno streaming contemporaneamente su una chiave completa, due di loro verranno respinti, quindi aggiungi una piccola coda o un limite per visitatore sul tuo server. Un semplice contatore in memoria basato sull'IP è sufficiente per un sito piccolo.
Le intestazioni di risposta ti aiutano a fare debug: X-Request-Id identifica una chiamata se contatti il supporto, e X-Balance-USD mostra il tuo credito residuo. Il limite del corpo della richiesta è 8 MB, molto al di sopra di ciò di cui ha bisogno una chat, e la finestra di contesto è di 100.000 token.
Punti critici durante il deploy
Il codice sopra funziona su localhost. Questi sono i problemi che si presentano una volta che è su un server reale.
- Proxy di buffering. Alcuni proxy inversi trattengono le risposte in streaming fino al termine della trasmissione, quindi la risposta appare tutta insieme. Se usi nginx, disabilita il buffering delle risposte per il percorso della chat. Testa lo streaming attraverso la stessa catena di proxy che usi in produzione, non solo sul tuo laptop.
- Chiavi nel repository. Tieni la chiave in una variabile d'ambiente o in un archivio dei segreti e aggiungi qualsiasi file env locale alla tua lista di ignore. Se una chiave finisce in un repo pubblico, creane una nuova e smetti di usare quella vecchia.
- Fidarsi del client. Il browser invia la cronologia della chat, quindi un visitatore può modificarla. Ecco perché il server nel passo 2 imposta i ruoli da solo e taglia la lunghezza del messaggio. Non accettare mai un messaggio di sistema dal client.
- Chiamate tra origini diverse. Se la tua pagina e il tuo backend risiedono su domini diversi, il browser bloccherà la richiesta finché il tuo server non invia le intestazioni CORS corrette. Servire entrambi da un'unica origine evita il problema.
- Costi fuori controllo. Un visitatore scriptato può inviare centinaia di messaggi. Conta le richieste per IP o sessione sul server e rifiuta quando il conteggio è troppo alto. Taglia anche la lunghezza del messaggio, come fa l'esempio.
- Markdown e link. I modelli rispondono spesso con elenchi e blocchi di codice. Decidi se renderizzarli o mostrare testo puro, e non inserire mai il testo della risposta come HTML grezzo.
Un ultimo controllo è il layout mobile. La maggior parte del traffico chat sui siti pubblici proviene da telefoni, quindi testa con uno schermo stretto, una tastiera software aperta e una connessione instabile. Se lo stream si interrompe a metà, il visitatore dovrebbe essere in grado di reinviare senza perdere il filo.
Estensione del bot in seguito
Una volta che il gateway di base funziona, lo stesso percorso può fare di più, perché l'API supporta le funzionalità standard di OpenAI. Puoi richiedere un output strutturato con la modalità JSON impostando response_format su {"type": "json_object"} e indicando nel prompt che la risposta deve essere JSON. Questo è adatto a un modulo di contatto che trasforma un messaggio in testo libero in campi come nome, argomento e urgenza.
La chiamata di funzioni permette al modello di chiedere al tuo server di eseguire una funzione, come la ricerca di un ordine o il controllo degli orari di apertura. Passi una lista tools, leggi tool_calls nella risposta, esegui la funzione tu stesso e invii il risultato di nuovo come messaggio con role: "tool". Il modello scrive poi la risposta finale basandosi sui tuoi dati. Questo è come un bot del sito web ottiene informazioni reali invece di indovinare.
Le impostazioni di campionamento sono anche a tua disposizione. Una temperatura più bassa è adatta per help desk fattuali e una più alta è adatta per la narrazione. Aggiungi una modifica alla volta e confronta i risultati sulle stesse cinque domande di test.
Fase 5: modella il bot e vai online
Il prompt di sistema definisce il tuo bot. Digli chi è, di cosa si occupa e quanto dovrebbero essere lunghe le risposte. Se il personaggio ha una personalità, le note su la progettazione della personalità approfondiscono. Poiché il modello è ottimizzato per rispondere senza rifiuti di contenuto per l'uso adulto legale, le protezioni per il tuo pubblico sono tue da scrivere: una conferma dell'età, un link per segnalare e un elenco chiaro di ciò di cui il bot non discuterà. I contenuti sessuali che coinvolgono minorenni non sono mai permessi. Vedi la pagina su l'uso responsabile e le salvaguardie prima del lancio.
Per il costo, paghi $0,15 per 1M di token di input e $0,50 per 1M di token di output. Una risposta con 1.200 token di input e 300 token di output costa $0,00018 più $0,00015, per un totale di $0,00033. Una ricarica di $20 copre oltre 60.000 di queste risposte. Le ricariche vanno da $20 a $500, con un bonus del +5% da $50, +10% da $100 e +15% da $200, pagabili in USDT su TRC20 o USDC su Base. Il credito non scade mai. La pagina dei prezzi contiene i dettagli, e la documentazione elenca tutti i parametri supportati, inclusa la chiamata di funzioni e la modalità JSON.
Prima del lancio, testa con alcune conversazioni lunghe, osserva i log per i 429 e conferma che il tuo server taglia la cronologia. I prompt non sono usati per l'addestramento, ma dovresti comunque dire ai tuoi visitatori cosa conservi.
Altre guide
Domande e risposte
Posso chiamare l'API direttamente dal JavaScript del browser?
Puoi, ma non dovresti. La chiave sarebbe visibile a ogni visitatore. Instrada le richieste attraverso il tuo server e conserva la chiave in una variabile d'ambiente.
Quali linguaggi e SDK funzionano?
Qualsiasi SDK o client HTTP OpenAI. Imposta il base URL su https://api.uncensoredchatbotapi.com/v1, usa la tua chiave come token bearer e imposta il modello su uncensored. Python, Node e curl funzionano tutti.
Lo streaming funziona in un browser?
Sì. L'API effettua lo streaming tramite SSE con stream impostato su true. L'esempio inoltra il testo attraverso il tuo server con fetch e un lettore di stream.
Cosa succede quando superi il limite di richieste?
Ottieni HTTP 429 con il codice rate_limited o concurrency. Attendi e riprova. Per sovraccarico temporaneo l'intestazione Retry-After è di 5 secondi.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.