API de instalaciones locales de la Plataforma de WhatsApp Business

Configuración de desarrollador: alta disponibilidad y multiconexión

En este documento, se muestra cómo configurar un clúster de alta disponibilidad en un equipo de desarrollador. Además, se proporciona orientación sobre cómo habilitar la multiconexión y sobre los cambios necesarios para un clúster de alta disponibilidad y multiconexión. Para configurar la producción, sigue las instrucciones correspondientes que se indican en Instalaciones de producción.

Antes de empezar con estas configuraciones, consulta nuestra lista de requisitos.

Para configurar un clúster de alta visibilidad, sigue estos pasos:

  1. Crea un directorio biz para los scripts de configuración
  2. Obtén los archivos de configuración del cliente de la API de WhatsApp Business
  3. Configura la variable de entorno WA_API_VERSION
  4. Inicia el cliente de la API de WhatsApp Business con alta disponibilidad
  5. Verifica que los contenedores se estén ejecutando
  6. Ejecuta una comprobación de estado
  7. Registra el cliente de la API de WhatsApp Business
  8. Ejecuta una comprobación de estado

Para configurar un clúster de multiconexión, sigue estos pasos:

  1. Configura dos fragmentos
  2. Ejecuta una comprobación de estado
  3. Inicia una tercera app principal para mantener la alta disponibilidad
  4. Ejecuta otra comprobación de estado

Una vez que hayas configurado por completo tu instancia, podrás optar por actualizarla. Para desinstalar el cliente, sigue estos pasos.

Antes de empezar

Si ya seguiste las instrucciones de Instalación de desarrollador: una sola instancia para configurar un cliente de la API de WhatsApp Business en un equipo de desarrollador, sigue la Guía de migración antes de continuar con el resto de este documento.

El contenido de esta guía se basa en la suposición de una instalación desde cero.

Antes de empezar, necesitarás completar lo siguiente:

Install Docker Desktop

To install Docker Desktop on your developer machine:

  1. Navigate to the Docker website.
  2. If you do not have an existing Docker account, create one by clicking on Sign Up.
  3. After you have created your account, you will be directed to the Docker download page.
  4. Download Docker Desktop based on your OS (This should be automatically detected and presented as the default option).

The remaining steps are based on macOS and should be very similar for Linux or Windows 10.

To install Docker using macOS:

  1. Install the package (docker.dmg for macOS).
  2. After extraction, Finder will pop-up and you will be presented with a dialog that instructs you to drag the Docker icon to Applications. Drag Docker icon to the Application folder in Finder.
  3. In Applications launch Docker and then click the Open button.
  4. You may be prompted to enter your password Docker needs priviledged/administrator access.
  5. Docker will present you with a tutorial, you can click Start to launch a tutorial or you can click Skip Tutorial to start using Docker.

Verify Docker Compose is installed

Docker Compose is a plugin that is bundled with Docker Desktop and should have installed automatically. For more information about using or Docker Compose, see Overview of Docker Compose. If for some reason Docker Compose was not installed, you can install it by following the instructions located at Install Docker Compose.

Otros requisitos previos

Asegúrate de configurar una cuenta de prueba local en un entorno de desarrollo. Es útil para un desarrollo rápido y para poner a prueba nuevos lanzamientos. También se recomienda que leas detenidamente la Guía sobre disponibilidad y expansión para obtener más información sobre la alta disponibilidad y la multiconexión.

Configuración de un clúster de alta disponibilidad

Paso 1: Crea un directorio biz para los scripts de configuración

Ejecuta el siguiente código en tu ubicación preferida para el cliente de la API de WhatsApp Business:

mkdir ~/biz; cd ~/biz;

Paso 2: Obtén los archivos de configuración del cliente de la API de WhatsApp Business

Los archivos de configuración para el cliente de la API de WhatsApp Business se ubican en el repositorio WhatsApp-Business-API-Setup-Scripts de GitHub. Puedes configurar tu cliente de la API de WhatsApp Business con una instancia de base de datos de Postgres o de MySQL.

Paso 3: Configura la variable de entorno WA_API_VERSION

La variable de entorno WA_API_VERSION debería configurarse con la versión actual mediante lo siguiente:

export WA_API_VERSION=current-whatsapp-version

Paso 4: Inicia el cliente de la API de WhatsApp Business con alta disponibilidad

Para iniciar un clúster de alta disponibilidad con 1 contenedor de base de datos, 1 contenedor de app web, 2 contenedores de objeto maestro y 2 contenedores de app principal en segundo plano de manera similar al diagrama que se muestra en la Introducción a la opción de alta disponibilidad, ejecuta el siguiente comando:

docker-compose -f multiconnect-compose.yml up -d db waweb master1 master2 wacore1 wacore2

El resultado se verá como en el siguiente ejemplo:

