Sviluppare un Bot Slack utilizzando Node.js

() translation by (you can also view the original English article)

Slack sta rapidamente diventando il nuovo standard di comunicazione per i team. In effetti, è così popolare che quando digitiamo slack in Google, come atteso, il primo risultato è la definizione della parola dal dizionario. Seguita immediatamente dopo dal sito di Slack!

È pressoché impensabile per le più comuni parole nel dizionario inglese. Di solito, la definizione di Google è seguita da numerosi collegamenti ai siti web di dizionari più importanti.

Cos'è Slack?

Nella sua forma base, Slack è un sistema di messaggistica. Consente di inviare messaggi diretti ai membri di un team e di creare canali (privati o pubblici) che consentono facilmente la collaborazione e la comunicazione di squadra in tempo reale. Per ulteriori informazioni su Slack, è possibile consultare le Slack's Features.

A questo punto, potreste domandavi dove entra in gioco Node.js. Come già menzionato, nella sua forma base, Slack è un sistema di messaggistica; tuttavia, può essere infinitamente esteso e personalizzato. Slack fornisce un sistema incredibilmente flessibile per personalizzare l'integrazione del vostro team, tra cui:

creazione di messaggi di benvenuto personalizzati
creazione personalizzata di emoji
l'installazione di applicazioni di terze parti
creazione di applicazioni personalizzate
creazione personalizzata di Bot Slack

In questo articolo, abbiamo intenzione di mostrare come creare un Bot Slack con Node.js che può essere aggiunto alla configurazione Slack del vostro team.

Definizione di Bot Slack

Il lavoro di un Bot Slack è quello di ricevere eventi inviati da Slack e gestirli. Ci sono una pletora di eventi che verranno inviati al vostro Bot, e qui è dove entra in gioco Node.js. Dobbiamo decidere non solo gli eventi da gestire, ma come gestire ogni singolo evento.

Ad esempio, alcuni eventi comuni che un Bot potrebbe gestire sono:

member_joined_channel
member_left_channel
message

In questo articolo, creeremo un'applicazione Node.js e un Bot Slack che possono essere aggiunti al progetto di un team per eseguire azioni specifiche in base agli eventi che riceve.

Per iniziare, abbiamo bisogno di creare un Bot in Slack. Due tipi di bot possono essere creati:

un bot personalizzato
creazione di un'applicazione e l'aggiunta di un bot utente

In questo articolo verrà creato un bot personalizzato perché un bot utente di applicazione sarebbe più appropriato se pensaste di scrivere e pubblicare un'applicazione in Slack. Dato che vorremmo che questo bot fosse privato al team, sarà sufficiente un bot personalizzato.

Creazione di un Bot personalizzato Slack

Un bot personalizzato può essere creato qui: https://my.slack.com/apps/A0F7YS25R-bots. Se siete già loggati al vostro account Slack, sulla sinistra selezionate il pulsante Add Configuration; altrimenti, accedete al vostro account Slack prima di procedere. Se non avete un account Slack, è possibile iscriversi gratuitamente.

Ciò vi porterà a una nuova pagina che richiede di fornire un nome utente per il bot. Inserite ora l'username, assicurandovi di seguire le linee guida di Slack sui nomi. Dopo aver selezionato un fantastico nome bot, premete Add bot configuration.

Dopo aver creato correttamente il vostro bot, Slack vi reindirizzerà a una pagina che consente ulteriori personalizzazioni del bot. Lasciamo questa parte alla vostra creatività. L'unica cosa necessaria da questa pagina è l'API Token che inizia con xoxb-. Copierei questo token in un luogo sicuro per un utilizzo successivo o semplicemente lascerei aperta questa pagina fino a quando avremo bisogno del token per l'applicazione Node.js.

Configurazioni

Prima di passare al codice, sono necessarie due ulteriori configurazioni Slack:

Create o selezionate un canale esistente con cui interagirà il vostro bot. Testando il nostro nuovo bot, abbiamo deciso di creare un nuovo canale. Assicuratevi di ricordare il nome del canale che servirà all'interno dell'applicazione a breve.
Aggiungete/invitate il bot al canale in modo da farlo interagire con esso.

Ora che abbiamo il nostro Bot Slack configurato, è tempo di passare all'applicazione Node.js. Se avete già installato Node.js, potete passare al passaggio successivo. Se non avete installato Node.js, suggeriamo di iniziare visitando la pagina Download di Node.js, selezionando il programma di installazione per il sistema.

Per il nostro Bot Slack, abbiamo intenzione di creare una nuova applicazione Node.js eseguendo npm init. Con un prompt dei comandi impostato dove si desidera che l'applicazione venga installata, eseguite le seguenti istruzioni:

1	mkdir slackbot
2	cd slackbot
3	npm init

Se avete poca dimestichezza con npm init, verrà avviato un programma di utilità per aiutarvi a configurare il nuovo progetto. La prima cosa che chiede è il nome. Il nostro è impostato di default su slackbot, e va bene. Se si desidera modificare il nome dell'applicazione, questo è il momento; in caso contrario, premere Invio per procedere con il passaggio di configurazione successivo. Le opzioni successive sono la versione e la descrizione. Abbiamo lasciato le opzioni predefinite e continuato semplicemente premendo Invio per entrambe le opzioni.

Punti di ingresso

La prossima cosa che viene chiesta è il punto di ingresso. D'impostazione predefinita è index.js; tuttavia, molte persone preferiscono usare app.js. Non desideriamo entrare in questo dibattito e dato che la nostra applicazione non richiede una struttura di progetto intensiva, abbiamo intenzione di lasciare l'impostazione predefinita index.js.

Dopo che vi sarete ripresi da un dibattito che sarà probabilmente intenso quanto tabs vs. spaces, la configurazione continua, facendo diverse domande:

test command
git repository
keywords
author
license

Ai fini di questo articolo, abbiamo lasciato tutte le opzioni di base. Infine, una volta configurate tutte le opzioni, viene visualizzata una richiesta di conferma del file package.json prima di crearlo. Premete Invio per completare la configurazione.

Immettere l'SDK

Per rendere semplificata l'interazione con Slack, installeremo il pacchetto Slack Developer Kit nel modo seguente:

1	npm install @slack/client --save

Siete finalmente pronti per del codice? Ne siamo certi. Per iniziare, abbiamo intenzione di utilizzare il codice d'esempio dal sito Web del Slack Developer Kit per postare un messaggio Slack utilizzando la Real-Time Messaging API (RTM) con poche modifiche.

Dato che il punto di ingresso che abbiamo scelto è index.js, è il momento di creare questo file. L'esempio dal sito di Slack Developer Kit è di circa 20 righe di codice. Inseriremo alcune linee, solo per consentirne la spiegazione passo passo. Siete pregati di notare che tutte queste linee dovrebbero essere contenute nel file index.js.

Il codice inizia includendo due moduli da Slack Developer Kit:

1	var RtmClient = require('@slack/client').RtmClient;
2	var CLIENT_EVENTS = require('@slack/client').CLIENT_EVENTS;

L'RtmClient, una volta creata un'istanza, sarà il nostro oggetto bot che farà riferimento all'API RTM. I CLIENT_EVENTS sono gli eventi che il bot ascolterà.

Una volta che questi moduli sono inclusi, è il momento di creare un'istanza e avviare il bot:

1	var rtm = new RtmClient('xoxb-*************************************');
2	rtm.start();

Siate certi di sostituire l'API Token oscurato qui sopra con il vostro token ottenuto durante la creazione del Bot Slack.

Chiamando la funzione start sul nostro RtmClient inizializzeremo la sessione del bot. Ciò tenterà di autenticare il nostro bot. Quando il nostro bot sarà connesso correttamente a Slack, gli eventi verranno inviati consentendo alla mia applicazione di procedere. Questi eventi verranno mostrati momentaneamente.

