API Local da Plataforma do WhatsApp Business

Configuração do desenvolvedor: alta disponibilidade e multiconexão

Este documento mostra como configurar um cluster com alta disponibilidade em uma máquina de desenvolvedor. Além disso, ele orienta sobre como habilitar o recurso de multiconexão e indica as mudanças necessárias para um cluster de multiconexão com alta disponibilidade. Caso você queira fazer uma configuração de produção, siga as instruções listadas em Configurações de produção.

Antes de você iniciar a configuração, verifique a nossa lista de requisitos.

Para configurar um cluster com alta disponibilidade, siga estas etapas:

  1. Criar um diretório biz para os scripts de configuração
  2. Obter os arquivos de configuração do cliente da WhatsApp Business API
  3. Definir a variável de ambiente WA_API_VERSION
  4. Iniciar o cliente da WhatsApp Business API com alta disponibilidade
  5. Verificar se os contêineres estão funcionando
  6. Fazer uma verificação de integridade
  7. Registrar o cliente da WhatsApp Business API
  8. Fazer uma nova verificação de integridade

Para configurar um cluster de multiconexão, siga estas etapas:

  1. Configurar dois fragmentos
  2. Fazer uma verificação de integridade
  3. Iniciar um terceiro Coreapp para manter a alta disponibilidade
  4. Fazer uma nova verificação de integridade

Depois de concluir a configuração da sua instância, você pode atualizá-la. Para desinstalar o cliente, siga estas etapas.

Antes de começar

Se você já seguiu as instruções Configuração do desenvolvedor: instância única para configurar o cliente da WhatsApp Business API em uma máquina de desenvolvedor, siga o guia sobre migração antes de implementar as etapas a seguir.

O conteúdo deste guia parte do pressuposto de que existe uma instalação recente.

Antes de começar, você precisará concluir o seguinte:

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.

Outros pré-requisitos

Configure uma conta de teste local em um ambiente de desenvolvimento. Ela deve ser usada para agilizar o desenvolvimento e testar lançamentos. Recomendamos que você também leia o guia sobre disponibilidade e dimensionamento para saber mais sobre alta disponibilidade e multiconexão.

Configurar um cluster com alta disponibilidade

Etapa 1: criar um diretório biz para os scripts de configuração

Na localização que você preferir, execute o seguinte código do cliente da WhatsApp Business API:

mkdir ~/biz; cd ~/biz;

Etapa 2: obter os arquivos de configuração do cliente da WhatsApp Business API

Os arquivos para configuração do cliente da WhatsApp Business API estão no repositório do GitHub WhatsApp-Business-API-Setup-Scripts. É possível configurar o cliente da WhatsApp Business API com uma instância de banco de dados MySQL ou Postgres.

Etapa 3: definir a variável de ambiente WA_API_VERSION

A variável de ambiente WA_API_VERSION precisa ser definida como a versão mais recente por meio de:

export WA_API_VERSION=current-whatsapp-version

Etapa 4: iniciar o cliente da WhatsApp Business API com alta disponibilidade

Para iniciar um cluster de alta disponibilidade com um contêiner de banco de dados, um do Webapp, dois do Master e dois do Coreapp em segundo plano, de forma semelhante ao diagrama mostrado na Visão geral sobre alta disponibilidade, execute o seguinte comando:

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

A saída terá aparência semelhante a esta:

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

Etapa 5: verificar se os contêineres estão funcionando

É possível verificar se todos os contêineres têm um estado UP executando:

docker-compose -f multiconnect-compose.yml ps

A saída terá aparência semelhante a esta:

      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

Por padrão, o contêiner do Webapp será executado na porta 9090, e o contêiner de banco de dados, na porta 33060.

Etapa 6: fazer uma verificação de integridade

Caso você não queira usar a linha de comando, baixe e configure a nossa coleção do Postman para interagir com a WhatsApp Business API.

É possível fazer a verificação de integridade na WhatsApp Business API do cliente por meio de uma chamada de API para o nó health.

A saída terá aparência semelhante a esta:

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

A resposta mostra um gateway_status de unregistered como o gateway_status do contêiner principal do Master porque o cliente da WhatsApp Business API ainda não foi registrado.

Etapa 7: registrar o cliente da WhatsApp Business API

Você pode registrar o cliente da WhatsApp Business API por meio de uma chamada de API para o nó account.

Etapa 8: fazer uma nova verificação de integridade

Realize uma nova verificação de integridade no cliente da WhatsApp Business API. Faça uma chamada de API para o nó health depois de concluir o registro e verifique se um dos contêineres do Coreapp tem um gateway_status de connected.

A saída terá aparência semelhante a esta:

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

Observação: no modo de alta disponibilidade, somente um Coreapp (wacore1 nesse exemplo) será conectado ao servidor do WhatsApp. Todos os outros nós, incluindo o Master principal, terão um gateway_status de disconnected. Se o wacore1 parar de funcionar, o wacore2 o substituirá e se conectará ao servidor do WhatsApp para manter a alta disponibilidade.

Agora o cliente da WhatsApp Business API foi configurado no modo de alta disponibilidade. Nesse modo, somente um Coreapp conseguirá se conectar ao servidor do WhatsApp por vez para enviar mensagens. Caso você queira ter vários Coreapps enviando mensagens por vez para aumentar a taxa de transferência, siga as etapas descritas na seção Configurar um cluster de multiconexão com alta disponibilidade abaixo.

