L’API di Discourse può essere utilizzata per automatizzare l’invio di email di invito dal tuo forum quando viene eseguita un’azione su un’applicazione esterna. Per molte applicazioni, puoi utilizzare Zapier per configurarlo senza dover scrivere codice.
Un caso d’uso comune per questo è invitare gli utenti sul tuo forum quando acquistano un prodotto o si iscrivono a un servizio esterno. Per l’esempio in questo argomento utilizzerò l’integrazione Zapier WordPress per attivare l’invio di un invito da Discourse quando un nuovo utente si iscrive a un sito WordPress.
Configura un passaggio di attivazione (trigger step) su Zapier
Vai alla tua dashboard di Zapier e cerca l’applicazione che desideri attivi l’email di invito. Nelle schermate seguenti, ho selezionato WordPress come attivatore (trigger).
L’unica configurazione richiesta per questo è collegare lo Zap di WordPress a un account WordPress e selezionare l’evento Nuovo Utente (New User) per attivare lo Zap.
Configura un passaggio di azione (action step) per inviare l’invito
Fai clic sul pulsante Aggiungi un passaggio (Add a Step) e quindi fai clic su Azione/Ricerca (Action/Search) dal menu a discesa.
Inserisci ‘webhook’ nel menu di ricerca e quindi seleziona Webhooks by Zapier dal menu delle azioni. Il passaggio di azione Webhook verrà aggiunto alla barra laterale del tuo Zap e si aprirà un modulo che ti consente di scegliere quale tipo di richiesta desideri che esegua il webhook.
Seleziona POST dal modulo e quindi fai clic su Continua (Continue).
Il modulo che si apre ti consente di configurare la richiesta POST che viene inviata a Discourse. Nel campo URL, inserisci l’URL di base del tuo forum, seguito da /invites. Ad esempio, l’URL di base del mio forum è https://demo.scossar.com, quindi il link completo alla rotta degli inviti è https://demo.scossar.com/invites
Ora devi configurare le sezioni Payload Type, Data e Headers del modulo. Tutte le altre sezioni del modulo possono essere lasciate con i loro valori predefiniti.
Il Payload Type indica a Zapier in quale formato inviare il payload. Dovrebbe essere impostato su Json.
La sezione Dati (Data) viene utilizzata per indicare a Discourse quale indirizzo email inviare l’invito e per impostare un elenco opzionale di nomi di gruppi e un messaggio personalizzato. Per invitare un utente senza aggiungerlo a gruppi o includere un messaggio personalizzato, inserisci il testo email come Chiave dati (Data Key) e quindi fai clic sull’icona ‘Inserisci un campo’ (Insert a Field) per aprire il menu a discesa del campo. Scorri l’elenco fino a quando non vedi il valore che è stato passato dalla tua app di attivazione che contiene l’email dell’utente. Quando si utilizza WordPress come app di attivazione, la sezione Dati completata dovrebbe apparire simile a questa:
Per aggiungere automaticamente gli utenti ai gruppi quando accettano l’invito, fai clic sull’icona 
della sezione Dati per aggiungere un nuovo campo. Imposta la Chiave del campo su group_names. Imposta il Valore del campo su un elenco di nomi di gruppi separati da virgole che desideri vengano aggiunti gli utenti. Per includere un messaggio personalizzato nell’email di invito, crea un altro campo con la sua Chiave impostata su custom_message e il suo valore impostato sul messaggio che desideri inviare.
Nota: aggiungendo un passaggio di Codice (Code step) dopo il passaggio di attivazione del tuo Zap, dovrebbe essere possibile impostare dinamicamente i nomi dei gruppi e un messaggio personalizzato per utenti specifici.
La sezione Intestazioni (Headers) viene utilizzata per autenticare la tua richiesta. Per configurare il campo Headers, dovrai generare una chiave API sul tuo sito Discourse. Per farlo, vai alla pagina Amministrazione / API del tuo sito Discourse e fai clic sul pulsante “Nuova chiave API” (New API Key). Durante la creazione della chiave, assegnala a un utente dello staff e imposta l’ambito su Globale (Global), oppure utilizza un ambito Granulare (Granular) con la casella Inviti > Crea (Invites > Create) spuntata.
Ora, nella sezione Headers dello Zap, inserisci le seguenti coppie chiave/valore. Sostituisci qualsiasi valore che ho incluso tra parentesi quadre con valori appropriati per il tuo sito. La distinzione tra maiuscole e minuscole nei nomi delle chiavi è importante.
Api-Username: <l'username dello staff che vuoi invii gli inviti>
Api-Key: <la chiave API che hai generato>
Content-Type: application/json
Il modulo dovrebbe ora apparire simile allo screenshot seguente, ma con il tuo Api-Username e Api-Key:
Fai clic sul pulsante Continua (Continue).
Ora sarai in grado di testare l’integrazione facendo clic sul pulsante ‘Invia Test a Webhooks by Zapier’ (Send Test To Webhooks by Zapier). Il test verrà eseguito con i dati che hai impostato nel passaggio di attivazione. Vedrai un messaggio di successo se tutto è configurato correttamente e, se l’utente che hai impostato nel passaggio di attivazione non esiste ancora sul tuo forum Discourse, verrà inviata un’email di invito e vedrai un messaggio di successo su Zapier. Una volta che il passaggio di test ha successo, fai clic sul pulsante Termina (Finish) e attiva il tuo Zap.
Per dettagli su come eseguire altri tipi di richieste all’API di Discourse con Zapier, consulta Make requests to the Discourse API with Zapier.
