Un widget è un componente interattivo incorporato direttamente in un messaggio del bot: un codice promozionale con un pulsante di copia, un timer di countdown, un tracker dello stato dell'ordine, un quiz o un calendario per selezionare data e ora. Quando un cliente interagisce con un widget, il bot aggiorna lo stesso messaggio sul posto — senza inviare nuovi messaggi o mostrare un'etichetta "modificato".

Codice promozionale

Ci sono due modi per inviare un widget:

Modello pronto — una singola riga nel Calcolatore. Il layout e la funzionalità sono già implementati.
Widget personalizzato — scrivi il tuo codice HTML (o chiedi a Mavi di crearlo) e gestisci le interazioni utilizzando i blocchi del flusso del bot.


Messenger	Solo Telegram
Tipo di chat	Solo chat private tra un cliente e un bot
Non supportato	Gruppi, canali, Telegram Business
App Telegram	Richiede una versione recente di Telegram. Le versioni precedenti mostrano un avviso "Messaggio non supportato" e la didascalia
Inoltro	I widget non possono essere inoltrati o copiati

I widget non supportano campi di input di testo o tastiere. I clienti possono interagire solo toccando. Se hai bisogno che i clienti inseriscano testo, usa una domanda normale del bot o una Web App.

I widget non vengono visualizzati nella finestra di test del bot nella dashboard perché non è Telegram. Testa i widget direttamente in Telegram inviando un messaggio al tuo bot.

Modelli Pronti

Tutti i modelli vengono inviati utilizzando una singola funzione:

tg_send_widget(platform_id, template, params, caption)

Parametro	Descrizione
`platform_id`	ID del destinatario. Per il cliente corrente, usa la variabile `platform_id`
`template`	Nome del modello: `promo`, `timer`, `order_status`, `faq`, `quiz`, `calendar`
`params`	Dizionario contenente le impostazioni del modello
`caption`	Testo visualizzato sotto il widget. I clienti lo vedono anche nell'elenco chat, nelle notifiche e nelle versioni precedenti di Telegram, quindi dovrebbe essere significativo da solo

La funzione restituisce la risposta dell'API di Telegram. L'ID del messaggio inviato è disponibile in response['result']['message_id']. Salvalo se prevedi di aggiornare il widget in seguito.

Se la funzione restituisce testo invece di una risposta Telegram, si è verificato un errore: modello sconosciuto, parametro non valido o mancante, o widget che supera il limite di dimensione. Il testo dell'errore spiega cosa è andato storto.

Come Costruire i Parametri

Crea un dizionario e assegna ogni parametro su una riga separata:

p = {}
p["code"] = "WIDGET10"
p["title"] = "Il tuo codice promozionale"
p["note"] = "10% di sconto su qualsiasi ordine"
w = tg_send_widget(platform_id, "promo", p, "Il tuo codice promozionale WIDGET10 — 10% di sconto")

Inserisci il codice nel campo Calcolatore del blocco. Lo screenshot mostra un blocco Condizione di Avvio che invia un widget di stato dell'ordine quando il cliente invia la frase "widget ordine".

Widget nel costruttore del bot

Nel blocco che invia il widget, di solito imposti il campo di risposta su #{none}. Il blocco non invia un messaggio di testo separato perché la didascalia del widget funge da testo del messaggio.

Lingua

I modelli includono testo dell'interfaccia integrato, come etichette dei pulsanti, nomi di mesi e giorni della settimana, "Tempo scaduto" e altri messaggi.

La lingua predefinita in Mavibot è l'inglese (en).

Per usare un'altra lingua, specifica il parametro lang:

p["lang"] = "de"

Lingue supportate:

ru, en, de, es, fr, pt, tr, uk, kk, ms, th, ar.

I testi che fornisci tu stesso — titoli, domande, passaggi e didascalie — vengono visualizzati esattamente come inseriti e non vengono tradotti automaticamente.

Codice Promozionale — `promo`

Mostra un codice promozionale con un pulsante che lo copia con un tocco.

Codice promozionale

Parametro	Descrizione
`code`	Codice promozionale. Obbligatorio
`title`	Testo visualizzato sopra il codice
`note`	Testo visualizzato sotto il codice, come una data di scadenza
`button`	Etichetta del pulsante. Predefinito: "Copia codice promozionale"
`used_text`	Testo visualizzato quando il codice è contrassegnato come usato