Creating network "biz_default" with the default driver
Creating volume "biz_mysqlData" with local driver
Creating volume "biz_whatsappMedia" with local driver
Creating biz_db_1 ... done
Creating biz_waweb_1 ... done
Creating biz_master1_1 ... done
Creating biz_master2_1 ... done
Creating biz_wacore2_1 ... done
Creating biz_wacore1_1 ... done

Paso 5: Verifica que los contenedores se estén ejecutando

Para comprobar si todos los contenedores tienen el estado UP, ejecuta lo siguiente:

docker-compose -f multiconnect-compose.yml ps

El resultado se verá como en el siguiente ejemplo:

      Name                    Command               State                                                 Ports
--------------------------------------------------------------------------------------------------------------------------------------------------------------
biz_db_1        docker-entrypoint.sh mysqld      Up      0.0.0.0:33060->3306/tcp, 33060/tcp
biz_master1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32931->6250/tcp, 0.0.0.0:32930->6251/tcp, 0.0.0.0:32928->6252/tcp, 0.0.0.0:32926->6253/tcp
biz_master2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32929->6250/tcp, 0.0.0.0:32927->6251/tcp, 0.0.0.0:32925->6252/tcp, 0.0.0.0:32924->6253/tcp
biz_wacore1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32937->6250/tcp, 0.0.0.0:32935->6251/tcp, 0.0.0.0:32933->6252/tcp, 0.0.0.0:32932->6253/tcp
biz_wacore2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32939->6250/tcp, 0.0.0.0:32938->6251/tcp, 0.0.0.0:32936->6252/tcp, 0.0.0.0:32934->6253/tcp
biz_waweb_1     /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

De manera predeterminada, el contenedor de la app web se ejecutará en el puerto 9090, y el contenedor de base de datos se ejecutará en el puerto 33060.

Paso 6: Ejecuta una comprobación de estado

Puedes descargar y configurar nuestra colección de Postman para interactuar con la API de WhatsApp Business si no quieres utilizar la línea de comandos.

Puedes ejecutar una comprobación de estado en el cliente de la API de WhatsApp Business mediante una llamada a la API enviada al nodo health.

El resultado se verá como en el siguiente ejemplo:

{
    "health": {
      "master1:b28d835cd579": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "master2:7fe542d305b4": {
          "gateway_status": "unregistered",
          "role": "primary_master"
      },
      "wacore1:35a5fabfc79d": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "wacore2:05e1a6d70665": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      }
  }
}

La respuesta muestra un gateway_status de unregistered como gateway_status para el contenedor de objeto maestro principal, porque el cliente de la API de WhatsApp Business aún no está registrado.

Paso 7: Registra el cliente de la API de WhatsApp Business

Puedes registrar tu cliente de la API de WhatsApp Business mediante una llamada a la API enviada al nodo account.

Paso 8: Ejecuta otra comprobación de estado

Ejecuta otra comprobación de estado en el cliente de la API de WhatsApp Business mediante una llamada a la API enviada al nodo health después de completar el proceso de registro y asegúrate de que uno de los contenedores de app principal tenga un gateway_status de connected.

El resultado se verá como en el siguiente ejemplo:

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

Nota: En el modo de alta disponibilidad, se conectará solo una app principal (en este ejemplo, wacore1) al servidor de WhatsApp; todos los demás nodos, incluido el objeto maestro principal, tendrán un gateway_status de disconnected. Si wacore1 falla, wacore2 lo reemplazará y se conectará al servidor de WhatsApp para mantener la alta disponibilidad.

Con esto, finaliza la configuración del cliente de la API de WhatsApp Business en el modo de alta disponibilidad. En este modo, solo puede conectarse al servidor de WhatsApp una app principal por vez para enviar mensajes. Si deseas que varias apps principales envíen mensajes a la vez para aumentar el rendimiento de los mensajes, sigue los pasos que se describen a continuación, en la sección Configurar un clúster de alta disponibilidad y multiconexión.

Configurar un clúster de alta disponibilidad y multiconexión

Paso 1: Configura dos fragmentos

Utiliza el punto de conexión de las particiones para configurar 2 fragmentos. Debes ver una respuesta HTTP con un estado 201 Created.

Paso 2: Ejecuta una comprobación de estado

Puedes ejecutar una comprobación de estado en el cliente de la API de WhatsApp Business mediante una llamada a la API enviada al nodo health.

El resultado se verá como en el siguiente ejemplo:

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}

Nota: En el modo de multiconexión con 2 fragmentos, habrá 2 apps principales (en este ejemplo, wacore1 y wacore2) conectadas al servidor de WhatsApp, y el objeto maestro principal (en este ejemplo, master2) también estará conectado al servidor de WhatsApp.

Paso 3: Inicia una tercera app principal para mantener la alta disponibilidad

