Un webhook consente a siti e applicazioni di scambiarsi dati automaticamente quando si verifica un determinato evento. I dati viaggiano in una richiesta HTTP: un’applicazione li invia via Internet a un indirizzo prestabilito dell’altra.
Cosa puoi fare con i webhook
In FLOWIN i webhook sono associati agli inoltri. Possono attivarsi quando nella chat di origine compare un messaggio o quando questo viene modificato, eliminato o fissato. Possono anche attivarsi quando qualcuno preme un pulsante nella chat che riceve i messaggi inoltrati, ossia la destinazione.
Puoi così collegare FLOWIN a social network, piattaforme di scambio, fogli di calcolo e CRM, i sistemi per gestire le relazioni con i clienti. Questo collegamento si chiama integrazione e ti permette di:
- Aggiungere automaticamente al CRM le richieste che arrivano da Telegram.
- Inviare segnali di trading da Telegram a una piattaforma di scambio per replicarli, ossia eseguire automaticamente le operazioni indicate.
- Inoltrare messaggi da Telegram ad altri social network.
- Copiare post e messaggi in Fogli Google.
- Configurare un risponditore automatico in un bot.
Per ogni caso devi configurare la ricezione dei dati e l’azione desiderata sul sito o nell’applicazione che li riceve.
Creare un webhook
Proviamo un webhook con webhook.site, un sito che fornisce un indirizzo a cui inviare dati e mostra le richieste ricevute. Gli invieremo il testo di un nuovo messaggio Telegram.
Per farlo serve un inoltro configurato e funzionante in FLOWIN.
Per la prima prova
Usa una chat di prova separata e una richiesta fittizia. Per la verifica basta inviare il testo, senza nomi, numeri di telefono o altri dati personali.
Apri @flow_in_bot, invia il comando
/starte premi «Pannello di controllo».
Accesso al pannello di controllo tramite @flow_in_bot. Apri webhook.site in un’altra scheda. Copia l’indirizzo per la ricezione delle richieste dal campo «Your unique URL».
L’indirizzo a cui inviare la richiesta di prova. Nel pannello di FLOWIN apri «Menu» → «Webhook» e premi «Creare».
La sezione «Webhook» nel menu di FLOWIN. 
Creazione del primo webhook. Incolla l’indirizzo copiato nel campo in alto. Nel campo «Corpo della richiesta» inserisci
{"message":"<message-text>"}e premi «Creare». Questo è il modello dei dati da inviare: al posto di<message-text>FLOWIN inserirà il testo del messaggio, che il destinatario vedrà nel campomessage.
L’indirizzo e il corpo della richiesta di prova. Premi «Applicare» accanto al webhook appena creato. Seleziona l’inoltro desiderato e premi «Salvare».
Collegamento del webhook all’inoltro. 
Scelta dell’inoltro per il webhook. Invia nella chat di origine un messaggio di prova, per esempio «Richiesta n. 1042: mi serve il catalogo dei mobili.». Torna su webhook.site: la prima richiesta ricevuta si aprirà automaticamente. Nella sezione «Request Content» troverai il testo della richiesta nel campo
message. Da questo momento FLOWIN invierà automaticamente il testo di ogni nuovo messaggio all’indirizzo specificato prima di inoltrarlo alla chat di destinazione.
La richiesta di prova nella chat di origine. 
Il testo della richiesta ricevuto su webhook.site.
Impostazioni dei webhook
Vediamo come modificare le impostazioni e cosa significa ogni campo usando il webhook appena creato.
Dove trovare i dati per la configurazione
Per collegare un altro sito o un’applicazione, consulta la sua documentazione. Di solito le istruzioni per ricevere i dati si trovano nella sezione dedicata all’API, che descrive come interagire con altri programmi. Lì troverai l’indirizzo, il metodo HTTP e il formato dei dati da usare nei campi descritti di seguito.
Come modificare le impostazioni del webhook
Nell’elenco «Webhook» premi «Modificare» accanto al webhook che ti interessa.
Apertura delle impostazioni del webhook. Modifica i campi desiderati e premi «Salvare».
Salvataggio delle impostazioni modificate. 
La descrizione salvata nelle impostazioni del webhook.
Metodo HTTP
Il metodo HTTP indica l’azione della richiesta: POST invia dati da elaborare, GET richiede dati e PUT li sostituisce. Per impostazione predefinita è selezionato POST, adatto alla nostra prova. Per un altro sito o un’altra applicazione scegli il metodo indicato nella relativa documentazione.
Indirizzo URL
Un URL è un indirizzo Internet. Qui inserisci l’indirizzo per la ricezione dei dati fornito dal sito o dall’applicazione che vuoi collegare. Nel nostro esempio lo ha generato webhook.site.
Corpo della richiesta
Il corpo della richiesta contiene i dati da inviare in formato JSON, organizzati in coppie «nome del campo: valore». I campi dipendono dai requisiti del sito o dell’applicazione che vuoi collegare.
I metatag sono segnaposto che FLOWIN sostituisce con i dati del messaggio. Per esempio, <message-text> viene sostituito con il testo e <author-name> con il nome dell’autore. Puoi aprire l’elenco dei metatag anche dal link «metatag» sotto il campo.
I numeri di utenti, messaggi, chat e argomenti nell’elenco che segue sono i rispettivi identificativi (ID) in Telegram.
Messaggio e autore
- Testo del messaggio:
<message-text>. - Data del messaggio:
<message-date>. - Ora del messaggio:
<message-time>. - ID dell’autore:
<author-id>. - Nome dell’autore:
<author-name>. - Nome dell’autore con link HTML al suo profilo:
<author-name-link>. - Nome dell’autore come hashtag:
<author-name-tag>. - Nome utente dell’autore:
<author-username>.
Origine
- Testo del messaggio:
<src-message-text>. - ID del messaggio:
<src-message-id>. - Link al messaggio:
<src-message-link>. - ID della chat:
<src-chat-id>. - Nome della chat:
<src-chat-name>. - Nome utente della chat:
<src-chat-username>. - ID dell’argomento:
<src-topic-id>. - Nome dell’argomento:
<src-topic-name>.
Destinazione
- Testo del messaggio:
<dst-message-text>. - ID del messaggio:
<dst-message-id>. - Link al messaggio:
<dst-message-link>. - ID della chat:
<dst-chat-id>. - Nome della chat:
<dst-chat-name>. - Nome utente della chat:
<dst-chat-username>. - ID dell’argomento:
<dst-topic-id>. - Nome dell’argomento:
<dst-topic-name>.
L’ID e il link del messaggio nella chat di destinazione sono disponibili dopo l’inoltro. Per trasmetterli, seleziona «Dopo l’invio» nel campo «Trigger della richiesta».
Clic sul pulsante
- ID dell’utente che ha premuto il pulsante:
<clicker-id>. - Nome dell’utente che ha premuto il pulsante:
<clicker-name>. - Dati del pulsante:
<clicker-data>. - Data del clic:
<click-date>. - Ora del clic:
<click-time>.
Selezione del testo
- Un’espressione regolare definisce una regola per cercare il testo. Per esempio,
<regexp>(short|sell)</regexp>inserisce la prima corrispondenza trovata pershortosell. - Testo casuale
<random>1|2|3|4|5</random>inserisce una delle cinque alternative. Tra i tag puoi indicare le tue alternative, separandole con il simbolo|.
Intestazioni della richiesta
Le «Intestazioni della richiesta» forniscono informazioni di servizio al destinatario. Per esempio, una chiave di accesso gli permette di verificare chi ha inviato la richiesta. Le intestazioni si specificano in formato JSON. Di solito non devi modificare questo campo. Se necessario, trovi i valori nella documentazione del sito o dell’applicazione che vuoi collegare.
Trigger della richiesta
Il «Trigger della richiesta» determina l’evento e il momento in cui il webhook deve inviare la richiesta all’indirizzo indicato. Puoi scegliere uno di questi eventi:
- «Invio» è selezionato per impostazione predefinita. Il webhook si attiva quando viene inoltrato un nuovo messaggio.
- «Modifica» si attiva quando viene elaborata la modifica di un messaggio nella chat di origine.
- «Fissaggio» si attiva quando viene elaborato il fissaggio di un messaggio nella chat di origine.
- «Eliminazione» si attiva quando viene elaborata l’eliminazione di un messaggio nella chat di origine.
- «Clic sul pulsante» si attiva per i pulsanti di callback nella chat di destinazione. Quando qualcuno preme un pulsante di questo tipo, il bot riceve una notifica e i dati associati al pulsante. Un normale pulsante con un link non attiva questo webhook.
Il momento dell’invio determina in quale fase dell’inoltro parte la richiesta:
- «Prima dell’elaborazione»: la richiesta parte prima della traduzione e dell’elaborazione del messaggio con l’intelligenza artificiale (IA).
- «Dopo l’elaborazione»: la richiesta parte dopo la traduzione e l’elaborazione con l’IA.
- «Dopo l’invio»: la richiesta parte quando il messaggio è già stato inviato o modificato con successo nella chat di destinazione.
I momenti di invio disponibili
Tutte e tre le opzioni sono disponibili per gli eventi «Invio» e «Modifica». Per «Fissaggio», «Eliminazione» e «Clic sul pulsante» si usa «Prima dell’elaborazione» e non è possibile scegliere un altro momento.
Descrizione
«Descrizione» è uno spazio per una nota personale e non influisce sul funzionamento del webhook. Puoi lasciare il campo vuoto.
Azioni disponibili per i webhook
Puoi gestire i webhook che hai creato dall’elenco «Webhook»:
- «Modificare» apre le impostazioni principali del webhook.
- «Duplicare» nel menu «Altro» crea una copia delle impostazioni del webhook.
- «Selezionare il progetto» nel menu «Altro» aggiunge il webhook a un progetto.
- «Eliminare» nel menu «Altro» elimina il webhook.
Ogni webhook dispone inoltre del pulsante «Inoltri [N]», che apre la selezione degli inoltri a cui è applicato. N indica il numero di inoltri selezionati. Se non ne hai ancora selezionati, al suo posto compare «Applicare».
Domande frequenti
In parole semplici, che cos’è un webhook?
È un modo per inviare automaticamente dati a un’altra applicazione quando si verifica un determinato evento. Per esempio, quando inoltra un nuovo messaggio, FLOWIN ne invia il testo all’indirizzo che hai indicato con una richiesta HTTP. Qui è FLOWIN a inviare la richiesta. Il metodo Telegram setWebhook configura invece il flusso nell’altra direzione: l’invio degli aggiornamenti da Telegram al programma che gestisce il bot.
Basta indicare l’indirizzo del CRM?
No. Servono l’indirizzo per la ricezione dei dati indicato nella documentazione del CRM, il metodo HTTP, i campi JSON appropriati e le eventuali intestazioni richieste per l’accesso. Il normale indirizzo del sito del CRM non è adatto. FLOWIN invia la richiesta, ma la creazione di una pratica o l’esecuzione di un’altra azione dipendono da come il CRM elabora i dati ricevuti. I campi sono descritti nella sezione «Impostazioni dei webhook».
Perché il link al messaggio nella chat di destinazione è vuoto?
Prima che il nuovo messaggio sia stato inviato con successo, FLOWIN non ne conosce ancora l’ID e il link nella chat di destinazione. Per trasmettere <dst-message-id> e <dst-message-link> scegli l’evento «Invio» o «Modifica» e il momento «Dopo l’invio» nel campo «Trigger della richiesta». Il link viene generato per i canali e i supergruppi. Per le chat private o i gruppi normali, <dst-message-link> rimarrà vuoto anche dopo l’invio.
Posso attivare un webhook premendo un normale pulsante URL?
No. Un normale pulsante URL apre un link. Per l’evento «Clic sul pulsante» serve un pulsante di callback nella chat di destinazione, che invii al bot i dati del clic. La differenza è descritta nella sezione «Trigger della richiesta».
Come verifico che il servizio esterno abbia ricevuto i dati?
Invia un messaggio fittizio e verifica la richiesta ricevuta dal servizio. Nel nostro esempio con webhook.site il testo della richiesta compare nella sezione «Request Content». Il fatto che l’inoltro in Telegram sia riuscito non conferma di per sé che il servizio esterno abbia ricevuto i dati o eseguito l’azione desiderata. Per la verifica basta il testo, senza nomi, numeri di telefono o altri dati personali.