(IT) Guida rapida per il gestore

I più sentiti ringraziamenti per avere scelto di usare zweb booking bot, il bot di Telegram che semplifica le prenotazioni di spazi e servizi in affitto a tempo.

Questa guida è pensata per fornire una panoramica delle caratteristiche del software associato al bot e delle modalità di interazione con il bot. Buona lettura.

Versione del software a cui si riferisce la guida: R32 (settembre 2024).

Funzionalità

Per l'utente

Si dà a seguire una lista con descrizione sintetica di ciò che offre il servizio di prenotazione di Zweb Booking Bot. Come utente, con questo bot puoi:

• prenotare un servizio a scelta fra vari servizi a ore, premendo dei pulsanti di scelta in una semplice procedura guidata;
• scegliere un giorno della settimana per la prenotazione - di norma, fino a 2 settimane nel futuro dal giorno odierno;
• visualizzare una lista di orari divisi per intervalli di tempo;
• scegliere la durata della propria prenotazione;
• visualizzare la lista delle proprie prenotazioni attive;
• cancellare una propria prenotazione;
• visualizzare un contenuto informativo, tipicamente contenente la descrizione, le condizioni e i prezzi che si applicano al servizio;
• ricevere un biglietto pro-forma contenente le informazioni principali della propria prenotazione;
• se attivata dalle impostazioni del bot, eseguire la registrazione per poi avere la possibilità di prenotare;
• visualizzare la posizione di mappa (nel formato del servizio di Telegram) dove è presente il servizio;

Per il gestore del servizio

In aggiunta a tutte le funzionalità precedenti, il gestore del servizio può anche:

• inviare gli orari delle prenotazioni al proprio Google Calendar;
• (richiesto dagli utenti) creare servizi virtuali, ovvero servizi che dipendono da un altro servizio dichiarato come "genitore" (parent) e che condividono lo stesso orario: questo può tornare molto utile quando si vuole differenziare due o più servizi che utilizzano una risorsa condivisa (una persona, una stanza, ecc.);
• creare regole per stabilire uno o più intervalli di orario di esercizio specifici per un singolo giorno della settimana (cioè turni di esercizio), incluse regole che diventano valide a partire da un giorno nel futuro; ogni regola resta valida finché non viene impostata nuovamente: l'ultima inserita e valida nel presente ha la priorità per quel giorno della settimana;
• visualizzare tutte le regole attive per gli orari di esercizio;
• recuperare, in formato .xlsx (Microsoft Excel), una tabella delle prenotazioni in base alla quantità, oppure specificando un mese e anno, oppure recuperare solo le prenotazioni ancora attive (prenotazioni future);
• visualizzare le prenotazioni in formato testo monospaziato (pseudo-tabella): sia tutte le prenotazioni attive, sia le prenotazioni divise per servizio;
• effettuare una prenotazione rapida, con una riga di testo, associandovi un nominativo, anche con una data nel passato (questo può essere utile per riflettere eventuali cambiamenti nel mondo reale e tenerne traccia);
• effettuare una prenotazione ricorrente settimanalmente, per un certo numero di settimane;
• cancellare una prenotazione propria o altrui, o modificarne una propria;
• accedere a una lista integrale delle prenotazioni in formato csv (valori separati da virgole, formato di file universale che può essere aperto da applicazioni per fogli di calcolo e da semplici editor di testo);
• accedere alla lista degli utenti registrati (solo se la registrazione è attiva: vedi oltre)
• annullare una registrazione specifica;
• bloccare o sbloccare un utente dal suo pannello di controllo, ossia un menu a pulsanti;

Il gestore del servizio sarà riconosciuto dal sistema automaticamente, in base all'id Telegram impostato nella configurazione.

Per il configuratore del servizio (sviluppatore) e/o il gestore

E' utile sapere che la configurazione manuale del bot, da effettuarsi generalmente al primo avvio del servizio editando un apposito file di testo di configurazione, permette inoltre di:

