Implementazione con Amazon Web Services

Questo documento mostra la modalità di utilizzo di Amazon Web Services (AWS) per l'implementazione dell'API di WhatsApp Business. Il processo può essere diviso in due passaggi principali:

1. Implementazione del client dell'API di WhatsApp Business
2. Configurazione del client dell'API di WhatsApp Business

Dopo aver completato la configurazione, puoi scegliere di aggiornare il client. Se hai bisogno di riavviare sia Webapp sia CoreApp, segui questi passaggi.

Primi passi

Prima di iniziare dovrai:

• Configurare un ID dell'account AWS.
• Creare una coppia di chiavi AWS.
• Attivare l'iscrizione a un'immagine CentOS 9.
• Implementare in un'area geografica supportata.

Configurazione di un ID dell'account AWS

Devi configurare un account AWS valido e conoscere il funzionamento di AWS. WhatsApp fornisce modelli CloudFormation per facilitare l'implementazione del client dell'API di WhatsApp Business. Per ulteriori informazioni, consulta il Centro risorse per le nozioni di base su AWS.

Creazione di una coppia di chiavi AWS

Devi creare una nuova coppia di chiavi per accedere all'istanza EC2 creata dal modello dell'API di WhatsApp Business. Puoi anche utilizzare una coppia di chiavi creata in precedenza. Consulta la documentazione sulle coppie di chiavi Amazon EC2 per informazioni sulla creazione e sull'utilizzo di coppie di chiavi con un'istanza EC2.

Attivazione dell'iscrizione a un'immagine CentOS 9

