Manuale dei moduli

Aggiornato il 4 settembre 2026

Un modulo è un'automazione che ti costruisci: QUANDO succede qualcosa, SE valgono certe condizioni, ALLORA il bot fa una o più cose.

Con i moduli si fanno i comandi che ti mancano, le risposte automatiche, i giochi a monete, i saluti agli eventi, i timer, e i collegamenti verso servizi tuoi. Un modulo è dati, mai codice: quello che può fare è l'elenco di azioni qui sotto, e nient'altro. È il motivo per cui puoi costruirci sopra senza poter rompere niente — tuo o di altri.

QUANDO: i sei inneschi

Innesco	Parte quando	Cosa gli dai
Comando	qualcuno scrive `!nome` in chat	il nome (senza `!`) e gli alias
Parola	in un messaggio compare un testo	il testo, e se deve contenerlo, esserlo o iniziare così
Evento	succede qualcosa sul canale	quale evento (sotto)
Timer	ogni tot minuti	i minuti, e se vuoi un minimo di messaggi nuovi
Manuale	solo quando lo lanci tu	niente: si lancia da «Prova» o da fuori
Voce	lo dici a voce mentre streammi	la frase da riconoscere

Gli eventi

Evento	Quando
Nuovo follow	qualcuno inizia a seguirti
Sub / resub	qualcuno si abbona o rinnova
Raid	un altro canale ti manda i suoi spettatori
Bits / cheer	qualcuno manda dei bit
Riscatto punti canale	qualcuno riscatta un premio dei punti Twitch
Primo messaggio di un utente	qualcuno scrive per la prima volta nel tuo canale
Sei andato in live	la diretta comincia
Fine live	la diretta finisce
Gesto webcam (mani/volto)	la webcam riconosce un gesto o un'espressione

Il timer non parla nel vuoto: se chiedi un minimo di messaggi nuovi, il modulo tace quando la chat è ferma. È la differenza fra un promemoria e un bot che parla da solo davanti a nessuno.

SE: le condizioni

Sono tutte facoltative, e si sommano: passano tutte o il modulo non parte.

Condizione	Cosa fa	Limiti
Chi può	da tutti, solo abbonati, solo VIP, solo moderatori	scala: tutti < sub < VIP < mod
Piattaforme	solo Twitch, solo Kick, o dove vuoi	se non scegli, vale ovunque
Solo in diretta	il modulo tace a canale spento	—
Solo offline	il contrario: solo a canale spento	—
Monete richieste	serve almeno quel saldo, ma non si paga	0–1.000.000
Costo	quante monete si pagano per usarlo	0–1.000.000, oppure una variabile
Attesa	quanto aspetta prima di poter ripartire, per tutti	secondi
Attesa a testa	quanto aspetta la stessa persona	0–86.400 secondi
Probabilità	quante volte su cento parte	0–100
Messaggio se non basta	cosa dice a chi non ha abbastanza monete	300 caratteri

In che ordine vengono controllate

L'ordine non è un dettaglio: decide quando si paga.

1	Chi può usarlo
2	La piattaforma
3	Diretta accesa o spenta
4	Monete richieste e costo — qui si controlla, non si paga
5	L'attesa di tutti
6	L'attesa della singola persona
7	Il pagamento: qui le monete escono davvero
8	La probabilità

Quindi si paga dopo le attese e prima del dado: chi gioca paga la giocata anche quando perde — che è come funziona una giocata — ma non paga se il comando era in attesa. Dopo il pagamento hai $costo (quanto è uscito) e $saldo (quanto è rimasto) da usare nei testi.

ALLORA: le quattordici azioni

Si eseguono in fila, fino a otto per modulo. Se una fallisce, le altre vanno avanti lo stesso: un webhook spento non deve spegnere il messaggio in chat.

Azione	Cosa fa	Cosa le dai	Serve
Scrivi in chat	manda un messaggio	il testo (fino a 400 caratteri)	—
Fai partire un effetto	lancia un tuo effetto o suono	quale effetto	un effetto già creato
Dai o togli punti	muove le monete del canale	aggiungi/togli/imposta, a chi, quanto	—
Contatore	tiene un numero che cresce	nome, e se incrementare, azzerare o impostare	—
Crea una clip	salva una clip del momento	un testo da dire (facoltativo)	il permesso clip
Cambia categoria Twitch	cambia il gioco del canale	il gioco, anche da `$args`	il permesso di modifica canale
Cambia titolo stream	cambia il titolo	il testo (fino a 140 caratteri)	il permesso di modifica canale
Metti una canzone in coda	aggiunge un brano su Spotify	il brano, anche da `$args`	add-on Musica e Spotify collegato
Annuncio in chat (/announce)	un messaggio evidenziato in chat	il testo e il colore	il permesso annunci
Shoutout (banner)	lo shoutout ufficiale di Twitch	chi, o il nome dopo il comando, o chi ha raidato	il permesso shoutout
Mostra testo sull'overlay	scrive a schermo nella diretta	il testo e per quanto	l'overlay in scena
Timeout in chat	mette in pausa chi ha scritto	i secondi	il permesso di moderazione
Aspetta	una pausa prima dell'azione dopo	i secondi (fino a 30)	—
Chiama un webhook	manda i dati a un indirizzo tuo	l'URL, e se usare la risposta	un servizio tuo