• editare il testo per ogni messaggio del bot;
• scegliere la lingua del bot: i messaggi, le notifiche, e i comandi speciali saranno tradotti nella lingua scelta; attualmente, il software è fornito con dei file di configurazione in italiano, inglese e spagnolo, ma si possono creare dei file per altre lingue in modo agevole;
• attivare la funzione di registrazione semplificata per tracciare gli utenti, in modo che solo gli utenti registrati possano prenotare;
• scegliere se inviare o meno il tagliando pro-forma, in formato immagine;
• scegliere orari standard di esercizio per uno specifico servizio (ad esempio, se una struttura o un servizio non possono essere prenotati dopo le ore 16, si può impostare come orario "08:00/16:00", e la disponibilità del servizio in orari successivi verrà ignorata)
• scegliere il numero massimo di prenotazioni per utente (il gestore non è soggetto a questo limite). Si consiglia di impostare un limite basso per evitare che un utente, per errore o per dolo, possa riempire il palinsesto degli orari prenotando troppe volte;
• impostare la posizione di mappa in base alle coordinate geografiche;
• impostare i servizi disponibili per la prenotazione;
• impostare il fuso orario, il nome dei giorni della settimana in formato breve (3 lettere), e il formato delle date;
• impostare un intervallo di orario generico giornaliero di esercizio; questo sarà valido in mancanza di regole per uno specifico giorno della settimana;
• impostare l'id telegram del gestore del servizio;
• personalizzare i nomi dei comandi dell'utente (pulsanti Telegram) e di quelli riservati al gestore;
• impostare il numero di giorni massimi di anticipo con i quali si può prenotare (massimo attuale: 14);
• modificare l'intervallo di minuti minimo. (il valore di default è 30 minuti, il bot è stato testato con intervalli di 30 e 60 minuti, ma è compatibile con altri sottomultipli di un'ora, quindi ad es.: 10, 12, 15, 20, 30 e 60 minuti)

Ricette ed esempi

D: Come creo una regola per i turni di esercizio di un giorno specifico della settimana, ad esempio il martedì, affinché siano effettivi a partire dal 5 giugno e fino al 30 agosto 2024?

R: Scrivere nel campo di testo della chat:

.imposta turni Mar 09:30/13:00,15:00/22:30 05-06-2024 30-08-2024

Di norma, i giorni della settimana sono Lun, Mar, Mer, Gio, Ven, Sab, Dom. Come si può vedere, gli intervalli di orario devono essere scritti senza spazi, e separati fra loro solo da una virgola. A seguire, si inserisce il giorno mese e anno di inizio della regola e di fine della regola, con le parti della data separate da trattino.

D: E se i servizi che offro hanno turni di esercizio diversi?

R: Supponiamo di avere più servizi, e che il servizio con un turno diverso abbia come short_name nella configurazione il nome campo1. Scrivere ad esempio nel campo di testo della chat:

.imposta servizio turni Mar 12:00/19:30 05-06-2024 30-08-2024 campo1

Questo farà sì che la regola per il servizio campo_1 abbia la priorità quando un utente prenota, e sia usata al posto di quella precedente (che ha validità generale)

D: E se volessi una regola attiva da subito?

Basta mettere, nella scrittura precedente, una qualsiasi data nel passato (anteriore a oggi), et voilà!

D: Ho sbagliato nell'inserire una regola. E adesso?

R. Per eliminare l'ultima regola inserita è possibile scrivere:

.cancella ultima regola

Attenzione: se questo comando viene usato più volte, ogni volta eliminerà una regola.

In alternativa, poiché l'ultima regola inserita relativa a un certo giorno della settimana è quella valida, sarà sufficiente impostarne una nuova. Se ad esempio si inserisce una nuova regola per lo stesso servizio, con lo stesso giorno della settimana e la stessa data, il sistema utilizzerà l'ultima inserita, ignorando tutte le precedenti.

D: Come visualizzo tutte le regole attive per i turni della settimana?

R: Scrivendo in chat:

.mostra turni attivi

D: Come recupero le ultime 50 prenotazioni inserite?

R: Scrivere nel campo di testo della chat:

.ottieni ultime 50

Al posto di 50, puoi inserire il numero che preferisci.

D: Come ottengo le prenotazioni attive in questo momento?

