Vittorio Nardone

7 min

La monetizzazione delle API è un trend in forte crescita. E’ ormai un business consolidato delle aziende digitali far utilizzare, a pagamento, le API che accedono ai dati aziendali o ad alcuni servizi già erogati secondo canali differenti.

Un possibile canale di diffusione delle proprie API e dei propri servizi è l’integrazione con piattaforme esistenti e molto note, come ad esempio Slack. Se il proprio servizio o le proprie API possono essere utili e di valore nell’ambito di un meeting, di una chat di progetto o durante le attività di customer care, allora realizzare un’integrazione per Slack potrebbe rivelarsi redditizia.

Ma cosa c’è dietro l’integrazione di API esistenti con Slack? Quanto è complesso pubblicare il classico pulsante “Add to Slack” sul proprio sito web? Vediamolo in questa guida passo passo.

Creare un App

In Slack è possibile creare le proprie app o utilizzarne di esistenti. Le più complete e professionali sono elencate nel App Directory. Si trova ogni cosa, dall’integrazione con Google Calendar, a Zoom e GitHub. Normalmente le app consentono di aggiungere funzionalità ai propri canali, fornendo l’integrazione con servizi già esistenti. Un’app può dialogare con i partecipanti ad un canale inviando messaggi di suggerimento e notifiche oppure rispondendo a comandi ben specifici. L’app può “esprimersi” sotto forma di bot oppure agire come se fossimo direttamente noi a inviare messaggi. Insomma: le potenzialità sono illimitate!

Creare la propria app è semplice: basta raggiungere il portale api e seguire le indicazioni di “Create New App”.

Prima di addentrarci negli step successivi di creazione di un app, è meglio chiarire come questa può essere distribuita su Slack.

Installazione nel proprio Workspace

Di default, quando creiamo un App su Slack, la stessa può essere installata sul proprio workspace. Chiunque sia invitato a partecipare al medesimo, può quindi interagire e usufruire della stessa. Se intendiamo realizzare un applicazione dedicata esclusivamente al nostro team, non è richiesto altro effort.

Distribuzione

Se l’app che intendiamo realizzare deve poter essere installata e condivisa su altri workspace, per esempio a livello aziendale, è necessario attivare la “distribuzione” dell’applicazione. Questo consente la creazione del classico pulsante “Add to Slack” e comporta l’implementazione di un flusso OAuth 2.0 per gestire il processo di autorizzazione.

App Directory

L’App Directory è una sorta di marketplace di Slack dove vengono elencate per categoria tutte le applicazioni che hanno superato un processo di verifica. Lo stesso è condotto direttamente da un Team di Slack che si assicura che l’applicazione abbia i necessari requisiti tecnici e qualitativi. E’ ovvio che se intendiamo monetizzare le nostre API tramite un’integrazione, la pubblicazione su App Directory ci consentirà di avere un pubblico decisamente più ampio e ne gioverà anche la reputazione dell’applicazione, in quanto già verificata da Slack stessa.

Pubblicare la propria app nella Directory ufficiale è però ovviamente un processo più complesso, che prevede un lungo elenco di requisiti da soddisfare.

Interazione

Abbiamo creato la nostra app, che però non svolge ancora alcuna funzione. A seconda del servizio che vogliamo integrare in Slack, per prima cosa è meglio decidere come la nostra applicazione andrà ad interagire sui canali Slack. Esistono diverse possibilità: l’app potrà essere invocata con uno “slash command” oppure nel caso di specifici eventi.

Gli “slash command” sono i tipici comandi di Slack preceduti appunto da una slash come, ad esempio /INVITE. Nel caso invece degli eventi, è possibile richiamare l’app quando la stessa viene per esempio citata (@nomeapp) durante una conversazione oppure quando le vengono inviati dei messaggi diretti.

Personalmente ho scelto questo secondo approccio, basato su eventi, ma non esiste una sola soluzione ottimale: dipende dal servizio che stiamo integrando e dalle UX che vogliamo fornire. Nessuno ci vieta, inoltre, di prevedere entrambe le modalità.

Integrazione

Come integrare il nostro servizio e le relative API esistenti? Sarà necessario realizzare un layer dedicato, in grado di rispondere alle richieste da parte di Slack e interagire con gli utenti, da un lato, e in grado di richiamare le nostre API dall’altro lato.

Di cosa si deve occupare questo layer di integrazione? Vediamolo:

• Ricevere gli eventi da parte di Slack e rispondere di conseguenza, erogando il servizio fornito dalle nostre API
• Gestire il processo di autorizzazione OAuth 2.0
• Gestire subscription e billing o integrarsi con una piattaforma di E-Commerce

Sottoscrizione agli eventi

Abbiamo deciso di ricevere delle notifiche quando si verifica un evento di interesse per la nostra app. Dobbiamo innanzitutto specificare l’endpoint a cui verranno notificati questi eventi.

Dovremo rispondere alla richiesta utilizzando il parametro challenge come indicato per validare il nostro endpoint. Dopo averlo Impostato potremo quindi specificare quali notifiche vogliamo ricevere.

Gli eventi sono ben descritti: message.im si verifica, per esempio, quando viene inviato un messaggio direct alla nostra app, tipicamente nel relativo channel privato.