Il client dell'API di WhatsApp Business utilizza un'immagine CentOS 9 (disponibile nell'AWS Marketplace). Prima di utilizzare il modello, devi controllare e accettare le condizioni. La mancata accettazione delle condizioni comporterà la mancata creazione del modello.

Per controllare e accettare l'immagine AMI CentOS 9:

1. Accedi alla pagina AWS Marketplace: CentOS 9 (x86_64) - with Updates HVM.
2. Clicca su Continue to Subscribe (Continua per attivare iscrizione) nell'angolo in alto a destra, quindi clicca sul pulsante Accept Terms (Accetta le condizioni).

Aree geografiche supportate

I modelli dell'API di WhatsApp Business utilizzano il tipo di risorsa EFS, che non è disponibile in tutte le aree geografiche AWS. Attualmente, sono supportate solo le seguenti aree geografiche:

• N. Virginia (us-east-1)
• Ohio (us-east-2)
• N. California (us-west-1)
• Oregon (us-west-2)
• Mumbai (ap-south-1)
• Seoul (ap-northeast-2)
• Singapore (ap-southeast-1)
• Sydney (ap-southeast-2)
• Tokyo (ap-northeast-1)
• Francoforte (eu-central-1)
• Irlanda (eu-west-1)

FAQ

Implementazione

Passaggio 1: [facoltativo] configurazione di rete

La rete Virtual Private Cloud (VPC) viene generalmente creata quando crei un account AWS. Per una specifica azienda potrebbero inoltre essere disponibili diverse personalizzazioni e necessarie numerose limitazioni di controllo dell'accesso.

Se l'infrastruttura di rete VPC è già stata creata, è possibile saltare questo passaggio. In caso contrario, il seguente modello può essere utilizzato per creare l'infrastruttura di rete su AWS.

Requisiti di rete

• Devono essere presenti almeno due subnet in diverse aree di disponibilità all'interno dell'area geografica. In caso contrario, la creazione del modello avrà esito negativo durante la creazione della risorsa RDS (database).
• Deve consentire l'accesso in entrata a HTTP (porta: 80), HTTPS (porta: 443) e SSH (porta: 22). Per motivi di sicurezza, si consiglia vivamente di utilizzare HTTPS ed evitare HTTP.

Per l'implementazione del modello di rete:

1. Accedi alla console CloudFormation per la tua area geografica (ad esempio, eu-west-1).
2. Seleziona Create a stack (Crea uno stack).
3. Scarica il file wa_ent.yml da GitHub e salvalo in locale.
4. Scegli Upload a template file (Carica un file modello) come sorgente del modello e carica il file modello scaricato durante il passaggio 3.
   

   Creazione dello stack
5. Clicca su Next (Avanti).
6. Nella schermata Specify stack details (Specifica dettagli stack) inserisci i valori dei parametri secondo la tabella seguente:

Parametri

Configurazione delle aree di disponibilità

Configurazione della rete VPC

Configurazione della subnet pubblica

Configurazione della subnet privata

Passaggio 2: caricamento del database e monitoraggio dei file di configurazione dello stack

Prima dell'implementazione dello stack dell'API di WhatsApp Business su AWS, devi caricare i file di configurazione dei substack indicati in un bucket S3 per cui hai accesso in lettura.

1. Crea un nuovo bucket S3 oppure utilizza un bucket S3 esistente per cui hai accesso in lettura.
2. Scarica i file wa_ent_db.yml e wa_ent_monitoring.yml da GitHub e carica entrambi nel bucket S3 indicato nel passaggio 1.
3. Scegli il file wa_ent_db.yml dalla lista Objects (Oggetti) e copia l'URL. Dovrebbe avere il formato https://xxx.s3.<avalability_zone>.amazonaws.com/wa_ent_db.yml.
4. Nel file wa_ent.yml, sostituisci il valore di TemplateURL in dbStack con l'URL dell'oggetto del passaggio 3 e salva il file.
5. Scegli il file wa_ent_monitoring.yml dalla lista Objects (Oggetti) e copia l'URL. Dovrebbe avere il formato https://xxx.s3.<avalability_zone>.amazonaws.com/wa_ent_monitoring.yml.
6. Nel file wa_ent.yml, sostituisci il valore dello stack TemplateURL in Monitoring con l'URL dell'oggetto del passaggio 5 e salva il file.

Caricamento nel bucket S3

Passaggio 3: implementazione dell'API di WhatsApp Business

WhatsApp Enterprise rappresenta il modello principale e crea tutte le risorse (tranne la rete) necessarie per il client dell'API di WhatsApp Business. Come notato in precedenza, questo modello crea anche una risorsa del database, se necessario.

Per l'implementazione del client dell'API di WhatsApp Business:

1. Accedi alla console CloudFormation per la tua area geografica (ad esempio, eu-west-1).
2. Seleziona Create a stack (Crea uno stack).
3. Scarica il file wa_ent.yml da GitHub e salvalo a livello locale.
4. Scegli Upload a template file (Carica un file modello) come sorgente del modello e carica il file modello scaricato durante il passaggio 3.
   

   Creazione dello stack
5. Clicca su Next
   (Avanti).
6. A questo punto potrai inserire i parametri. Consulta la tabella riportata di seguito per le descrizioni dei parametri.
   
7. Una volta impostati tutti i parametri (nelle tabelle seguenti), clicca su Next (Avanti) nella pagina Configure stack options (Configurazione delle opzioni di stack). Puoi apportare le modifiche necessarie in base alle preferenze e cliccare su Next (Avanti).
8. Nella pagina Review stack (Controllo stack), vedrai un riepilogo dei valori dei parametri e delle opzioni di stack. Dopo la verifica, nella sezione Capabilities (Funzionalità), seleziona entrambe le caselle e clicca su Submit (Invia) per iniziare la creazione dello stack.
   Nota: l'implementazione dura circa 20-30 minuti.
   

Parametri

Configurazione generale

Configurazione di rete

Configurazione del contenitore

Configurazione del database

Configurazione della registrazione

Configurazione del file system

Configurazione della sicurezza

Punto di accesso all'API di WhatsApp Business

Questi parametri sono necessari per permettere alle dashboard di Grafana di recuperare le metriche dell'app per scopi di monitoraggio.

Grafana

Output dopo l'implementazione

Dopo aver creato correttamente il modello, verranno visualizzati i seguenti parametri:

• Load balancer name (Nome servizio di bilanciamento del carico): nome host del servizio di bilanciamento del carico per accedere al client dell'API di WhatsApp Business
• Database hostname (Nome host database): nome host del database creato o fornito durante la creazione del modello
• Database port number (Numero porta database): numero della porta per la connessione al database
• ECS cluster name (Nome cluster ECS): nome del cluster ECS creato
• Log retention days (Giorni di conservazione del registro): numero di giorni per la conservazione dei registri
• DB connection CA (CA connessione DB): valore di CA della connessione al database se configurata
• DB connection cert (Certificato connessione DB): valore del certificato della connessione al database se configurata
• DB connection key (Chiave connessione DB): valore della chiave della connessione al database se configurata
• Grafana: URL della dashboard di Grafana
• ShardCount: numero di partizioni per la configurazione per l'API della piattaforma WhatsApp Business

Modifica delle regole di sicurezza SSH

Per impostazione predefinita, le regole di sicurezza create dallo stack consentono a tutto il traffico di poter raggiungere le istanze EC2 tramite SSH, gli endpoint dell'API e la dashboard di Grafana tramite HTTP, e i contenitori cadvisor e Prometheus. Per motivi di sicurezza, si consiglia vivamente di chiudere gli accessi non necessari. Come esempio, questa sezione illustra i passaggi per l'aggiornamento della regola di sicurezza SSH. Dovresti sempre limitare l'accesso SSH al solo traffico di cui ti fidi.

1. In EC2 - Security Groups console (EC2 - Console gruppi di sicurezza) (ad esempio: EC2 Management Console (Console di gestione EC2) (amazon.com)):
   1. Seleziona l'area geografica corretta nell'angolo in alto a destra.
   2. Seleziona il gruppo di sicurezza che contiene <stackName>-EcsSecurityGroup, poi passa alla tab Inbound Rules (Regole in entrata).
      

      Modifica delle regole in entrata
   3. Seleziona Edit inbound rules (Modifica regole in entrata), aggiorna la colonna Source (Origine) per consentire solo al traffico attendibile (ad esempio: My IP [Il mio IP]) di accedere agli host EC2 tramite SSH.
      
   4. Dopo aver regolato tutte le regole di sicurezza, clicca Save rules (Salva regole) per applicare le modifiche.
   5. Ripeti queste modifiche per il gruppo di sicurezza che contiene "<stackName>-ms-xxx-EcsSecurityGroup" per limitare l'accesso SSH per lo stack di monitoraggio.

Configurazione del client dell'API di WhatsApp Business

Dopo aver implementato correttamente il client dell'API di WhatsApp Business, è necessario configurarlo per renderlo operativo.

Passaggio 1: registrazione del telefono

Consulta la Guida per il numero di telefono per ulteriori informazioni dettagliate sulla registrazione del numero di telefono.

Scarica il certificato con codifica base64 dal tuo account WhatsApp nel Business Manager di Facebook nella tab Numeri di telefono di WhatsApp Manager.

Dopo aver selezionato il numero di telefono e il certificato con codifica base64 corretti, è necessario registrare il client dell'API di WhatsApp Business tramite il nodo account. Consulta la documentazione sulla registrazione per maggiori informazioni.

Passaggio 2: configurazione delle partizioni

Dopo la creazione dello stack, devi utilizzare la chiamata API shards per aumentare il numero di istanze Coreapp attive per raggiungere il throughput desiderato. Il numero di partizioni è disponibile nella sezione Output dello stack.

Passaggio 3: aggiornamento delle impostazioni dell'app

La configurazione delle callback web dell'API di WhatsApp Business e di altri parametri è descritta nella documentazione sulle impostazioni dell'app. Per ottenere un throughput stabile, si consigliano le seguenti impostazioni dell'app.

 {
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "db_garbagecollector_enable": false, # change this to true when there are no ongoing messaging campaigns
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "document",
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio"
                ]
            },
            "notify_user_change_number": true,
            "pass_through": false,
            "sent_status": true,
            "show_security_notifications": false,
            "skip_referral_media_download": false,
            "unhealthy_interval": 30,
            "wa_id": "12245552741",
            "webhooks": {
                "max_concurrent_requests": 24,
                "message": {
                    "delivered": true,
                    "read": true,
                    "sent": true
                },
                "url": "<YOUR_WEBHOOK_SERVER_URL>"
            }
        }
    },
    "meta": {
        "api_status": "stable",
        "version": "2.41.3"
    }
}

      
      
    