R: Premi il pulsante "/prenotazioni_attive" nella tastiera di Telegram, e le riceverai in formato Excel (.xlsx).

D: Come ottengo le prenotazioni di aprile 2024?

R: Scrivere nel campo di testo della chat:

.ottieni prenotazioni 2024-04

Prima l'anno, poi il mese, separati da un trattino.

D: Come recupero l'archivio integrale in .csv con tutte le prenotazioni inserite / annullate?

R: Scrivere nel campo di testo della chat:

.ottieni tutto

Nota: questo file, col tempo, potrebbe diventare relativamente voluminoso se il tuo volume di affari è importante. La ragione per cui l'archivio è in formato 'csv' è questa: il file si manterrà di dimensioni più contenute, il formato è universale, e il sistema lo aggiornerà ad ogni prenotazione e cancellazione, tenendolo già pronto nel caso tu lo richieda.

D: Come cancello una specifica prenotazione? Non posso accettarla!

R: Recupera prima di tutto le prenotazioni con uno dei metodi già visti. Sègnati il valore nel campo rid della riga di quella prenotazione. Quindi scrivi in chat:

.cancella 1234, sostituendo a "1234" il rid corrispondente. Attenzione: questa operazione non può essere annullata, se non rifacendo la stessa prenotazione!

Nota: Per ragioni di privacy e spam, il bot non può avvisare l'utente che la sua prenotazione è stata cancellata: sarebbe gentile che gli scrivessi tu per avvisarlo!

D: Come recupero la lista in formato Excel degli utenti registrati?

R: Scrivere nel campo di testo della chat:

.ottieni utenti

D: Ho individuato un utente fraudolento: come bloccarlo?

R: Prima recupera gli utenti come scritto sopra, e segnati il suo "id". Si può disattivare un utente specifico scrivendo in chat:

.disabilita utente {id}, inserendo l'id numerico dell'utente (senza parentesi) al posto di "{id}". Se l'utente era già bloccato, non saranno operate modifiche. Una volta bloccato l'utente, lo sarà anche la sua procedura di prenotazione.

Nota: Se l'utente, nell'istante in cui viene bloccato, stava eseguendo una prenotazione, potrebbe effettuarla ugualmente. Da quel momento, però, non gli sarà più possibile farne di nuove.

D: E se volessi riammetterlo?

R: Basta scrivere:

.abilita utente {id}, inserendo l'id numerico dell'utente (senza parentesi) al posto di "{id}". Se l'utente era già abilitato, non saranno operate modifiche.

D: Un cliente mi chiede di poter prenotare il servizio per due mesi tutti i lunedì, dalle 16 alle 18. Posso eseguire una prenotazione ripetuta?

R. Dalla versione R20 beta, questo è possibile per il solo gestore, su base settimanale. Supponiamo che il primo lunedì sia il 22 aprile 2024 e che il servizio abbia lo shortname "Palestra2". Ogni lunedì per due mesi significa almeno 8 prenotazioni. Si userà il seguente comando:

.prenota 8 volte 22-04-2024 16:00/18:00 Palestra2

D: Un cliente mi chiama e vuole effettuare una prenotazione. Come aggiungo la prenotazione al bot?

R. Devi semplicemente scrivere una riga di messaggio contenente tutti i dati necessari per la prenotazione, compreso un nome alla fine del messaggio. Questo nome ti aiuterà a ricordare la prenotazione, ma il sistema memorizzerà anche l'ID telegramma del custode, così saprai che hai prenotato per conto di qualcun altro. Esempio di prenotazione veloce:

.p 20-06-2024 18:00/20:00 Padel_court John Doe

Si prega di notare che:

• il nome alla fine può avere qualsiasi lunghezza e struttura, tuttavia, a causa della struttura tabellare dei messaggi di testo del bot, quando riceverai tutte le prenotazioni attive in formato testo verranno visualizzati solo i primi 20 caratteri;
• l'esempio 'Padel_court' è il nome che inserisci nel file di configurazione sotto la proprietà "short_name" di quel servizio: è una specie di nome in codice breve che indica quale servizio è stato scelto; è consigliabile, come suggerisce il nome, mantenerlo abbastanza breve per motivi pratici (verrà riportato anche nel biglietto pro-forma)
• '.p' sta per 'prenota', e tutta la parte di testo dei comandi che NON sono tra parentesi graffe (che invece sono parametri e devono essere mantenuti così come sono) può essere modificata a proprio piacimento dal file di configurazione. Se decidi di usare un comando di testo, fa' attenzione agli errori di battitura, il sistema non accetta errori!