p = {}
p["code"] = "WIDGET10"
p["title"] = "Il tuo codice promozionale"
p["note"] = "10% di sconto su qualsiasi ordine"
p["button"] = "Copia codice"
w = tg_send_widget(platform_id, "promo", p, "Il tuo codice promozionale WIDGET10 — 10% di sconto")
client.promo_widget_id = w['result']['message_id']

Per contrassegnare il codice come usato, che lo barrato e rimuove il pulsante:

p = {}
p["used"] = 1
t = tg_edit_widget_data(platform_id, client.promo_widget_id, p)

Timer di Countdown — `timer`

Mostra un conto alla rovescia fino a una data e ora specificate.

Il conto alla rovescia viene eseguito sul dispositivo del cliente. Il bot non è coinvolto nell'aggiornamento del timer.

Timer di countdown

Parametro	Descrizione
`until`	Data e ora target nel formato `"DD.MM.YYYY HH:MM"`, usando il fuso orario del progetto
`seconds`	In alternativa, il numero di secondi dal momento in cui il widget viene inviato
`title`	Intestazione del timer. Predefinito: "L'offerta scade tra"
`done`	Testo visualizzato quando il conto alla rovescia termina
`text`	Testo visualizzato sotto il conto alla rovescia
`button`, `url`	Etichetta del pulsante e URL di destinazione (solo `https://`)
`hide_button`	Imposta a `1` per nascondere il pulsante quando il conto alla rovescia termina

Devi fornire o until o seconds.

p = {}
p["seconds"] = 7200
p["title"] = "L'offerta scade tra"
p["button"] = "Visita il sito"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "L'offerta scade tra 2 ore")

Quando il conto alla rovescia raggiunge lo zero, nessun messaggio o callback viene inviato al bot. Se il bot deve eseguire un'azione quando l'offerta scade, usa una connessione timer regolare nel flusso del bot.

Stato Ordine — `order_status`

Mostra un elenco di fasi dell'ordine con la fase corrente evidenziata.

Il bot può aggiornare la fase sul posto, quindi il cliente vede sempre lo stesso messaggio.

Stato ordine: prima fase

Parametro	Descrizione
`title`	Titolo del widget
`steps`	Elenco delle fasi, da 1 a 12. Predefinito: accettato, in preparazione, consegnato al corriere, in viaggio, consegnato
`step`	Numero della fase corrente, a partire da 1
`text`	Testo visualizzato sotto le fasi

Invio del widget:

p = {}
p["title"] = "Stato ordine"
p["steps"] = ["Accettato", "In preparazione", "Consegnato"]
p["step"] = 1
p["text"] = "Il tuo ordine è stato accettato ed è in preparazione"
w = tg_send_widget(platform_id, "order_status", p, "Il tuo ordine")
client.order_widget_id = w['result']['message_id']

Passa alla fase successiva da qualsiasi altro blocco, ad esempio quando cambia la fase di una trattativa, un manager invia un comando o un timer si attiva:

p = {}
p["step"] = 2
p["text"] = "Il tuo ordine è in preparazione e sarà consegnato al corriere a breve"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

Stato ordine: seconda fase

La didascalia sotto il widget non cambia quando la fase viene aggiornata. Usa una didascalia neutra come "Il tuo ordine" invece di "Stato: Accettato".

Domande Frequenti — `faq`

Mostra un elenco di domande. I clienti possono toccare una domanda per espandere la risposta.

Widget FAQ

Parametro	Descrizione
`title`	Titolo del widget
`items`	Elenco di coppie domanda-risposta. Obbligatorio

p = {}
p["title"] = "Domande Frequenti"
p["items"] = [["Come posso pagare?", "Puoi pagare con carta. Un link di pagamento verrà inviato in questa chat."], ["Quanto tempo richiede la consegna?", "La consegna di solito richiede 1–2 giorni in zona e 3–7 giorni a livello nazionale."], ["Posso restituire un articolo?", "Sì, entro 14 giorni."]]
w = tg_send_widget(platform_id, "faq", p, "Risposte alle domande frequenti")

Il testo viene visualizzato come testo semplice. I tag HTML e altri markup non vengono elaborati.

Quiz e Sondaggio — `quiz`