Configurar um cluster de multiconexão com alta disponibilidade

Etapa 1: configurar dois fragmentos

Use o ponto de extremidade de fragmentos para configurar dois fragmentos. Você verá uma resposta HTTP com status 201 Created.

Etapa 2: fazer uma verificação de integridade

É possível fazer a verificação de integridade na WhatsApp Business API do cliente por meio de uma chamada de API para o nó health.

A saída terá aparência semelhante a esta:

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

Observação: no modo de multiconexão com dois fragmentos, serão conectados dois Coreapps (wacore1 e wacore2 nesse exemplo) ao servidor do WhatsApp. Além disso, o Master principal (master2 nesse exemplo) será conectado ao mesmo servidor.

Etapa 3: iniciar um terceiro Coreapp para manter a alta disponibilidade

Até o momento, neste exemplo, você tem dois contêineres do Coreapp, e o carregamento de mensagens se divide entre eles. Entretanto, caso um dos contêineres pare de funcionar, ocorrerá falha na metade dos envios de mensagens. Para você manter a alta disponibilidade na configuração de multiconexão, inicie um terceiro Coreapp para dar suporte à falha de um dos existentes, de forma semelhante ao diagrama exibido na Visão geral sobre multiconexão.

Para iniciar o terceiro contêiner do Coreapp, execute o seguinte comando:

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

A saída terá aparência semelhante a esta:

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

Etapa 4: fazer uma nova verificação de integridade

Realize outra verificação de integridade por meio de uma chamada de API para o nó health, com objetivo de conferir se todos os nós estão funcionando corretamente.

A saída terá aparência semelhante a esta:

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

Agora o novo contêiner do Coreapp (wacore3 nesse exemplo) funcionará como um contêiner reserva. Porém, neste momento, ele não está conectado ao servidor do WhatsApp. Se wacore1 ou wacore2 parar de funcionar, wacore3 será conectado ao servidor do WhatsApp para manter a contagem geral de dois fragmentos.

Atualizar o cliente da WhatsApp Business API

Haverá um período de inatividade durante o processo de atualização.

Recomendamos que você faça backup das configurações do aplicativo antes de atualizar para garantir que você possa voltar a usá-lo rapidamente. Siga as instruções da documentação sobre backup e restauração.

É recomendado que as atualizações sejam feitas em horários com menor movimentação.

Etapa 1: alterar a variável de ambiente WA_API_VERSION para a nova versão

A variável de ambiente WA_API_VERSION precisa ser atualizada para a versão mais recente por meio de:

export WA_API_VERSION=new-whatsapp-version

Etapa 2: reiniciar os contêineres do Docker

Reinicie os contêineres do Docker executando:

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

Para usuários do banco de dados MySQL que estão atualizando para v2.23.x e versões posteriores

Agora você pode usar um serviço de atualização do banco de dados para atualizar o banco de dados enquanto o app continua em execução, evitando o tempo de inatividade.

Etapa 1: baixar o arquivo de configuração

O arquivo dbupgrade-compose.yml tem campos que indicam a versão do contêiner.

Exemplo:

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

Etapa 2: inicializar o contêiner

Para atualizar uma instalação, inicialize o contêiner dbupgrade-service com a variável de ambiente WA_API_VERSION definida como a versão mais recente:

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

Observação: se você estiver usando uma orquestração que reinicia o contêiner na saída independentemente do código de saída, inicialize o serviço com a variável de ambiente EXIT_ON_SUCCESS definida como FALSE. Isso evitará a saída do contêiner quando o código de saída for 0.

Etapa 3: permitir que a atualização seja concluída

Se a atualização do banco de dados for bem-sucedida, o contêiner sairá com o código 0. É possível usar o seguinte comando do Docker para acompanhar o status:

docker wait your-database-upgrade-container-name

Com isso, o código de saída do contêiner dbupgrade-service será criado.

Etapa 4: reiniciar os contêineres do Coreapp e do Webapp

Reinicie os contêineres do Docker do Coreapp e do Webapp com a variável de ambiente WA_API_VERSION definida como a versão mais recente:

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

Desinstalar o cliente da WhatsApp Business API

Recomendamos que você faça backup das configurações atuais do seu aplicativo antes da desinstalação. Siga as instruções da documentação sobre backup e restauração.

Se precisar redefinir o ambiente de desenvolvimento removendo todos os contêineres, execute o seguinte comando no diretório que contém o arquivo multiconnect-compose.yml:

docker-compose -f multiconnect-compose.yml down

Para eliminar os volumes definidos no arquivo multiconnect-compose.yml, bem como os contêineres, execute down com o parâmetro -v:

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

Solução de problemas

Para coletar registros de todos os contêineres, execute o seguinte comando:

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

Para coletar registros de um serviço específico, anexe o nome de serviço (por exemplo, waweb, master1 ou wacore1) ao comando docker-compose logs:

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

Os registros podem ser encontrados no arquivo debug_output.txt no diretório do momento.

Esse software usa código de FFmpeg licenciado como LGPLv2.1. Baixe a fonte aqui.