Implementar la API con Amazon Web Services

En este documento, se muestra la manera de usar Amazon Web Services (AWS) para implementar la API de WhatsApp Business. El proceso se puede dividir en dos pasos principales:

1. Implementación del cliente de la API de WhatsApp Business
2. Configuración del cliente de la API de WhatsApp Business

Una vez que completes la configuración, podrás actualizar el cliente. Si en alguna ocasión debes reiniciar la app web y la app principal, sigue estos pasos.

Primeros pasos

Antes de empezar, necesitarás hacer lo siguiente:

• Configurar un identificador de la cuenta de AWS
• Crear un par de claves de AWS
• Suscribirte a una imagen de CentOS 9
• Hacer la implementación en una región admitida

Configurar un identificador de la cuenta de AWS

Debes configurar una cuenta de AWS válida y estar familiarizado con el funcionamiento de AWS. WhatsApp proporciona plantillas de CloudFormation para implementar con facilidad el cliente de la API de WhatsApp Business. Consulta el Centro de recursos de primeros pasos de AWS para obtener más información.

Crear un par de claves de AWS

Debes crear un nuevo par de claves para acceder a la instancia de EC2 que se creó con la plantilla de la API de WhatsApp Business. También puedes usar un par de claves creado anteriormente. Consulta la documentación sobre pares de claves EC2 de Amazon para obtener información sobre cómo crear y usar pares de claves con una instancia de EC2.

Suscribirte a una imagen de CentOS 9

El cliente de la API de WhatsApp Business utiliza una imagen de CentOS 9 (disponible en AWS Marketplace). Antes de usar la plantilla, se deben revisar y aceptar las condiciones. Si no se aceptan las condiciones, no se podrá crear la plantilla.

Para revisar y aceptar la imagen AMI de CentOS 9, sigue estos pasos:

1. Ve a la página de AWS Marketplace: CentOS 9 (x86_64) - with Updates HVM.
2. Haz clic en Continue to Subscribe en la esquina superior derecha. Luego, haz clic en el botón Accept Terms.

Regiones admitidas

Las plantillas de la API de WhatsApp Business utilizan el tipo de recurso EFS, lo cual no está disponible en todas las regiones de AWS. Por lo tanto, en la actualidad solo se admiten las siguientes regiones:

• Virginia del Norte (us-east-1)
• Ohio (us-east-2)
• Norte de California (us-west-1)
• Oregón (us-west-2)
• Bombay (ap-south-1)
• Seúl (ap-northeast-2)
• Singapur (ap-southeast-1)
• Sídney (ap-southeast-2)
• Tokio (ap-northeast-1)
• Fráncfort (eu-central-1)
• Irlanda (eu-west-1)

Preguntas frecuentes

Implementación

Paso 1: Configuración de la red [Opcional]

La red de nube privada virtual (VPC) se crea, generalmente, al registrarse para obtener una cuenta de AWS. Además, puede haber varias personalizaciones y restricciones de control de accesos necesarias que sean específicas del negocio de una empresa.

Si ya está creada la infraestructura de la red VPC, puedes omitir este paso. De lo contrario, puedes usar la plantilla siguiente para crear la infraestructura de red en AWS.

Requisitos de red

• Debe haber por lo menos dos subredes en diferentes zonas de disponibilidad dentro de la región. De lo contrario, no se podrá crear la plantilla mientras se crea el recurso RDS (base de datos).
• Debe permitir el acceso entrante a HTTP (puerto: 80), HTTPS (puerto: 443) y SSH (puerto: 22). Por motivos de seguridad, se recomienda usar HTTPS y evitar HTTP.

Para realizar la implementación de la red:

1. Dirígete a la consola de CloudFormation correspondiente a tu región (por ejemplo, eu-west-1).
2. Selecciona Create a stack.
3. Descarga el archivo wa_ent_net.yml de GitHub y guárdalo a nivel local.
4. Elige Upload a template file como fuente de plantilla y carga el que descargaste en el paso 3.
   

   Crear pila