Dai o togli punti

È l'azione che trasforma un modulo in un gioco. Aggiungi e togli spostano, imposta mette una cifra esatta.

Il destinatario può essere chi ha scritto, il nome dopo il comando, uno a caso fra chi ha parlato di recente, o un nome fisso. La quantità può essere un numero o una variabile: $random(10,50), $arg1.

Dopo, $mossa dice quante monete si sono mosse davvero e $bersaglio su chi. Sono la stessa cifra per tutte le azioni che seguono: senza, un furto toglierebbe una somma alla vittima e ne darebbe un'altra al ladro.

Chiama un webhook

Manda il contesto in JSON a un indirizzo tuo. Se rispondi con {"reply": "testo"} e hai spuntato «usa la risposta», il bot scrive quel testo in chat — con le variabili già espanse.

Accetta solo http e https, e non può puntare dentro una rete privata: gli indirizzi interni sono rifiutati sia scritti direttamente sia dopo aver risolto il nome, e un redirect non aggira il controllo. Cinque secondi di tempo, risposta letta fino a 10 KB.

Il ramo ALTRIMENTI

È quello che succede quando il dado non passa. Ha senso solo con una probabilità sotto il 100%: il pannello non lo lascia salvare altrimenti, perché un modulo che sembra fare due cose e ne fa una sola è peggio di un errore.

Le azioni del ramo «altrimenti» sono le stesse quattordici, e il costo è già stato pagato: la giocata persa può raccontarlo con $costo e $saldo.

Le variabili

Si scrivono nei testi e diventano quello che valgono. Una variabile che non esiste sparisce, non lascia scritto il suo nome. Non c'è nessun modo di eseguire codice: sono sostituzioni, e basta.

Chi scrive e cosa dice

`$user`	chi ha scritto
`$touser`	il nome scritto dopo il comando (o chi scrive, se manca)
`$target`	come `$touser`
`$args`	tutto quello che c'è dopo il comando
`$arg1`	la prima parola dopo il comando (poi `$arg2`, `$arg3`…)
`$canale`	il nome del tuo canale

La diretta adesso

`$uptime`	da quanto sei in diretta (vuoto se offline)
`$gioco`	la categoria attuale
`$titolo`	il titolo attuale
`$spettatori`	quanti stanno guardando ora

Le persone

`$followage`	da quanto ti segue chi scrive, o il nome dopo il comando
`$ore`	ore guardate sul tuo canale (anche `$oreguardate`, `$watchtime`)
`$chattercaso`	uno a caso fra chi ha scritto di recente
`$cita`	una citazione a caso fra quelle salvate
`$giocotarget`	l'ultima categoria di chi nomini dopo il comando
`$titolotarget`	l'ultimo titolo di chi nomini dopo il comando

Le monete

`$punti`	quante ne ha chi scrive
`$punti(nome)`	quante ne ha un altro
`$monete`	come si chiama la tua moneta
`$posizione`	in che posizione è chi scrive
`$top(3)`	i primi tre, già scritti
`$costo`	quanto è costato questo modulo
`$saldo`	quanto è rimasto dopo il pagamento
`$mossa`	quante monete ha mosso l'ultima azione punti
`$bersaglio`	su chi le ha mosse

Quando l'innesco è un evento

`$raider`	chi ti ha raidato
`$viewers`	quanti ne ha portati
`$mesi`	da quanti mesi è abbonato
`$bits`	quanti bit ha mandato
`$premio`	quale premio ha riscattato
`$gesto`	il gesto riconosciuto dalla webcam
`$emozione`	l'espressione riconosciuta

Data e ora

`$data`	la data di oggi
`$ora`	che ore sono
`$giorno`	che giorno della settimana è

Le funzioni

`$random(1,100)`	un numero fra due
`$random(6)`	un numero da 1 a 6
`$decimale(1,2)`	un numero con la virgola
`$misura(1,50,cm)`	un numero con l'unità che vuoi
`$pick(a\|b\|c)`	una a caso fra queste (anche `$scegli`)
`$count(nome)`	quanto vale un contatore
`$titolo($args)`	cambia il titolo mentre scrivi il messaggio
`$categoria($args)`	cambia la categoria mentre scrivi il messaggio

