Integrare WhatsApp e Amazon Connect Chat

Una delle funzionalità di Amazon Connect consente di inviare e ricevere messaggi tramite la chat web , è però possibile includere anche messaggistica mobile come WhatsApp. Nel caso di quest’ultimo, la configurazione è strutturata in parti diverse: in questo senso può venirci in aiuto il progetto whatsapp-amazonconnect-chat, che pone le basi per l'integrazione tramite la sandbox per Whatsapp di Twilio.

Twilio è una piattaforma che mette a disposizione vari servizi per l’interfaccia del codice del software con i vari canali di comunicazione collegati alla telefonia: tra questi rientrano appunto gli account WhatsApp, che richiedono di avere un numero di telefono associato

Sia Twilio che Amazon Connect applicano una tariffa ai messaggi scambiati che varia a seconda del paese. In Italia il costo per messaggio di entrambi i servizi è circa 4 centesimi di dollaro, per un costo totale di circa 8 centesimi di dollaro a messaggio. La tariffa scende quando si superano certe quantità di messaggi scambiati per mese.

L'immagine riassume in breve le parti messe in gioco nello scambio dei messaggi:

1. L'utente manda un messaggio tramite smartphone a un numero Whatsapp del supporto che sta cercando di contattare.
2. L'account di Whatsapp associato al numero è gestito da Twilio: attraverso la sandbox chiama l'indirizzo che abbiamo indicato in fase di configurazione della sandbox per informarlo della ricezione del messaggio.
3. L'indirizzo che riceve notifica del messaggio espone un server node eseguito in una macchina di nostra proprietà sul servizio EC2 di Amazon Web Services, che annota i dettagli della connessione su un database dynamoDB (sempre fornito da AWS) e apre una sessione di chat su Amazon Connect, dove quindi inoltra il messaggio con la struttura riadattata.
4. L'agente riceve il messaggio nello stesso posto dove riceve i messaggi di tutti gli altri servizi integrati, senza quindi bisogno di utilizzare l'applicazione di Whatsapp e mantenendo i benefici di Amazon Connect; ad esempio, la possibilità di far seguire due chat da due operatori diversi situati fisicamente in luoghi diversi.

Cosa serve per attivare questo sistema?

Come prima cosa, è necessario avviare un'instanza EC2 nella quale andrà installato nodejs, clonato il progetto https://github.com/tamdilip/whatsapp-amazonconnect-chat ed installate le sue dipendenze.

# dopo aver installato nodejs
$ git clone https://github.com/tamdilip/whatsapp-amazonconnect-chat.git
$ cd whatsapp-amazonconnect-chat
$ npm i

Per proseguire, possiamo approfondire nella cartella /config del repository il file di configurazione env.js, che ci dà una lista di parametri da riempire interamente, affinché il tutto funzioni correttamente.

Questi parametri andrebbero impostati come variabili d'ambiente, tuttavia è possibile anche modificare il file env.js in modo da sostituire i vari process.env.NOMEPARAMETRO direttamente con il suo rispettivo valore (tra virgolette ")

module.exports = {
  TABLE_NAME: process.env.TABLE_NAME,
  TWILIO_WHATSAPP_NUM: process.env.TWILIO_WHATSAPP_NUM,
  TWILIO_ACCOUNT_SID: process.env.TWILIO_ACCOUNT_SID,
  TWILIO_AUTH_TOKEN: process.env.TWILIO_AUTH_TOKEN,
  ACCESS_KEY: process.env.ACCESS_KEY,
  SECRET_ACCESS_KEY: process.env.SECRET_ACCESS_KEY,
  CONNECT_INSTANCE_ID: process.env.CONNECT_INSTANCE_ID,
  CONNECT_CONTACT_FLOW_ID: process.env.CONNECT_CONTACT_FLOW_ID,
  CONNECT_SOURCE_NUMBER: process.env.CONNECT_SOURCE_NUMBER,
  CONNECT_DESTINATION_NUMBER: process.env.CONNECT_DESTINATION_NUMBER
};