5. Haz clic en Siguiente.
6. En la pantalla Specify stack details, introduce los valores de los parámetros de acuerdo con la tabla siguiente:

Parámetros

Configuración de zonas de disponibilidad

Configuración de VPC

Configuración de subred pública

Configuración de subred privada

Paso 2: Subida de archivos de configuración de base de datos y pila de supervisión

Antes de implementar la pila de la API de WhatsApp Business en AWS, debes subir archivos de configuración de las subpilas de referencia a un contenedor S3 al que tengas acceso de lectura.

1. Crea un nuevo contenedor S3 o usa uno preexistente al que tengas acceso de lectura.
2. Descarga los archivos wa_ent_db.yml y wa_ent_monitoring.yml de GitHub y súbelos al contenedor S3 mencionado en el paso 1.
3. Elige el archivo wa_ent_db.yml de la lista de objetos y copia su URL. Debe estar en el formato de https://xxx.s3.<avalability_zone>.amazonaws.com/wa_ent_db.yml.
4. En el archivo wa_ent.yml, reemplaza el valor de TemplateURL en dbStack por la URL de objeto del paso 3 y guarda el archivo.
5. Elige el archivo wa_ent_monitoring.yml de la lista de objetos y copia su URL. Debe estar en el formato de https://xxx.s3.<avalability_zone>.amazonaws.com/wa_ent_monitoring.yml.
6. En el archivo wa_ent.yml, reemplaza el valor de TemplateURL en la pila de supervisión por la URL de objeto del paso 5 y guarda el archivo.

Subida al contenedor S3

Paso 3: Implementación de la API de WhatsApp Business

WhatsApp Enterprise es la plantilla principal y crea todos los recursos (excepto la red) necesarios para el cliente de la API de WhatsApp Business. Como se ya se indicó, esta plantilla también crea un recurso de base de datos, si es necesario.

Para implementar el cliente de la API de WhatsApp Business:

1. Ve a la consola de CloudFormation correspondiente a tu región (por ejemplo, eu-west-1).
2. Selecciona Create a stack.
3. Descarga el archivo wa_ent.yml de GitHub y guárdalo a nivel local.
4. Elige Upload a template file como fuente de plantilla y carga el que descargaste en el paso 3.
   

   Crear pila
5. Haz clic en Next
   .
6. A continuación, podrás introducir parámetros. Consulta las descripciones de los parámetros en la siguiente tabla.
   
7. Después de configurar todos los parámetros (en las tablas a continuación), haz clic en Next en la página Configure stack options. Puedes hacer los cambios necesarios según tus preferencias y hacer clic en Next.
8. En la página Review stack, verás un resumen de valores de parámetros y opciones de pila. Después de la verificación, en la sección Capabilities, marca las dos casillas y haz clic en Submit para comenzar a crear la pila.
   Nota: La implementación tarda entre 20 y 30 minutos.
   

Parámetros

Configuración general

Configuración de red

Configuración de contenedores

Configuración de bases de datos

Configuración de inicio de sesión

Configuración del sistema de archivos

Configuración de seguridad

Punto de acceso de la API de WhatsApp Business

Estos parámetros son obligatorios para que los paneles de Grafana recuperen métricas de aplicación con fines de supervisión.

Grafana

Resultado tras la implementación

Al finalizar correctamente la creación de la plantilla, se generarán los siguientes parámetros:

• Load balancer name: nombre de host del equilibrador de carga para acceder al cliente de la API de WhatsApp Business.
• Database hostname: nombre de host de la base de datos que se creó o se proporcionó al crear la plantilla.
• Database port number: número de puerto de la conexión de base de datos.
• ECS cluster name: nombre del clúster de ECS creado.
• Log retention days: número de días para la retención de registros.
• DB connection CA: valor de CA de conexión de DB, si está configurado.
• DB connection cert: valor del certificado de conexión de DB, si está configurado.
• DB connection key: valor de la clave de conexión de DB, si está configurado.
• Grafana: URL del panel de Grafana.
• ShardCount: número de fragmentos que se configurarán en la API de la plataforma de WhatsApp Business.

Edición de reglas de seguridad de SSH