Mostra domande con risposte a scelta multipla, una domanda alla volta.

Se vengono specificate risposte corrette, il widget funziona come un quiz e calcola un punteggio. Senza risposte corrette, funziona come un sondaggio.

Domanda del quiz

Parametro	Descrizione
`title`	Intestazione visualizzata sopra le domande
`questions`	Elenco delle domande. Obbligatorio
`retry`	Imposta a `1` per visualizzare un pulsante "Riprova" alla fine
`callback`	Testo di callback personalizzato invece di `widget_quiz_finished`

Ogni domanda è un dizionario contenente:

q — testo della domanda
options — opzioni di risposta
correct — risposta corretta, specificata dal suo indice basato su 1 o dal testo esatto

p = {}
p["title"] = "Quiz: Metti alla prova le tue conoscenze"
p["retry"] = 1
p["questions"] = [{"q": "Quanto fa 2 + 2?", "options": ["3", "4", "5"], "correct": 2}, {"q": "Qual è la capitale della Francia?", "options": ["Londra", "Parigi", "Berlino"], "correct": "Parigi"}]
w = tg_send_widget(platform_id, "quiz", p, "Fai questo quiz di due domande!")

Per creare un sondaggio senza punteggio, ometti correct da ogni domanda.

Le risposte corrette vengono verificate dalla piattaforma e non vengono inviate al dispositivo del cliente.

Cosa Riceve il Flusso del Bot

Le risposte alle singole domande non vengono inviate alla conversazione.

Quando il cliente risponde all'ultima domanda, il bot riceve il callback widget_quiz_finished e vengono popolate le seguenti variabili:

Variabile	Valore
`widget_quiz_score`	Numero di risposte corrette; vuoto per i sondaggi
`widget_quiz_total`	Numero totale di domande
`widget_quiz_answers`	Indici delle opzioni selezionate, ad esempio `[2,2]`

Per elaborare il risultato, crea una connessione dal blocco che ha inviato il quiz o usa un blocco Condizione di Avvio con la condizione widget_quiz_finished.

Esempio di risposta:

Il tuo risultato: #{widget_quiz_score} su #{widget_quiz_total} risposte corrette

Risultato del quiz e risposta del bot

Calendario — `calendar`

Mostra un calendario mensile in cui i clienti possono selezionare una data e poi una fascia oraria.

Sostituisce più pagine di pulsanti per data e ora, inclusa la navigazione "Indietro" e "Avanti".

Calendario: selezione di data e ora

Il calendario supporta tre modalità.

Date e Orari Personalizzati

Gli orari disponibili vengono sempre passati tramite il parametro slots.

Stesse fasce orarie ogni giorno — fornisci un elenco di orari e un intervallo di date:

p = {}
p["title"] = "Seleziona data e ora"
p["name"] = "Consulenza"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Scegli data e ora")

Fasce orarie diverse per date specifiche — fornisci un dizionario che mappa le date agli elenchi di orari. Le date disponibili sono prese dalle chiavi del dizionario:

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Scegli data e ora")

Parametro	Descrizione
`slots`	Orari disponibili, come elenco o dizionario raggruppato per data
`days`	Numero di giorni disponibili a partire da oggi
`date_from`, `date_to`	In alternativa, limiti dell'intervallo di date nel formato `"DD.MM.YYYY"`
`dates`	In alternativa, un elenco di date specifiche
`weekdays_off`	Giorni della settimana non disponibili: 1 = Lunedì fino a 7 = Domenica
`title`	Suggerimento visualizzato sotto la griglia del calendario
`name`	Nome dell'elemento o servizio prenotato; visualizzato dopo la selezione
`change`	Imposta a `1` per visualizzare un pulsante "Scegli un altro orario" dopo la selezione
`callback`	Testo di callback personalizzato invece di `widget_calendar_selected`

Solo data

Non passare slots se il cliente deve solo selezionare una data.

p = {}
p["days"] = 45
p["weekdays_off"] = [7]
w = tg_send_widget(platform_id, "calendar", p, "Choose a date")

Prenotazione online

Fornisci una sede e un servizio, e il calendario recupererà automaticamente le date e le fasce orarie disponibili dal modulo Servizi.

cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
w = tg_send_widget(platform_id, "calendar", cal, serv_title)