Passaggio 4: [facoltativo] configurazione SSL

Al momento della creazione, il client dell'API di WhatsApp Business genera un certificato autofirmato per impostazione predefinita. Il certificato di Autorità di certificazione (CA) utilizzato per generare il certificato autofirmato potrebbe essere necessario per verificare l'endpoint del client dell'API di WhatsApp Business ed evitare un avviso di attendibilità del certificato.

Puoi scaricare il certificato CA e archiviarlo localmente per evitare l'avviso di attendibilità del certificato oppure caricarne uno in tuo possesso. Consulta la documentazione sul nodo certificate per maggiori informazioni.

Passaggio 5: convalida della configurazione

Dopo aver completato correttamente i passaggi di configurazione e registrazione, è possibile inviare e ricevere un messaggio per convalidare le funzionalità di base del client dell'API di WhatsApp Business. Questa operazione è descritta in dettaglio nella documentazione sui messaggi.

Al momento della corretta ricezione del messaggio, il client dell'API di WhatsApp Business eseguirà il POST dello stato/dei dettagli del messaggio sul webhook configurato nel Passaggio 3.

Se il messaggio è stato ricevuto correttamente, è tutto pronto: congratulazioni! Consulta la documentazione di riferimento per ulteriori informazioni sugli endpoint API disponibili.