Creata un'istanza del client, una variabile channel viene creata per essere popolata momentaneamente all'interno di uno degli eventi CLIENT_EVENTS.

1	let channel;

La variabile channel verrà utilizzata per eseguire azioni specifiche, quali l'invio di un messaggio al canale cui il bot è connesso.

Quando viene avviata la sessione RTM (rtm.start();) e dato un API Token valido per il bot, un messaggio RTM.AUTHENTICATED verrà inviato. Le successive linee rimangono in ascolto di questo evento:

rtm.on(CLIENT_EVENTS.RTM.AUTHENTICATED, (rtmStartData) => {
  for (const c of rtmStartData.channels) {
      if (c.is_member && c.name ==='jamiestestchannel') { channel = c.id }
  }
  console.log(`Logged in as ${rtmStartData.self.name} of team ${rtmStartData.team.name}`);
});

Quando l'evento RTM.AUTHENTICATED viene ricevuto, il codice precedente esegue un ciclo for attraverso la lista dei canali Slack del team. Nel nostro caso, siamo specificatamente alla ricerca di jamiestestchannel, assicurandoci che il bot sia un membro di quel canale. Quando tale condizione è soddisfatta, l'ID di canale viene memorizzato nella variabile channel.

Debugging

Per facilitare il debug, viene registrato un messaggio di console che visualizza un messaggio che indica che il bot si è autenticato correttamente visualizzando il suo nome (${rtmStartData.self.name}) e il nome del team (${rtmStartData.team.name}) cui esso appartiene.

Dopo che il bot si è autenticato, viene attivato un altro evento (RTM.RTM_CONNECTION_OPENED) che indica che il bot è completamente collegato e può iniziare l'interazione con Slack. Le successive righe di codice creano il listener di eventi; al momento del successo, un messaggio di Hello! viene inviato al canale (nel nostro caso, jamiestestchannel).

1	rtm.on(CLIENT_EVENTS.RTM.RTM_CONNECTION_OPENED, function () {
2	rtm.sendMessage("Hello!", channel);
3	});

A questo punto, possiamo ora eseguire l'applicazione Node e guardare il bot postare automaticamente un nuovo messaggio sul canale:

1	node index.js

I risultati dell'esecuzione di questo comando (quando ha successo) sono duplici:

Abbiamo ricevuto il messaggio di debug che indica che il bot si è autenticato correttamente. Questo proviene dall'attivazione di RTM.AUTHENTICATED dopo aver avviato il Client RTM.
Abbiamo ricevuto un messaggio Hello! sul nostro canale Slack. Questo si è verificato quando il messaggio di evento di RTM.RTM_CONNECTION_OPENED è stato ricevuto e gestito dall'applicazione.

Prima di procedere migliorando ulteriormente la nostra applicazione, è un buon momento per ricapitolare quello che abbiamo fatto per arrivare a questo punto:

Abbiamo creato un Bot personalizzato di Slack.
Abbiamo creato un canale personalizzato di Slack e invitato il nostro bot.
Abbiamo creato una nuova applicazione Node.js chiamata slackbot.
Abbiamo installato il pacchetto Slack Developer Kit nella nostra applicazione.
Abbiamo creato il file index.js che crea un RtmClient utilizzando il nostro API Token dal bot personalizzato.
Abbiamo creato un listener di eventi per RTM.AUTHENTICATED che trova il canale Slack di cui il nostro bot è un membro.
Abbiamo creato un listener di eventi per RTM.RTM_CONNECTION_OPENED che invia un messaggio Hello! al nostro canale Slack.
Abbiamo chiamato il metodo RTM Start Session per iniziare il processo di autenticazione che viene gestito dal nostro listener di eventi.

Costruire il Bot