Il concetto di Scope è fondamentale da comprendere: per poter ricevere alcune notifiche è necessario che la nostra applicazione abbia ottenuto l’autorizzazione ad un particolare scope; nell’esempio precedente, im:history. Vedremo che tale autorizzazione verrà richiesta durante il processo di autorizzazione dell’app.

Tutto qui? Non direi. E’ opportuno fare in modo che il nostro layer di integrazione verifichi inoltre le richieste per assicurarsi che provengano proprio dai server di Slack: non vogliamo certo pubblicare un servizio a pagamento e poi essere frodati giusto?

L’algoritmo di verifica delle richieste è indicato in questo articolo tratto dalla documentazione ufficiale. Richiede l’utilizzo del Signing Secret, un parametro che Slack attribuisce ad ogni applicazione e che è possibile trovare nella sezione App Credentials della propria applicazione.

Personalmente mi sono occupato di realizzare un layer di integrazione totalmente serverless, utilizzando API Gateway e AWS Lambda. Ecco riportata un estratto della funzione di risposta agli eventi, che prevede inoltre l’eventuale decodifica Base64.

Le notifiche sono in formato JSON e ben documentate. Un esempio di payload relativo a message:im è qui.

Cos’è l’evento app_home_opened? Si verifica quando l’utente che ha installato la nostra app ne apre la sezione corrispondente. E’ utilizzabile per inviare un messaggio di benvenuto e spiegare, per esempio, come utilizzare l’app. E’ bene ricordarsi di questo evento perché la sua corretta gestione è uno dei requirement alla pubblicazione nel App Directory.

Gli eventi disponibili sono molti e permettono di personalizzare la UX della propria integrazione.

Autorizzazione

Il processo di autorizzazione OAuth 2.0 è documentato molto chiaramente.

Il processo di autorizzazione è composto dai seguenti step:

1. L’utente avvia il processo di installazione cliccando su “Add to Slack”. Il codice HTML del pulsante può essere facilmente ottenuto dalla pagina della propria app. L’URL richiamata dal pulsante sarà gestita dal nostro integration layer che si occuperà di rispondere con un redirect (302) verso l’URL di autorizzazione di Slack (https://slack.com/oauth/v2/authorize) specificando almeno i parametri client_id e scope che sono obbligatori. Il primo parametro identifica la nostra app e il suo valore è disponibile nella sezione App Credentials. Il secondo specifica invece le varie autorizzazioni che intendiamo richiedere per la nostra app (scope).
2. L’utente autorizza l’installazione dell’applicazione
3. Un primo code di autorizzazione viene fornito al nostro integration layer alla redirect URL specificata nella sezione OAuth & Permissions della nostra applicazione
4. L’integration layer si occupa di richiedere il token di autorizzazione richiamando l’URL dedicato (https://slack.com/api/oauth.v2.access) e specificando i parametri client_id e client_secret, oltre al code appena ottenuto
5. In caso di risposta positiva, il token viene memorizzato dall’integration layer in modo da poter essere utilizzato per interagire con il workspace relativo

Ecco un esempio di una Lambda function in grado di gestire il processo, memorizzando i token ottenuti in una tabella DynamoDB.

UX & Pagamenti

Abbiamo terminato? No, siamo solo all’inizio! Abbiamo realizzato due funzioni, la prima delle quali è in grado di ricevere le notifiche relative agli eventi che ci interessa gestire con la nostra app. La seconda si occupa invece di gestire correttamente il processo di autorizzazione.

Dobbiamo ora rimboccarci le maniche e implementare la vera integrazione tra Slack e il nostro servizio o API. Il package Python slackclient ci permette di interagire con le API Web Client in modo da poter, per esempio, postare un messaggio in risposta ad uno specifico direct. Come già detto all’inizio di questo post, le possibilità sono infinite e dipendono molto dal servizio che si vuole integrare.

I messaggi Slack possono essere arricchiti di elementi per renderli più funzionali e accattivanti. La struttura di ciascun messaggio è composto da blocchi. L’ottimo editor consente di sperimentare il layout dei messaggi prima di implementarli nella propria app.

Dovremo inoltre gestire l’integrazione con la piattaforma di E-Commerce al fine di gestire le sottoscrizioni al nostro servizio. Personalmente ho utilizzato Paddle.

Pubblicazione su App Directory

La nostra App è pronta? Abbiamo testato le sue funzionalità, il processo di installazione e l’integrazione con la piattaforma di E-Commerce? Benissimo! Siamo pronti alla pubblicazione in App Directory? Non ancora.

Il processo di pubblicazione prevede la verifica, da parte del team di Slack, di una serie di requisiti che la nostra App deve soddisfare. Ce ne sono molti, divisi in sezioni e che consiglio di leggere attentamente.

Il processo di verifica è molto scrupoloso e ci possono volere alcuni giorni per ottenere un feedback. Se anche solo uno dei requisiti non è soddisfatto, viene segnalato e si deve procedere ad una nuova submission, ovviamente dopo aver corretto la propria app.

Prepariamoci quindi a dover realizzare, ad esempio, landing page per il supporto al cliente e per la propria privacy policy. Un attenzione particolare va riposta agli scope richiesti, che andranno motivati dettagliatamente.

Se abbiamo realizzato tutto nella maniera corretta, la nostra app sarà finalmente presente nella Directory di Slack e inizieremo a monetizzare il nostro servizio.. o almeno speriamo!

Ci siamo divertiti? Alla prossima!