De forma predeterminada, las reglas de seguridad creadas por la pila permiten que todo el tráfico pueda alcanzar las instancias de EC2 a través de SSH, los puntos de conexión de API y el panel de Grafana a través de HTTPs, y los contenedores de cadvisor y Prometheus. Por motivos de seguridad, se recomienda mucho que bloquees el acceso innecesario. En esta sección, se mostrarán, a modo de ejemplo, los pasos para actualizar la regla de seguridad de SSH. Siempre debes restringir el acceso de SSH solo a tráfico en el que confíes.

1. En la sección Security Groups de la consola de EC2 (por ejemplo: EC2 Management Console [amazon.com]):
   1. Selecciona la región correcta en la esquina superior derecha.
   2. Selecciona el grupo de seguridad que contiene <stackName>-EcsSecurityGroup y pasa a la pestaña Inbound Rules.
      

      Editar reglas de entrada
   3. Selecciona Edit inbound rules y actualiza la columna Source para permitir que solo el tráfico confiable (por ejemplo: Mi IP) acceda a hosts de EC2 a través de SSH.
      
   4. Después de ajustar todas las reglas de seguridad, haz clic en Save rules para aplicar los cambios.
   5. Repite estos cambios en el grupo de seguridad que contiene "<stackName>-ms-xxx-EcsSecurityGroup", a fin de restringir el acceso de SSH a la pila de monitoreo.

Configuración del cliente de la API de WhatsApp Business

Una vez que se implementó correctamente el cliente de la API de WhatsApp Business, es necesario configurarlo para ponerlo en funcionamiento.

Paso 1: Registro del teléfono

Consulta la guía para números de teléfono, a fin de obtener información más detallada sobre el registro del número de teléfono.

Descarga el certificado codificado mediante Base64 desde tu cuenta de WhatsApp en el Facebook Business Manager bajo la pestaña Números de teléfono del administrador de WhatsApp.

Cuando tengas el número de teléfono correcto seleccionado y el certificado codificado mediante Base64, deberás registrar el cliente de la API de WhatsApp Business a través del nodo account. Consulta la documentación de registro para obtener más información.

Paso 2: Configurar fragmentos

Después de crear la pila, debes hacer uso de la llamada a la API shards para aumentar el número de instancias activas de las app principales y así lograr el rendimiento deseado. La cantidad de fragmentos se puede consultar en la sección de resultados de la pila.

Paso 3: Actualizar la configuración

La configuración de las devoluciones de llamadas web de la API de WhatsApp Business y otros parámetros se describe en la documentación sobre configuración de la aplicación. Para lograr un rendimiento estable, se recomienda la siguiente configuración en la aplicación.

 {
    "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"
    }
}

      
      
    

Paso 4: Configurar la SSL [opcional]

El cliente de la API de WhatsApp Business genera un certificado autofirmado de forma predeterminada en el momento de su creación. Es posible que el certificado de la autoridad de certificación (CA) que se utilizó para generar el certificado autofirmado sea necesario para verificar el extremo del cliente de la API de WhatsApp Business y evitar una advertencia de confianza de certificado.

Puedes descargar el certificado de CA y almacenarlo localmente para evitar la advertencia de confianza de certificado, o bien subir uno propio. Para obtener más información, consulta la documentación sobre el nodo certificate.

Paso 5: Validación de la configuración

Una vez que completes correctamente los pasos de configuración y registro, puedes enviar y recibir un mensaje para validar la funcionalidad básica del cliente de la API de WhatsApp Business. Esta operación se describe detalladamente en la documentación sobre los mensajes.

Después de recibir correctamente el mensaje, el cliente de la API de WhatsApp Business enviará una solicitud POST con el estado o los detalles del mensaje al webhook que se configuró en el Paso 4.

Si el mensaje se recibió correctamente, ¡felicitaciones, terminaste! Para obtener más información sobre los extremos de API disponibles, consulta la Documentación referencia de la API.

Reinicio de la app principal y la app web

Para reiniciar el cliente de la API de WhatsApp Business, en la consola ECS (por ejemplo, https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/clusters), sigue estos pasos:

1. Selecciona la región correcta en la esquina superior derecha.
2. Selecciona el grupo adecuado de la lista.
3. En la pestaña Services, selecciona el nombre del servicio que contiene WAEntService.
4. Selecciona la pestaña Tasks. Normalmente, debería haber una sola tarea con un identificador compuesto de dígitos hexadecimales.
5. En la ventana Tasks, haz clic en Stop en la esquina superior derecha y, a continuación, haz clic de nuevo en Stop cuando se te solicite.

Se detendrán la app web y la app principal. En breve, la infraestructura de AWS reiniciará la app web y la app principal.

Actualización

En esta sección, se explica cómo actualizar el cliente de la API de WhatsApp Business y la plantilla de CloudFormation (CFN). Si se realiza una actualización, se ocasionará un tiempo de inactividad. No envíes mensajes durante ese tiempo. Vuelve a enviar mensajes después de que se haya completado la actualización.

Puedes actualizar simultáneamente la plantilla de CFN y la versión del cliente de la API de WhatsApp Business si se realizan los siguientes pasos:

1. En el paso 5 de las instrucciones de actualización del cliente de la API de WhatsApp Business, selecciona Use current template en vez de Replace current template.
2. En la sección "Specify template", elige la opción "Upload a template file" y, luego, selecciona el más reciente que se haya descargado de GitHub.

Actualización del cliente de la API de WhatsApp Business

1. Ve a la consola de CFN (por ejemplo, https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks?filter=active).
2. Selecciona la región correcta en la esquina superior derecha.
3. Selecciona la pila del cliente de la API de WhatsApp Business que ya se creó.
4. Haz clic en Update.
5. En la página Prerequisite - Prepare template, selecciona la opción Replace current template. En la sección Specify template, elige la opción "Upload a template file" y, luego, selecciona el más reciente que se haya descargado de GitHub. Haz clic en Next.
6. En la página Specify stack details, cambia el valor de WhatsApp Business API Client (container) version por la versión deseada. NO CAMBIES ningún otro parámetro. Haz clic en Next.
7. En la página Configure stack options, haz clic en Next.
8. En la página Review, selecciona “I acknowledge that AWS CloudFormation might create IAM resources with custom names”. Revisa la sección Change set preview para detectar cambios inesperados. Si existen cambios inesperados o si tienes dudas, ponte en contacto con el equipo de asistencia directa de WhatsApp. Haz clic en Update stack. Es posible realizar el seguimiento del estado de actualización de la pila en la consola de CFN, que cambiará de UPDATE_IN_PROGRESS a UPDATE_COMPLETE cuando finalice la actualización.

Actualización de la plantilla de CFN de WhatsApp

1. Ve a la consola de CFN (por ejemplo, https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks?filter=active).
2. Selecciona la región correcta en la esquina superior derecha.
3. Selecciona la pila del cliente de la API de WhatsApp Business que ya se creó.
4. Haz clic en Update.
5. En la página Prerequisite - Prepare template, selecciona la opción Replace current template. En la sección Specify template, elige la opción "Upload a template file" y, luego, selecciona el más reciente que se haya descargado de GitHub. Haz clic en Next.
6. En la página Specify Stack Details, introduce los parámetros correspondientes de conformidad con la información de las secciones anteriores. Haz clic en Next.
7. En la página Configure Stack Options, haz clic en Nex.
8. En la página Review, selecciona "I acknowledge that AWS CloudFormation might create IAM resources with custom names". Revisa la sección Change set preview para detectar cambios inesperados. Si existen cambios inesperados o si tienes dudas, ponte en contacto con el equipo de asistencia directa de WhatsApp. Haz clic en Update stack. Es posible realizar el seguimiento del estado de actualización de la pila en la consola de CFN, que cambiará de UPDATE_IN_PROGRESS a UPDATE_COMPLETE cuando finalice la actualización.

Cómo reducir manualmente la carga cuando tu sistema esté inactivo (opcional)