Quelle a caso

Danno un valore nuovo a ogni volta che compaiono: due $dado nella stessa frase danno due numeri diversi.

`$dado`	da 1 a 6
`$moneta`	testa o croce
`$sino`	sì o no
`$random` `$numero`	da 0 a 100
`$percentuale`	da 0% a 100%
`$livello`	da 1 a 100
`$altezza`	da 1,40 m a 2,10 m
`$peso`	da 40 a 130 kg
`$lunghezza`	da 1 a 30 cm
`$grandezza`	da 1 a 50 cm
`$eta`	da 1 a 99 anni
`$temperatura`	da -10 a 45 °C
`$velocita`	da 1 a 320 km/h
`$distanza`	da 1 a 1000 km
`$soldi` `$euro`	da 0 a 100.000 €
`$colore`	un colore
`$animale`	un animale
`$emoji`	una emoji

Tre esempi

Un comando con una risposta viva

QUANDO   comando  !abbraccia
ALLORA   scrivi in chat
         $user abbraccia $touser per $random(3,30) secondi.

Un saluto ai raid, con lo shoutout

QUANDO   evento  Raid
ALLORA   scrivi in chat
         Benvenuti! $raider è arrivato con $viewers persone.
ALLORA   shoutout  (a chi ha raidato)

Una scommessa

QUANDO   comando  !scommetti
SE       costo $arg1 · probabilità 45
ALLORA   dai punti  a chi scrive  +$arg1
ALLORA   scrivi in chat
         $user punta $costo $monete e vince! Ora ne ha $punti.
ALTRIMENTI  scrivi in chat
         $user punta $costo $monete e perde tutto. Ne restano $saldo.

Nel terzo: il costo è la cifra scritta da chi gioca, si paga sempre, e la vincita raddoppia perché la puntata era già uscita.

I comandi pronti, e chi vince

Il bot porta con sé una quarantina di comandi già fatti — giochi, sorteggi, ore guardate, shoutout, VIP, sondaggi, musica. In Comandi, in fondo alla scheda, ci sono tutti: ognuno si spegne, si rinomina e si può riservare ad abbonati, VIP o moderatori.

Rinominare sostituisce: se chiami !slot in un altro modo, il nome di serie smette di rispondere. Un comando ha un nome, e lo scegli tu.

Due comandi non possono chiamarsi allo stesso modo: il secondo non partirebbe mai. Se ci provi, il pannello rifiuta e ti dice quale nome è già preso.

E la regola di sempre resta: un comando tuo con lo stesso nome vince su quello pronto. Non devi spegnere niente per sovrascrivere un comando di serie — basta crearne uno tuo che si chiami così.

Limiti e sicurezza

Otto azioni per modulo, e la fila si ferma lì.
Un messaggio in chat arriva a 400 caratteri, un titolo a 140.
Una pausa può durare al massimo 30 secondi.
Un'azione punti può muovere al massimo un milione di monete per volta.
I webhook non possono raggiungere una rete privata, non seguono i redirect e hanno cinque secondi di tempo.
Le variabili sono sostituzioni di testo: nessun codice viene eseguito, né tuo né di chi scrive in chat.
Il bot non innesca sé stesso: quello che dice non fa ripartire i tuoi moduli.

Lanciare un modulo da fuori

Ogni canale ha una chiave (la vede solo il proprietario, mai un moderatore). Con quella, un programma tuo — un'estensione, un pulsante della tastiera fisica, uno script — può far scrivere il bot o lanciare un modulo.

Si manda una POST all'indirizzo del canale con la chiave nell'intestazione Authorization, e nel corpo cosa fare: un messaggio, un effetto, o un modulo. Trenta richieste al minuto. Una chiave sbagliata riceve un 404, senza dire perché.

Quando un modulo non parte

Controlla l'ordine delle condizioni. Se c'è un'attesa in corso il modulo tace prima di pagare: sembra rotto e invece sta aspettando.
La probabilità è quella che sembra? Con 20 su 100, quattro volte su cinque non succede niente — e senza il ramo «altrimenti» quel silenzio è indistinguibile da un guasto.
Ti manca un permesso. Categoria, titolo, annunci, shoutout e clip li fa Twitch: se il permesso non c'è, il bot lo dice in chat una volta e va avanti. Si riautorizza dalla dashboard.
Hai un comando pronto con lo stesso nome? Vince il tuo, sempre. Se volevi quello pronto, cambia nome al tuo.
Provalo. Il tasto «Prova» esegue il modulo saltando tutte le condizioni: se funziona lì, il problema è in una condizione, non in un'azione.