Riavvio di Coreapp e Webapp

Per riavviare il client dell'API di WhatsApp Business, nella console ECS, ad esempio, https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/clusters):

1. Seleziona l'area geografica corretta nell'angolo in alto a destra.
2. Seleziona il cluster appropriato dalla lista.
3. Nella tab Services (Servizi), seleziona il nome del servizio che contiene WAEntService.
4. Seleziona la tab Tasks (Attività). Di solito dovrebbe essere presente una sola attività, con un ID composto da cifre esadecimali.
5. Nella finestra Tasks (Attività), clicca su Stop (Interrompi) nell'angolo in alto a destra, quindi clicca di nuovo su Stop (Interrompi) quando richiesto.

Questa operazione interromperà Webapp e CoreApp. In breve tempo, l'infrastruttura AWS riavvierà sia Webapp sia CoreApp.

Aggiornamento

Questa sezione illustra la modalità di aggiornamento sia dell'API di WhatsApp Business sia del modello CloudFormation (CFN). L'esecuzione di un aggiornamento comporterà un periodo di inattività, quindi non inviare messaggi in questo intervallo di tempo, fino a quando l'aggiornamento non sarà completato.

Puoi aggiornare il modello CFN e la versione client dell'API di WhatsApp Business nello stesso momento procedendo come segue:

1. Al Passaggio 5 delle istruzioni per l'aggiornamento del client dell'API di WhatsApp Business, al posto di Use current template (Usa modello corrente) seleziona Replace current template (Sostituisci modello corrente).
2. Nella sezione Specify template (Specifica modello), scegli "Upload a template file" (Carica un file modello) e scegli l'ultimo file modello scaricato da GitHub.

Aggiornamento del client dell'API di WhatsApp Business