Es común que las empresas busquen configurar un entorno de alto rendimiento para una campaña de tiempo limitado y mantener un entorno de carga reducida cuando no haya campañas en curso. En esta sección se ofrecen sugerencias sobre cómo reducir manualmente la escala del entorno de AWS para reducir la carga.

1. En la consola de ECS (p. ej., Amazon ECS):
   1. Selecciona la región correcta en la esquina superior derecha.
   2. Selecciona el grupo adecuado de la lista.
   3. En la pestaña Services, selecciona el nombre del servicio que contiene WAEntCoreappService. Selecciona Editar servicio y actualiza el valor "Tareas deseadas" a 0.
      

      Configuración de implementación
   4. Repite el paso C para todos los demás servicios, incluidos WAEntWebService, WAEntMasterService y HostExporterService.
   5. Regresa a la página de clústeres en la pestaña Tareas y asegúrate de que no haya en ejecución tareas de los servicios anteriores.
2. En la sección Auto Scaling Groups de la consola de EC2 (p. ej., Auto Scaling Groups | EC2 Management Console [amazon.com]):
   1. Selecciona la región correcta en la esquina superior derecha.
   2. Selecciona el grupo de escalamiento automático de la pila con HAECSAutoScalingGroup en el nombre y elige Editar. Actualiza la “Capacidad deseada” y la “Capacidad mínima” a 3.
      

      Tamaño de grupo
   3. Selecciona el grupo de escalamiento automático de la pila con HAECSAutoScalingGroupWeb en el nombre y elige Editar. Actualiza los campos "Desired capacity" y "Minimum capacity" a 2.
3. (Opcional) Si el valor inicial de "Type of message" es cualquiera de los tipos de imágenes, puedes reemplazar los tipos de instancias de EC2 por la opción c5.large, que supone menos carga.
   1. En la sección Launch Templates de la consola de EC2, selecciona la plantilla de lanzamiento correspondiente en la lista.
   2. Selecciona Actions - Modify template (create new version).
      

      Sección Launch Templates de la consola
   3. En la sección Instance type, actualiza la el tipo de instancia a c5.large y, luego, selecciona Create template version.
      

      Tipo de instancia
   4. En la sección Auto Scaling Groups de la consola de EC2, selecciona el grupo de escalamiento automático de la pila que tenga HAECSAutoScalingGroup en el nombre.
   5. Selecciona Edit en la sección Launch template.
   6. Selecciona la nueva plantilla de lanzamiento creada en el paso 3c y elige Update.
      

      Plantilla de lanzamiento
4. En la consola de RDS (p. ej., RDS Management Console [amazon.com]):
   1. Selecciona la región correcta en la esquina superior derecha.
   2. Selecciona la base de datos de Aurora adecuada de la lista.
   3. Selecciona Modify y actualiza la clase de instancia de DB a r5.xlarge.
      

      Configuración de instancias
5. En la consola de ECS (p. ej., Amazon ECS):
   1. Selecciona la región correcta en la esquina superior derecha.
   2. Selecciona el grupo adecuado de la lista.
   3. En la pestaña Services, selecciona el nombre del servicio que contiene WAEntCoreappService. Selecciona Edit Service y actualiza el valor "Desired tasks" a 3.
   4. En la pestaña Services, selecciona el nombre del servicio que contiene HostExporterService. Selecciona Edit Service y actualiza el valor "Desired tasks" a 3.
   5. En la pestaña Services, selecciona el nombre del servicio que contiene WAEntWebService. Selecciona Edit Service y actualiza el valor "Desired tasks" a 2.
   6. En la pestaña Services, selecciona el nombre del servicio que contiene WAEntMasterService. Selecciona Edit Service y actualiza el valor "Desired tasks" a 2.
6. Espera hasta que todos los servicios lancen el número de tareas deseado. Una vez que todas las tareas estén en ejecución, usa la API para establecer fragmentos para restablecerlos a 2.
7. Valida el estado del sistema con la API de estado. También se puede enviar y recibir un mensaje para validar la funcionalidad básica del cliente de la API de WhatsApp Business. Esta operación se describe detalladamente en la documentación sobre los mensajes.