Parametro	Descrizione
`company_id`	Identificativo della sede
`service_ids`	Servizio o elenco di servizi
`employee_id`	Identificativo del dipendente; se omesso, viene utilizzato qualsiasi dipendente disponibile
`days_limit`	Numero di giorni in avanti per cercare la disponibilità. Predefinito: 14
`people_count`	Numero di posti richiesti per un servizio di gruppo
`auto_booking`	Impostare a `1` per consentire alla piattaforma di creare la prenotazione automaticamente

Questi parametri sono gli stessi utilizzati da get_dates_for_booking e get_slots_for_booking.

Cosa riceve il flusso del bot

Le singole selezioni di data non vengono inviate alla conversazione.

Quando il cliente seleziona una fascia oraria, o una data se il calendario non ha fasce orarie, il bot riceve il callback widget_calendar_selected e vengono popolate le seguenti variabili:

Variabile	Valore
`widget_date`	Data selezionata nel formato `DD.MM.YYYY`
`widget_time`	Ora selezionata nel formato `HH:MM`; vuota per calendari solo data
`widget_message_id`	ID del messaggio contenente il widget

Calendario: selezione completata

I formati di data e ora sono gli stessi accettati da create_booking e modify_booking_time.

Prenotazione online con calendario: esempio completo

Il widget gestisce la selezione della data, le fasce orarie e la navigazione, riducendo il numero di blocchi del bot richiesti.

Blocco 1. Selezione del servizio

Usa un blocco Condizione di avvio con la condizione "prenota un appuntamento".

Risposta: "Scegli un servizio:"

Imposta il campo pulsanti su #{srv_buttons}.

comp_id = 8
srv_data = get_services_for_booking(comp_id)
srv_kb = tools_make_button_str_checker(srv_data, 'title', 1)
srv_buttons = srv_kb['buttons']
srv_checker = srv_kb['checker']

Blocco 2. Calendario

Risposta: #{none}.

Collega il Blocco 1 al Blocco 2 usando la condizione #{srv_checker}.

serv_id = tools_check_user_input(srv_data, question, 'title', 'id')
serv_title = tools_check_user_input(srv_data, question, 'title', 'title')
cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
cal_sent = tg_send_widget(platform_id, "calendar", cal, serv_title)

Blocco 3. Crea prenotazione

Risposta: #{none}.

Collega il Blocco 2 al Blocco 3 usando la condizione widget_calendar_selected con Corrispondenza esatta.

booking_date = widget_date
booking_time = widget_time
booking_result = create_booking(comp_id, serv_id, booking_date, booking_time, '')
booking_ok = booking_result['status']

Blocco 4. Prenotazione confermata

Collega il Blocco 3 al Blocco 4 usando la condizione variabile booking_ok == True con un ritardo di un secondo.

Risposta:

Il tuo appuntamento è confermato: #{serv_title}, #{booking_date} alle #{booking_time}. A presto!

Blocco 5. Fascia oraria non più disponibile

Risposta: #{none}.

Collega il Blocco 3 al Blocco 5 usando la condizione variabile booking_ok != True con un ritardo di un secondo.

Questo blocco reimposta il calendario esistente, consentendo al cliente di selezionare un altro orario e visualizzando un messaggio di errore.

fix = {}
fix["reset"] = 1
fix["error"] = "Questa fascia oraria è stata appena prenotata. Scegline un'altra."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

Aggiungi un'altra connessione dal Blocco 5 al Blocco 3 con la condizione widget_calendar_selected.

Il cliente può ora selezionare un altro orario nello stesso calendario.

Opzione più semplice: prenotazione automatica

Aggiungi il seguente parametro alle impostazioni del calendario:

cal["auto_booking"] = 1

La piattaforma creerà la prenotazione immediatamente quando il cliente seleziona un orario.

Se la fascia oraria selezionata diventa non disponibile, il widget visualizza un errore direttamente.

Il callback widget_calendar_selected viene inviato solo dopo una prenotazione riuscita, insieme alla variabile widget_booking_id.

Con questo approccio, i Blocchi 3 e 5 non sono necessari.

Usa la prenotazione tramite il flusso del bot (il primo approccio) se hai bisogno di un pagamento anticipato o di controlli personalizzati prima di confermare un appuntamento.

Aggiornamento di un widget inviato

Usa la seguente funzione per aggiornare i dati del widget:

tg_edit_widget_data(platform_id, message_id, data)

Parametro	Descrizione
`message_id`	ID del messaggio del widget, salvato quando viene inviato o ottenuto da `widget_message_id` dopo un'interazione
`data`	Dizionario contenente i nuovi valori

Possono essere aggiornati solo i dati del widget. Non puoi modificare il layout di un widget già inviato. Per usare un layout diverso, invia un nuovo widget.

Come vengono applicati gli aggiornamenti:

Codice promozionale, timer, stato ordine, FAQ: i nuovi dati sostituiscono completamente l'aggiornamento precedente. Eventuali campi mancanti tornano ai valori originali forniti quando il widget è stato inviato. Pertanto, includi ogni campo che dovrebbe differire dai dati iniziali, come sia step che text.
Quiz e calendario: i nuovi dati vengono applicati sopra lo stato corrente del widget.

Parametri di aggiornamento speciali:

Modello	Dati	Risultato
`promo`	`{"used": 1}`	Contrassegna il codice promozionale come usato
`timer`	`{"seconds": 600}` o `{"until": "…"}`	Riavvia il conto alla rovescia
`calendar`	`{"reset": 1, "error": "message"}`	Cancella la selezione, riapre il calendario e visualizza un messaggio

Widget personalizzati

Quando i modelli pronti non bastano — ad esempio, se hai bisogno di un catalogo prodotti con carrello, una valutazione a stelle o un calcolatore di prezzi — puoi creare un widget HTML personalizzato.

Widget personalizzato: valutazione a stelle

Come funziona

Crea un widget come un singolo file HTML contenente i suoi stili e JavaScript.
Salva il codice come file .txt nella sezione File del progetto e copia l'URL del file. Il sistema di archiviazione non accetta file .html.
Un blocco del bot invia il widget usando l'URL e passa i suoi dati iniziali.
Quando un cliente interagisce con il widget, il bot riceve un callback contenente il testo definito nel codice del widget.
Un blocco handler calcola i nuovi dati e li rimanda al widget, che aggiorna la propria interfaccia.

tg_send_widget_file(platform_id, url, data, caption)

Esempio:

st = {}
st["rating"] = 0
w = tg_send_widget_file(platform_id, "https://files.mavibot.ai/…/rating.txt", st, "Valuta il tuo ordine — tocca una stella")

Il parametro data è un dizionario contenente lo stato iniziale usato per renderizzare il widget.

Gestione delle interazioni

Quando un cliente interagisce con un widget personalizzato, il bot riceve un callback.

Vengono anche popolate le seguenti variabili:

Variabile	Valore
`widget_data`	Testo della richiesta inviato dal widget, ad esempio `rate:4`
`widget_message_id`	ID del messaggio in cui è avvenuta l'interazione
`widget_query_id`	Identificativo della richiesta

Crea l'handler usando un blocco Trigger e abilita l'impostazione Trigger solo su Callback.

La condizione deve corrispondere al testo della richiesta del widget.

Questo tipo di blocco funziona indipendentemente dalla posizione corrente del cliente nel flusso del bot e non lo sposta dal suo passo attuale.

Importante: Non usare un blocco Condizione di avvio per gestire le interazioni con widget personalizzati. Un widget rimane nella chat e il cliente può interagire con esso in qualsiasi momento — anche mentre compila un questionario, prenota un appuntamento o effettua un pagamento. Un blocco Condizione di avvio reindirizzerebbe il cliente all'handler e interromperebbe il suo passo corrente.

Esempio di handler per la valutazione:

Condizione (espressione regolare):

^rate:[1-5]$

Calcolatore:

local a = splitter(widget_data, ":")
client.widget_rating = a[1]
st = {}
st["rating"] = client.widget_rating
t = tg_edit_widget_data(platform_id, widget_message_id, st)

I dati del widget personalizzato vengono sostituiti interamente durante gli aggiornamenti. Invia sempre lo stato completo piuttosto che solo il campo modificato.

Il limite di dimensione dei dati è 1024 byte.

Mantieni set di dati grandi e statici (come cataloghi prodotti) all'interno del codice del widget e invia solo i valori che cambiano tramite i dati del widget.

Per impostazione predefinita, il widget riceve immediatamente una risposta vuota e i dati aggiornati arrivano tramite un aggiornamento separato del widget.