Ora è il momento di cominciare con il vero divertimento. Slack offre (non abbiamo contato) almeno 50 diversi eventi disponibili per il bot personalizzato per l'ascolto e facoltativamente la gestione. Come si può vedere dall'elenco degli eventi di Slack, alcuni eventi sono personalizzati per l'API RTM (che stiamo usando), mentre altri eventi sono personalizzati per l'API Events. Al momento della scrittura di questo articolo, sappiamo che l'SDK di Node.js supporta solo RTM.

Per finire il bot, gestiremo l'evento message; naturalmente, questo è probabilmente uno degli eventi più complicati dal momento che supporta un gran numero di sottotipi che analizzeremo in un attimo.

Ecco un esempio di come appare il più semplice evento message da Slack:

{
    "type": "message", 
    "channel": "C2147483705", 
    "user": "U2147483697", 
    "text": "Hello world", 
    "ts": "1355517523.000005" 
}

In questo oggetto di base, le tre cose più importanti che ci interessano sono:

channel. Vogliamo assicurarci che il messaggio appartenga al canale di cui il bot è parte.
user. Questo mi permetterà di interagire direttamente con l'utente o eseguire un'azione specifica in base a chi è l'utente.
text. Questo è probabilmente il pezzo più importante in quanto contiene il contenuto del messaggio. Il nostro bot vuole rispondere solo a determinati tipi di messaggi.

Alcuni messaggi sono più complicati. Possono contenere un sacco di proprietà secondarie come:

edited: un oggetto figlio che descrive quale utente ha modificato il messaggio e quando si è verificato.
subtype: una stringa che definisce uno dei molti generi differenti, quali channel_join, channel_leave, etc.
is_starred: un valore booleano che indica se questo messaggio è stato segnato.
pinned_to: array di canali dove questo messaggio è stato puntato.
reactions: un array di oggetti di reazione che definiscono ciò che la reazione è stata (per esempio facepalm), quante volte si è verificata e un vasto array di utenti che hanno reagito in questo modo al messaggio.

Abbiamo intenzione di estendere il nostro index.js creato in precedenza per ascoltare eventi message. Per ridurre la ridondanza del codice, i seguenti esempi conterranno solo la porzione di codice legata al miglioramento di eventi message.

La prima cosa che deve essere fatta è quella di includere un nuovo modulo per RTM_EVENTS su cui saremo in ascolto. Abbiamo inserito questo di seguito ai due precedenti moduli:

1	var RTM_EVENTS = require('@slack/client').RTM_EVENTS;

Il codice per gestire l'evento message che inseriremo nella parte inferiore del file. Per verificare che l'evento message sta lavorando correttamente, abbiamo creato un nuovo listener di eventi che registra l'oggetto message nella console nel modo seguente:

1	rtm.on(RTM_EVENTS.MESSAGE, function(message) {
2	console.log(message);
3	});

Ora possiamo eseguire nuovamente l'applicazione Node (node index.js). Quando digitiamo un messaggio nel canale, nella console viene riportato:

{ 
    type: 'message',
    channel: 'C6TBHCSA3',
    user: 'U17JRET09',
    text: 'hi',
    ts: '1503519368.000364',
    source_team: 'T15TBNKNW',
    team: 'T15TBNKNW' 
}

Fin qui tutto bene. Il nostro bot sta ricevendo correttamente i messaggi. Il prossimo passo è assicurarci che il messaggio appartenga al canale in cui si trova il nostro bot:

1	rtm.on(RTM_EVENTS.MESSAGE, function(message) {
2	if (message.channel === channel)
3	console.log(message);
4	});

Ora quando eseguiamo l'applicazione, vediamo solo il messaggio di debug se l'evento message era per il channel di cui il bot è parte.

Abbiamo quindi intenzione di estendere l'applicazione per inviare un messaggio personalizzato al canale mostrando come un utente può essere taggato in un messaggio:

1	rtm.on(RTM_EVENTS.MESSAGE, function(message) {
2	if (message.channel === channel)
3	rtm.sendMessage("Stop, everybody listen, <@" + message.user + "> has something important to say!", message.channel);
4	});

Ora, quando qualcuno digita un messaggio nel canale, il nostro bot invia il proprio messaggio, qualcosa di simile a: "Stop, ascoltatemi, @endyourif ha qualcosa di importante da dire!"

Ok, non estremamente utile. Al contrario, abbiamo intenzione di completare il bot migliorando il listener di eventi message per rispondere a comandi specifici. Ciò sarà realizzato eseguendo le operazioni seguenti:

Dividere la porzione text di un message in un array basato su uno spazio vuoto.
Verificare se il primo indice corrisponde al nome utente del nostro bot.
In caso affermativo, guarderemo il secondo indice (se ne esiste uno) e lo tratteremo come un comando che deve eseguire il bot.

Per rendere più facile rilevare se il bot è stato accennato, abbiamo bisogno di creare una nuova variabile che memorizzerà l'ID utente del bot. Di seguito una sezione aggiornata del codice dove abbiamo precedentemente impostato la variabile channel. Ora inoltre memorizza l'ID utente del bot in una variabile denominata bot.

let channel;
let bot;

rtm.on(CLIENT_EVENTS.RTM.AUTHENTICATED, (rtmStartData) => {
  for (const c of rtmStartData.channels) {
      if (c.is_member && c.name ==='jamiestestchannel') { channel = c.id }
  }
  console.log(`Logged in as ${rtmStartData.self.name} of team ${rtmStartData.team.name}`);
  
  bot = '<@' + rtmStartData.self.id + '>';
});

Con la variabile bot impostata, abbiamo completato il nostro bot modificando il listener di eventi message creato in precedenza nel modo segue:

rtm.on(RTM_EVENTS.MESSAGE, function(message) {
    if (message.channel === channel) {
  	if (message.text !== null) {
			var pieces = message.text.split(' ');
			
			if (pieces.length > 1) {
				if (pieces[0] === bot) {
					var response = '<@' + message.user + '>';
					
					switch (pieces[1].toLowerCase()) {
						case "jump":
							response += '"Kris Kross will make you jump jump"';
							break;
						case "help":
							response += ', currently I support the following commands: jump';
							break;
						default:
							response += ', sorry I do not understand the command "' + pieces[1] + '". For a list of supported commands, type: ' + bot + ' help';
							break;
					}
					
					rtm.sendMessage(response, message.channel);
				}
			}
		}
	}
});

Il seguente codice divide la proprietà text dell'oggetto message in un array basato su uno spazio. Ci assicuriamo di avere almeno due elementi nell'array, idealmente il nostro bot e il comando da eseguire.

Quando il primo elemento dell'array corrisponde al nostro bot, eseguiremo un'istruzione switch sul secondo elemento dell'array: il comando. I comandi attuali supportati sono jump e help. Quando un messaggio viene inviato al canale che assomiglia a "@jamiestest jump", il bot risponderà con un messaggio speciale all'utente.

Se il comando non viene riconosciuto, ricadrà nel caso di default dell'istruzione switch e risponderà con un comando generico che sarà simile: "@endyourif, mi dispiace non capisco il comando "Ciao". Per un elenco dei comandi supportati, digitare: @jamiestest help".

Conclusione

A questo punto, il nostro bot è completo! Se siete interessati a migliorare ulteriormente il vostro bot, ecco una lista di idee:

Gestire un nuovo membro del team ascoltando l'evento team_join. Quando si aggiunge un nuovo membro del team, sarebbe una grande idea inviare loro una varietà di informazioni onboarding e/o documentazione per accoglierli nel vostro team.
Migliorare l'elenco dei comandi supportati che abbiamo iniziato.
Rendere interattivi i comandi di ricerca in un database, Google, YouTube, etc.
Creare un utente bot su un'applicazione e creare i vostri comandi slash personalizzati.