TABLE_NAME ci suggerisce che abbiamo bisogno di una tabella su dynamoDB il cui nome andrà indicato in questo campo. In particolare la tabella richiede di avere come chiave primaria "customerNumber".

TWILIO_WHATSAPP_NUM, TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN sono rispettivamente il numero di telefono, l'account SID e il token di autenticazione che ci sono stati forniti da Twilio:

•  Il primo necessita di prefisso ed è quello indicato in questa pagina del proprio account su Twilio, preceduto dalla stringa 'whatsapp:', producendo quindi una cosa come questa: "whatsapp:+000000000000".
• Il SID e l'AUTH Token sono quelli indicati in questa pagina di Twilio (Le TEST Credentials permettono solo di ricevere ma non di inviare messaggi, per testare entrambe le direzioni occorrono invece le LIVE Credentials).

ACCESS_KEY, SECRET_ACCESS_KEY sono le credenziali AWS di un “utente ad accesso programmatico”, generabili in AWS IAM, al quale vanno assegnate le policy che gli permettono di accedere ad Amazon Connect e a DynamoDB.

Il CONNECT_INSTANCE_ID è indicato nella parte finale della stringa ARN, quella che segue "instance/", che è visibile cliccando sull'alias dell'istanza di connect a questa pagina. 

Anche il CONNECT_CONTACT_FLOW_ID è indicato nella parte finale della sua stringa ARN.

Per vederla occorre accedere alla propria istanza di Amazon Connect col nome utente e password impostati alla prima configurazione e premere quindi l'icona con le 3 freccette sul menù di sinistra, quindi “contact flows”, scegliere il flow interessato e cliccare sul suo nome per raggiungere la pagina corrispondente. In questo modo nell'url della pagina che si apre sarà visibile l'ARN e di conseguenza l'id del contact flow.

Il CONNECT_SOURCE_NUMBER è sempre il numero fornito da Twilio, ma a differenza del TWILIO_WHATSAPP_NUM non deve essere preceduto da nessuna stringa, mentre il CONNECT_DESTINATION_NUMBER rappresenta la stringa alternativa che sarà mostrata nel caso non sia possibile risalire al numero di telefono del destinatario.

Gli indirizzi degli endpoint dell'applicazione vanno indicati alla pagina della sandbox di Whatsapp del proprio account di Twilio (questa). 

Questi indirizzi devono essere degli indirizzi HTTPS, pertanto in produzione occorrerà preoccuparsi di configurare un certificato per la macchina ec2. Per testare che il tutto funzioni possiamo invece usare temporaneamente il software ngrok, un software che ha la funzione di esporre pubblicamente la porta che gli indichiamo su un indirizzo randomico, per farlo basta lanciare i seguenti comandi:

# installa ngrok globalmente utilizzando npm
$ npm install ngrok -g
# lancia ngrok esponendo la porta 3000 e annotando sul file "ngrok.log" gli output del comando
$ ngrok http 3000 --log=stdout > ngrok.log &
# stampa la riga contenente "https://" del contenuto del file ngrok.log
$ cat ngrok.log | grep https://

Copiando e aprendo l'indirizzo generato da ngrok su browser si dovrebbe vedere il messaggio di errore "Failed to complete tunnel connection", che sarà sostituito dal messaggio "I am alive :)" una volta che il software whatsapp-amazonconnect-chat verrà avviato con il comando `npm start`.

Una volta ottenuta questa risposta abbiamo quindi conferma che il server sta funzionando e ci basta riportare a questa pagina del nostro account di Twilio l'indirizzo nei seguenti 2 campi:

“when a message comes in”: va compilato con “https://INDIRIZZONGROK.ngrok.io” , come “HTTP Post”

“status callback url”: va compilato con “https://INDIRIZZONGROK.ngrok.io/status-callback” , come “HTTP Post”

Se abbiamo impostato tutto correttamente, all'invio di un messaggio tramite whatsapp al numero fornito da Twilio dovrebbe squillare il softphone di Amazon Connect.