Hasta ahora, en este ejemplo, hay 2 contenedores de app principal y las cargas de mensajes se dividen entre ellos. Sin embargo, si uno de los contenedores de la app principal falla, fallará también la mitad de los envíos de tus mensajes. Para mantener la alta disponibilidad en esta nueva configuración de multiconexión, puedes iniciar una tercera app principal para tolerar que falle de app principal, similar a lo que se representa en el diagrama que se muestra en la sección Introducción a la opción de multiconexión.

Para iniciar el contenedor de la tercera app principal, ejecuta el siguiente comando:

docker-compose -f multiconnect-compose.yml up -d wacore3

El resultado se verá como en el siguiente ejemplo:

biz_db_1 is up-to-date
biz_waweb_1 is up-to-date
biz_master1_1 is up-to-date
Creating biz_wacore3_1 ... done

Paso 4: Ejecuta otra comprobación de estado

Realiza otra comprobación de estado para verificar que todos los nodos se estén ejecutando correctamente, mediante una llamada a la API al nodo health.

El resultado se verá como en el siguiente ejemplo:

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore3:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

El nuevo contenedor de app principal (en este ejemplo, wacore3) ahora actúa como contenedor en reposo, pero no está conectado al servidor de WhatsApp. Si wacore1 o wacore2 dejan de funcionar, wacore3 se conectará al servidor de WhatsApp para mantener un total de 2 fragmentos.

Actualización del cliente de la API de WhatsApp Business

Habrá tiempo de inactividad durante el proceso de actualización.

Se recomienda crear una copia de seguridad de la configuración actual de la app antes de actualizarla; eso te permitirá asegurarte de que puedas volver a ponerte en marcha rápidamente. Sigue los pasos de la documentación sobre copias de seguridad y restauración.

Se recomienda siempre realizar las actualizaciones durante las horas de menos actividad.

Paso 1: Cambia la variable de entorno WA_API_VERSION por la nueva versión

La variable de entorno WA_API_VERSION debe actualizarse a la nueva versión mediante lo siguiente:

export WA_API_VERSION=new-whatsapp-version

Paso 2: Reinicia los contenedores Docker

Reinicia los contenedores Docker ejecutando lo siguiente:

docker-compose -f multiconnect-compose.yml up -d

Para usuarios de la base de datos MySQL que actualizan a la versión v2.23.x o a una superior

Ahora puedes utilizar un servicio de actualización de versión de base de datos que te permite actualizar la base de datos con la app en ejecución y así evitar tiempo de inactividad.

Paso 1: Descarga los archivos de configuración

El archivo dbupgrade-compose.yml tiene campos que indican la versión del contenedor.

Ejemplo:

services:
  dbupgrade:
    image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

Paso 2: Inicia el contenedor

Para actualizar la versión de una instalación, inicia el contenedor dbupgrade-service con la variable de entorno WA_API_VERSION configurada con el valor de la versión más reciente:

WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

Nota: Si utilizas una orquestación que reinicia el contenedor al salir, independientemente del código de salida, inicia el servicio con la variable de entorno EXIT_ON_SUCCESS configurada en FALSE para evitar salir del contenedor cuando el código de salida sea 0.

Paso 3: Espera a que la actualización finalice

Si la base de datos se actualiza con éxito, el código del contenedor al salir será 0. Puedes utilizar el siguiente comando Docker para hacer un seguimiento del estado:

docker wait your-database-upgrade-container-name

El resultado devuelto será el código de salida del contenedor dbupgrade-service.

Paso 4: Reinicia los contenedores de la app principal y de la app web

Reinicia el contenedor Docker de la app web y el de la app principal con la variable de entorno WA_API_VERSION configurada con la versión más reciente:

WA_API_VERSION=new-whatsapp-version docker-compose -f multiconnect-compose.yml up -d

Cómo desinstalar el cliente de la API de WhatsApp Business

Se recomienda crear una copia de seguridad de la configuración de la app actual antes de desinstalarla. Sigue los pasos de la documentación sobre copias de seguridad y restauración.

Si debes eliminar todos los contenedores para restablecer el entorno de desarrollo, ejecuta el siguiente comando desde el directorio que contiene el archivo multiconnect-compose.yml:

docker-compose -f multiconnect-compose.yml down

Si, además de los contenedores, quieres eliminar todos los volúmenes definidos en el archivo multiconnect-compose.yml, ejecuta down con el parámetro -v:

docker-compose -f multiconnect-compose.yml down -v

Solución de problemas

Para recopilar registros de todos los contenedores, ejecuta el siguiente comando:

docker-compose -f multiconnect-compose.yml logs > debug_output.txt

Para obtener los registros de un servicio específico, agrega el nombre del servicio (por ejemplo, wawebmaster1 o wacore1) al comando docker-compose logs:

docker-compose -f multiconnect-compose.yml logs waweb > debug_output.txt

Puedes encontrar los registros en el archivo debug_output.txt en el directorio actual.

Este software utiliza código de FFmpeg con licencia de LGPLv2.1, y puedes descargar el código fuente aquí.