Auto-prenotazione

A partire dalla versione R 24, il gestore del servizio può prenotare per conto terzi anche con la procedura guidata a pulsanti di Telegram usata dagli altri utenti; al termine della procedura, si dovrà, in aggiunta, inserire un nominativo della persona per conto della quale si prenota (di default, il nominativo dovrà essere preceduto dal prefisso .utente (con uno spazio alla fine del prefisso).

Foglio informativo

Queste sono le strutture dei comandi di testo standard con parametri racchiusi tra parentesi graffe. Non è necessario mettere le parentesi graffe quando si scrive un comando nel campo di testo della chat di Telegram, proprio come mostrato negli esempi sopra: le parentesi graffe vanno scritte solo nel file di configurazione per indicare un parametro; il parametro è un segna-posto, quando si scrive un comando in chat, va sostituito con il valore che si intende dare a quel parametro. Il nome del parametro può essere cambiato (usando di preferenza solo lettere minuscole e trattini bassi ( _ ) ), ma il cambiamento non altera il comportamento del software.

Ricorda!

• Per conoscere l'{id_utente}, dovresti usare un comando come .ottieni utenti registrati, oppure ottenere un elenco delle prenotazioni in formato excel, dove l'id_utente è mostrato sotto la relativa colonna.
• L'intervallo di tempo ha sempre la forma hh:mm/hh:mm (senza spazi intermedi). Per essere sicuri al 100% che il comando funzionerà in qualsiasi circostanza, applicare uno zero iniziale prima delle ore a cifra singola (ad esempio, 8:30 diventa 08:30). Un 'turno' è semplicemente una serie di intervalli di tempo (fino a 3) separati da virgola es. 09:00/12:00,13:30/18:30.
• {nome_cliente} può essere una serie qualsiasi di uno o più nomi separati da uno spazio
• {gg_mm_aaaa} deve essere scritto nella forma GG-MM-AAAA, con un trattino come separatore tra anno e mese e tra mese e giorno
• {giorno_settimana_abbrev} è la denominazione abbreviata di un giorno della settimana con la prima lettera maiuscola: Lun, Mar, Mer, Gio, Ven, Sab, Dom.

Configurazione

Attraverso ulteriori parametri di configurazione, è possibile decidere:

• il numero di ore d'anticipo con le quali è possibile prenotare;
• il numero di prenotazioni concorrenti per ogni servizio (nuova funzionalità, dalla versione 0.12beta)
• il numero di ore, puramente informativo, per poter disdire la prenotazione senza incorrere in penali (se previste);
• l'intervallo di giorni nei quali è possibile prenotare (massimo 14, per evitare di intasare l'interfaccia della chat di Telegram con i pulsanti);
• il numero massimo di prenotazioni attive per utente;
• il fuso orario;
• il testo dei comandi (attenzione: un'errata assegnazione può comportare errori nell'esecuzione del codice del bot, è raccomandato un parere esperto);
• se usare la registrazione utente o disattivarla;
• e altro ancora...

Per modificare questi parametri, è richiesto l'accesso allo spazio web che ospita il codice dell'applicazione, una minima esperienza di programmazione. I parametri di configurazione permettono di personalizzare l'esperienza d'uso del chatbot, specialmente nella fase iniziale.

Limitazioni

Il software al momento presenta alcune limitazioni alle funzioni appena viste:

• Non è possibile gestire orari che superino la fine del giorno solare, ovvero le 23:59 (in alternativa, sarebbe possibile passare al giorno seguente, dividendo il tempo in due prenotazioni);
• Non è possibile effettuare pagamenti attraverso il bot;
• E' possibile salvare solo un'informazione di testo relativa all'utente in fase di registrazione.