Se il widget deve ricevere dati direttamente in risposta alla sua richiesta, il testo della richiesta deve iniziare con ?, ad esempio:

?price

In questo caso, il blocco handler deve chiamare la seguente funzione entro 15 secondi:

tg_answer_widget_query(data)

Altrimenti, il widget visualizza un errore di timeout.

Il limite di dimensione della risposta è 1024 byte.

Requisiti del codice

File singolo: includi gli stili all'interno di <style> e JavaScript all'interno di <script>. Script esterni, fogli di stile, font e immagini non possono essere caricati. Le immagini devono essere incorporate usando URL data: o SVG.
Limiti di dimensione: massimo 32 KB prima della compressione e 4 KB dopo la compressione.
Nessun campo di input: gli elementi input, select, textarea e form vengono rimossi. Solo gli elementi <button> sono supportati come controlli interattivi.
Nessuna richiesta di rete: fetch e API simili non funzionano. L'unico modo per comunicare con il bot è tramite TelegramWidget.request("text"), con una dimensione della richiesta di 1–64 byte.
Nessuno scorrimento interno: l'altezza massima del widget è di 600 pixel. Qualsiasi cosa oltre viene tagliata. Per creare un carosello, sposta una riga di card piuttosto che usare lo scorrimento.
Accesso agli elementi: usa document.getElementById. L'accesso agli elementi come variabili globali basate sui loro ID non funziona.
Tema Telegram: usa le variabili del tema Telegram come var(--tg-theme-text-color) affinché il widget appaia corretto sia nei temi chiari che scuri.
Dati del widget: leggi i dati da TelegramWidget.chatData e ridisegna il widget quando si verifica l'evento chatDataChanged.
Richieste: chiama request direttamente all'interno di un handler di interazione utente. È consentita una sola richiesta per interazione.

Il widget non visualizza errori di codifica. Gli elementi non supportati vengono rimossi silenziosamente e un errore JavaScript può risultare in un widget vuoto. Testa sempre il widget in Telegram dopo aver apportato modifiche.

L'esempio seguente visualizza un prodotto, un pulsante che invia una richiesta al bot e un contatore del carrello basato sui dati del widget.

<style>
body{margin:0;padding:14px}
.h{color:var(--tg-theme-hint-color);font-size:.85em}
button{width:100%;margin-top:8px}
</style>

<b>Margherita · $10</b>
<div class="h" id="c"></div>
<button id="add">Aggiungi al carrello</button>
<div class="h" id="e"></div>

<script>
var W=window.TelegramWidget,$=function(i){return document.getElementById(i)},busy=0;

function draw(){
  var s={};
  try{s=JSON.parse(W.chatData)||{}}catch(e){}
  $('c').textContent='Nel carrello: '+(s.count||0)
}

$('add').onclick=function(){
  if(busy)return;
  busy=1;
  $('e').textContent='';
  W.request('cart_add').then(
    function(){busy=0},
    function(x){
      busy=0;
      $('e').textContent='Errore: '+x.code
    }
  )
};

W.onEvent('chatDataChanged',draw);
draw();
</script>

Mavi e Widget

Mavi può creare flussi bot completi con widget automaticamente.

Basta descrivere ciò di cui hai bisogno in linguaggio semplice.

Ad esempio:

"Quando il cliente invia 'ordine', mostra un widget di stato dell'ordine con tre fasi. Quando invia 'pronto', sposta l'ordine alla seconda fase."
"Crea un flusso di prenotazione servizi: i clienti scelgono un servizio usando pulsanti, poi selezionano data e ora usando un widget calendario."
"Crea un widget di valutazione a stelle per gli ordini e salva la valutazione selezionata in una variabile cliente."

Mavi configura automaticamente modelli già pronti.

Per widget personalizzati, Mavi scrive e controlla il codice, salva il file del widget nel progetto e crea i blocchi necessari per inviare il widget e gestire le interazioni del cliente.

Riferimento

Funzioni

Funzione	Descrizione
`tg_send_widget(platform_id, template, params, caption)`	Invia un modello di widget già pronto
`tg_send_widget_file(platform_id, url, data, caption)`	Invia un widget personalizzato da un file
`tg_edit_widget_data(platform_id, message_id, data)`	Aggiorna i dati in un widget esistente
`tg_answer_widget_query(data)`	Risponde a una richiesta di widget personalizzato che inizia con `?`