1. Accedi alla console CFN (ad esempio, https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks?filter=active).
2. Seleziona l'area geografica corretta nell'angolo in alto a destra.
3. Seleziona lo stack del client dell'API di WhatsApp Business già creato.
4. Clicca su Update (Aggiorna).
5. Nella pagina Prerequisite - Prepare template (Prerequisiti - Prepara modello), seleziona l'opzione Replace current template (Sostituisci modello corrente). Nella sezione Specify template (Specifica modello), scegli "Upload a template file" (Carica un file modello) e scegli l'ultimo file modello scaricato da GitHub. Clicca su Next (Avanti).
6. Nella pagina Specify stack details (Specifica dettagli stack), cambia WhatsApp Business API Client (container) version (Versione [contenitore] del client dell'API di WhatsApp Business) nella versione desiderata. NON CAMBIARE nessun altro parametro. Clicca su Next (Avanti).
7. Nella pagina Configure stack options (Configura opzioni stack), clicca su Next (Avanti).
8. Nella pagina Review (Controllo), seleziona "I acknowledge that AWS CloudFormation might create IAM resources with custom names" (Riconosco che AWS CloudFormation potrebbe creare risorse IAM con nomi personalizzati). Rivedi la sezione Change set preview (Cambia anteprima impostata) per eventuali modifiche impreviste. In caso di modifiche impreviste o dubbi, contatta l'Assistenza diretta di WhatsApp. Clicca su Update stack (Aggiorna stack). Lo stato Stack Update (Aggiornamento stack) può essere monitorato nella console CFN e cambierà da UPDATE_IN_PROGRESS a UPDATE_COMPLETE al termine dell'aggiornamento.

Aggiornamento del modello CFN di WhatsApp

1. Accedi alla console CFN console (ad esempio, https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks?filter=active).
2. Seleziona l'area geografica corretta nell'angolo in alto a destra.
3. Seleziona lo stack del client dell'API di WhatsApp Business già creato.
4. Clicca su Update (Aggiorna).
5. Nella pagina Prerequisite - Prepare template (Prerequisiti - Prepara modello), seleziona l'opzione Replace current template (Sostituisci modello corrente). Nella sezione Specify template (Specifica modello), scegli "Upload a template file" (Carica un file modello) e scegli l'ultimo file modello scaricato da GitHub. Clicca su Next (Avanti).
6. Nella pagina Specify Stack Details (Specifica dettagli stack), inserisci i parametri appropriati, seguendo le informazioni contenute nelle sezioni precedenti. Clicca su Next (Avanti).
7. Nella pagina Configure Stack Options (Configura opzioni stack), clicca su Next (Avanti).
8. Nella pagina Review (Controllo), seleziona "I acknowledge that AWS CloudFormation might create IAM resources with custom names" (Riconosco che AWS CloudFormation potrebbe creare risorse IAM con nomi personalizzati). Rivedi la sezione Change set preview (Cambia anteprima impostata) per eventuali modifiche impreviste. In caso di modifiche impreviste o dubbi, contatta l'Assistenza diretta di WhatsApp. Clicca su Update stack (Aggiorna stack). Lo stato Stack Update (Aggiornamento stack) può essere monitorato nella console CFN e cambierà da UPDATE_IN_PROGRESS a UPDATE_COMPLETE al termine dell'aggiornamento.

Modalità di riduzione manuale dei costi quando il sistema è inattivo (facoltativo)

È comune che le aziende desiderino configurare un ambiente con throughput elevato per una campagna limitata nel tempo e mantenere attivo un ambiente a basso costo durante il periodo non dedicato alla campagna. Questa sezione offre dei suggerimenti su come ridurre manualmente la configurazione AWS per risparmiare sui costi.

1. Nella console ECS (ad es: Amazon ECS):
   1. Seleziona l'area geografica corretta nell'angolo in alto a destra.
   2. Seleziona il cluster appropriato dalla lista.
   3. Nella tab Services (Servizi), seleziona il nome del servizio che contiene WAEntCoreappService. Scegli Edit Service (Modifica servizio) e aggiorna il valore "Desired tasks" (Attività desiderate) a 0.
      

      Configurazione dell'implementazione
   4. Ripeti il passaggio C per tutti i servizi, inclusi WAEntWebService, WAEntMasterService e HostExporterService.
   5. Torna alla pagina del cluster, nella tab Tasks (Attività), assicurati che non ci siano attività in esecuzione dei servizi indicati in precedenza.
2. Nella console EC2 - Auto Scaling Groups (ECS - Riduzione automatica gruppi) (ad es: Auto Scaling groups | EC2 Management Console (Riduzione automatica gruppi - Console di gestione ECS) (amazon.com)):
   1. Seleziona l'area geografica corretta nell'angolo in alto a destra.
   2. Seleziona il gruppo da ridurre automaticamente dello stack con HAECSAutoScalingGroup nel nome e scegli Edit (Modifica). Aggiorna sia "Desired capacity" (Capacità desiderata) sia "Minimum capacity" (Capacità minima) a 3.
      

      Dimensioni del gruppo
   3. Seleziona il gruppo da ridurre automaticamente dello stack con HAECSAutoScalingGroupWeb nel nome e scegli Edit (Modifica). Aggiorna sia "Desired capacity" (Capacità desiderata) sia "Minimum capacity" (Capacità minima) a 2.
3. (Facoltativo) Se il valore iniziale di "Type of message" (Tipo di messaggio) è uno qualsiasi dei tipi di immagine, puoi sostituire i tipi di istanza EC2 con l'opzione più economica di c5.large.
   1. Nella console EC2 - Launch Templates (EC2 - Avvio modelli), seleziona il modello di avvio appropriato dalla lista.
   2. Seleziona Actions - Modify template (create new version) (Azioni - Modifica modello [crea nuova versione]).
      

      Console Avvio modelli
   3. Nella sezione Instance type (Tipo di istanza), aggiorna il tipo di istanza a c5.large, poi scegli Create template version (Crea versione modello).
      

      Tipo di istanza
   4. Nella console EC2 - Auto Scaling Groups (ECS - Riduzione automatica gruppi) seleziona il gruppo da ridurre automaticamente dello stack con HAECSAutoScalingGroup nel nome.
   5. Seleziona Edit (Modifica) nella sezione Launch template (Modello di avvio).
   6. Seleziona il nuovo modello di avvio creato durante il passaggio 3C e scegli Update (Aggiorna).
      

      Modello di avvio
4. Nella console RDS (ad es.: RDS Management Console (Console di gestione RDS) (amazon.com)):
   1. Seleziona l'area geografica corretta nell'angolo in alto a destra.
   2. Seleziona il database Aurora appropriato dalla lista.
   3. Seleziona Modify (Modifica) e aggiorna la classe di istanza del database a r5.xlarge.
      

      Configurazione dell'istanza
5. Nella console ECS (ad es.: Amazon ECS):
   1. Seleziona l'area geografica corretta nell'angolo in alto a destra.
   2. Seleziona il cluster appropriato dalla lista.
   3. Nella tab Services (Servizi), seleziona il nome del servizio che contiene WAEntCoreappService. Scegli Edit Service (Modifica servizio) e aggiorna il valore "Desired tasks" (Attività desiderate) a 3.
   4. Nella tab Services (Servizi), seleziona il nome del servizio che contiene HostExporterService. Scegli Edit Service (Modifica servizio) e aggiorna il valore "Desired tasks" (Attività desiderate) a 3.
   5. Nella tab Services (Servizi), seleziona il nome del servizio che contiene WAEntWebService. Scegli Edit Service (Modifica servizio) e aggiorna il valore "Desired tasks" (Attività desiderate) a 2.
   6. Nella tab Services (Servizi), seleziona il nome del servizio che contiene WAEntMasterService. Scegli Edit Service (Modifica servizio) e aggiorna il valore "Desired tasks" (Attività desiderate) a 2.
6. Attendi che tutti i servizi avviino il numero desiderato di attività. Dopo che tutte le attività sono in esecuzione, usa API Set Shards per reimpostare le partizioni a 2.
7. Convalida lo stato di salute del sistema con l'API Health. È anche possibile inviare e ricevere un messaggio per convalidare la funzionalità di base del client dell'API di WhatsApp Business. Questa operazione è descritta in dettaglio nella documentazione sui messaggi.