Callback e Variabili

Evento	Callback	Variabili
Quiz completato	`widget_quiz_finished`	`widget_quiz_score`, `widget_quiz_total`, `widget_quiz_answers`
Data e ora selezionate nel calendario	`widget_calendar_selected`	`widget_date`, `widget_time`; anche `widget_booking_id` quando `auto_booking` è abilitato
Interazione con widget personalizzato	Testo della richiesta definito nel codice del widget	`widget_data`, `widget_message_id`, `widget_query_id`

Se il tuo bot contiene più quiz o calendari, assegna un callback univoco a ciascun widget usando il parametro callback per poterli distinguere nelle condizioni del flusso del bot.

Limitazioni

I widget funzionano solo in chat Telegram private tra un cliente e un bot.
Solo i cinque quiz e calendari più recenti vengono conservati per ciascun cliente. I più vecchi smettono di rispondere alle interazioni.
Cancellare tutte le variabili cliente in un flusso bot disabilita quiz e calendari inviati in precedenza.
I dati del widget sono limitati a 1024 byte.
Le richieste da widget personalizzati sono limitate a 64 byte.
Le richieste di widget personalizzati che richiedono tg_answer_widget_query devono ricevere risposta entro 15 secondi.

Risoluzione dei problemi

Problema	Causa / Soluzione
Il widget non viene inviato e la variabile contiene `Unknown parameter…`	Il modello ha ricevuto un parametro non supportato. Il messaggio di errore elenca i parametri consentiti
Il calendario si ferma dopo la selezione della data senza mostrare gli orari	Il parametro `slots` non è stato fornito
Dopo l'interazione con un widget, il bot smette di rispondere ai pulsanti nel passaggio corrente	Il gestore dell'interazione usa un blocco Start Condition. Sostituiscilo con un blocco Non-State con Condizione
Il widget personalizzato appare vuoto	C'è un errore nel codice del widget. Una causa comune è l'accesso a un elemento tramite il suo ID senza usare `document.getElementById`
Telegram mostra "Unsupported message"	Il cliente sta usando una versione obsoleta di Telegram
`Bad Request: chat not found`	Il widget è stato inviato al di fuori di Telegram, ad esempio dalla finestra di test del bot

Widget Telegram

Dove Funzionano i Widget

Modelli Pronti

Come Costruire i Parametri

Lingua

Timer di Countdown — `timer`

Stato Ordine — `order_status`

Domande Frequenti — `faq`

Quiz e Sondaggio — `quiz`

Cosa Riceve il Flusso del Bot

Calendario — `calendar`

Date e Orari Personalizzati

Solo data

Prenotazione online

Cosa riceve il flusso del bot

Prenotazione online con calendario: esempio completo

Opzione più semplice: prenotazione automatica

Aggiornamento di un widget inviato

Widget personalizzati

Come funziona

Invio di un widget personalizzato

Gestione delle interazioni

Risposta a una richiesta del widget

Requisiti del codice

Esempio minimo di widget personalizzato

Mavi e Widget

Riferimento

Funzioni

Callback e Variabili

Limitazioni

Risoluzione dei problemi

Widget Telegram

Dove Funzionano i Widget

Modelli Pronti

Come Costruire i Parametri

Lingua

Codice Promozionale — promo

Timer di Countdown — timer

Stato Ordine — order_status

Domande Frequenti — faq

Quiz e Sondaggio — quiz

Cosa Riceve il Flusso del Bot

Calendario — calendar

Date e Orari Personalizzati

Solo data

Prenotazione online

Cosa riceve il flusso del bot

Prenotazione online con calendario: esempio completo

Opzione più semplice: prenotazione automatica

Aggiornamento di un widget inviato

Widget personalizzati

Come funziona

Invio di un widget personalizzato

Gestione delle interazioni

Risposta a una richiesta del widget

Requisiti del codice

Esempio minimo di widget personalizzato

Mavi e Widget

Riferimento

Funzioni

Callback e Variabili

Limitazioni

Risoluzione dei problemi

Codice Promozionale — `promo`

Timer di Countdown — `timer`

Stato Ordine — `order_status`

Domande Frequenti — `faq`

Quiz e Sondaggio — `quiz`

Calendario — `calendar`