API Local da Plataforma do WhatsApp Business

Configuração do desenvolvedor: multiconexão no Minikube

Este documento mostra como configurar uma instalação de máquina do desenvolvedor do cliente da WhatsApp Business API com a multiconexão no Minikube. 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. Criar um banco de dados no MySQL
  4. Criar uma chave secreta do whatsapp-config
  5. Criar um volume de mídia local
  6. Definir a variável de ambiente $VERSION
  7. Implantar os contêineres
  8. Encontrar a porta do contêiner do webapp
  9. Obter um token de autenticação
  10. Fazer uma verificação de integridade
  11. Registrar o cliente da WhatsApp Business API
  12. Fazer uma nova verificação de integridade

Para configurar um cluster de multiconexão com alta disponibilidade, 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

Você precisará do seguinte:

  • Um cluster Kubernetes configurado localmente usando o minikube
  • A ferramenta de linha de comando kubectl
  • Uma conta de teste configurada localmente 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

Clone todos os arquivos de configuração do diretório installation/kubernetes do repositório do GitHub WhatsApp-Business-API-Setup-Scripts para o diretório ~/biz que você criou na Etapa 1.

Etapa 3: criar um banco de dados no MySQL

Crie um banco de dados no MySQL com um volume persistente usando:

kubectl apply -f mysql.yaml

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

persistentvolume/mysql-volume created
persistentvolumeclaim/mysql-volume-claim created
service/mysql-service created
deployment.extensions/mysql-deployment created

É possível verificar se o MySQL está em execução com:

kubectl get pods

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

NAME                               READY   STATUS    RESTARTS   AGE
mysql-deployment-5d4f898-xtkpj     1/1     Running   0          53m

Etapa 4: criar uma chave secreta do whatsapp-config

Crie uma chave secreta do whatsapp-config a partir do arquivo db.env com o seguinte comando:

kubectl create secret generic whatsapp-config --from-env-file=db.env

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

secret/whatsapp-config created

É possível verificar se a chave secreta foi criada com:

kubectl get secrets

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

NAME                TYPE        DATA        AGE
whatsapp-config     Opaque      5           52s

É possível verificar os detalhes da chave secreta com:

kubectl describe secrets/whatsapp-config

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

Name:         whatsapp-config
Namespace:    default
Labels:       <none>
Annotations:  <none>

Type:  Opaque

Data
====
wa-db-password:  8 bytes
wa-db-port:      4 bytes
wa-db-username:  4 bytes
wa-db-engine:    5 bytes
wa-db-hostname:  13 bytes

Etapa 5: criar um volume de mídia local

Para enviar ou receber mensagens de mídia, o cliente da WhatsApp Business API requer que um volume persistente seja compartilhado entre as implantações do Webapp, do Master e do Coreapp. Execute o seguinte para criar um PersistentVolume e PersistentVolumeClaim para mensagens de mídia:

kubectl apply -f volume.yaml

Esse comando configurará um volume de mídia local, montado em /usr/local/wamedia dentro do cluster Kubernetes, com um tamanho de 1 GB e solicita dele um tamanho físico de 1 GB por meio de um PersistentVolumeClaim para fins de desenvolvimento e testes.

É possível verificar o status do volume de mídia e do pedido de volume de mídia com:

kubectl get pv media-volume

kubectl get pvc media-volume-claim

Etapa 6: definir a variável de ambiente $VERSION

Substitua a variável de ambiente $VERSION pela última versão do cliente da WhatsApp Business API (por exemplo, 2.23.4) na seção containers dos arquivos webapp.yaml, master.yaml e coreapp.yaml.

webapp.yaml

containers:
- name: whatsapp-web
  image: docker.whatsapp.biz/web:v2.23.4

master.yaml

containers:
- name: whatsapp-master
  image: docker.whatsapp.biz/coreapp:v2.23.4

coreapp.yaml

containers:
- name: whatsapp-coreapp
  image: docker.whatsapp.biz/coreapp:v2.23.4

Etapa 7: implantar os contêineres

Execute os seguintes comandos para implantar os contêineres Webapp, Master e Coreapp:

Webapp

kubectl apply -f webapp.yaml

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

horizontalpodautoscaler.autoscaling/whatsapp-web-autoscaler created
service/whatsapp-web-service created
deployment.apps/whatsapp-web-deployment created

Master

kubectl apply -f master.yaml

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

horizontalpodautoscaler.autoscaling/whatsapp-master-autoscaler created
service/whatsapp-master-service created
deployment.apps/whatsapp-master-deployment created

Coreapp

kubectl apply -f coreapp.yaml

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

horizontalpodautoscaler.autoscaling/whatsapp-coreapp-autoscaler created
service/whatsapp-coreapp-service created
deployment.apps/whatsapp-coreapp-deployment created

É possível verificar se o pod do Master/Coreapp/Webapp está em execução com:

kubectl get pods

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

NAME                                           READY   STATUS    RESTARTS   AGE
mysql-deployment-5d4f898-xtkpj                 1/1     Running   0          53m
whatsapp-coreapp-deployment-78c4d987b8-4cpz4   1/1     Running   0          2s
whatsapp-coreapp-deployment-78c4d987b8-l5qjj   1/1     Running   0          2s
whatsapp-master-deployment-8598d7bf6b-56fvn    1/1     Running   7          15m
whatsapp-master-deployment-8598d7bf6b-9r6lc    1/1     Running   7          16m
whatsapp-web-deployment-cd4c5785c-9vn6l        1/1     Running   0          16m
whatsapp-web-deployment-cd4c5785c-mn7kf        1/1     Running   0          16m

As configurações padrão criarão 2 pods Master, 2 pods Coreapp e 2 pods Webapp. Cada pod solicita 128 MB de memória e CPUs de 0,15. Faça alterações em spec.template.spec.containers.resources nos respectivos arquivos YAML se quiser definir configurações de recurso diferentes.

Etapa 8: encontrar a porta do contêiner do Webapp

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.

Ao executar um cluster Kubernetes usando o Minikube, é preciso verificar o IP do cluster executando:

minikube ip

Encontre a porta em que o contêiner do Webapp está em execução usando:

kubectl get services/whatsapp-web-service

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

NAME                   TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)         AGE
whatsapp-web-service   NodePort   10.101.114.46   <none>        443:32477/TCP   25m

Neste exemplo, a porta 443 dentro do contêiner do Webapp foi mapeada para a porta 32477 no cluster Kubernetes.

Você precisa usar https://your-minikube-cluster-ip:your-webapp-service-targetport (por exemplo, https://10.101.114.46:32477) como a URL raiz da API ao usar a coleção do Postman.

Etapa 9: obter um token de autenticação

Faça login na WhatsApp Business API para obter um token de autenticação Bearer e fazer chamadas de API.

Etapa 10: fazer uma verificação de integridade

É possível fazer a verificação de integridade no cliente da WhatsApp Business API por meio de uma chamada de API para o nó health a fim de verificar se todos os pods estão funcionando corretamente.

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

'health': {
    '172.17.0.11:whatsapp-coreapp-deployment-78c4d987b8-l5qjj': {
        'errors': [
            {
                'code': 1011,
                'title': 'Service not ready',
                'details': 'Wacore is not instantiated. Please check wacore log for details.'
            }
        ]
    },
    '172.17.0.6:whatsapp-master-deployment-8598d7bf6b-56fvn': {
        'errors': [
            {
                'code': 1011,
                'title': 'Service not ready',
                'details': 'Wacore is not instantiated. Please check wacore log for details.'
            }
        ]
    },
    '172.17.0.7:whatsapp-coreapp-deployment-78c4d987b8-4cpz4': {
        'errors': [
            {
                'code': 1011,
                'title': 'Service not ready',
                'details': 'Wacore is not instantiated. Please check wacore log for details.'
            }
        ]
    },
    '172.17.0.8:whatsapp-master-deployment-8598d7bf6b-9r6lc': {
        'gateway_status': 'unregistered',
        'role': 'primary_master'
    }
},
'meta': {
    'version': 'v2.23.4',
    'api_status': 'stable'
}

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 11: 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 12: 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': {
    '172.17.0.11:whatsapp-coreapp-deployment-78c4d987b8-l5qjj': {
        'gateway_status': 'disconnected',
        'role': 'coreapp'
    },
    '172.17.0.6:whatsapp-master-deployment-8598d7bf6b-56fvn': {
        'gateway_status': 'disconnected',
        'role': 'secondary_master'
    },
    '172.17.0.7:whatsapp-coreapp-deployment-78c4d987b8-4cpz4': {
        'gateway_status': 'connected',
        'role': 'coreapp'
    },
    '172.17.0.8:whatsapp-master-deployment-8598d7bf6b-9r6lc': {
        'gateway_status': 'disconnected',
        'role': 'primary_master'
    }
},
'meta': {
    'version': 'v2.23.4',
    'api_status': 'stable'
}

Observação: no modo de alta disponibilidade, somente um Coreapp (whatsapp-coreapp-deployment-78c4d987b8-4cpz4 nesse exemplo) será conectado ao servidor do WhatsApp. Todos os outros pods, incluindo o Master principal, terão um gateway_status de disconnected. Se o whatsapp-coreapp-deployment-78c4d987b8-4cpz4 parar de funcionar, whatsapp-coreapp-deployment-78c4d987b8-l5qjj o substituirá e se conectará ao servidor do WhatsApp para manter a alta disponibilidade.

Você agora configurou o cliente da WhatsApp Business API 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 uma seção de 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 no cliente da WhatsApp Business API por meio de uma chamada de API para o nó health a fim de verificar se todos os pods estão funcionando corretamente.

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

'health': {
    '172.17.0.11:whatsapp-coreapp-deployment-78c4d987b8-l5qjj': {
        'gateway_status': 'connected',
        'role': 'coreapp'
    },
    '172.17.0.6:whatsapp-master-deployment-8598d7bf6b-56fvn': {
        'gateway_status': 'disconnected',
        'role': 'secondary_master'
    },
    '172.17.0.7:whatsapp-coreapp-deployment-78c4d987b8-4cpz4': {
        'gateway_status': 'connected',
        'role': 'coreapp'
    },
    '172.17.0.8:whatsapp-master-deployment-8598d7bf6b-9r6lc': {
        'gateway_status': 'connected',
        'role': 'primary_master'
    }
},
'meta': {
    'version': 'v2.23.4',
    'api_status': 'stable'
}

Observação: no modo de multiconexão com dois fragmentos, serão conectados dois Coreapps (whatsapp-coreapp-deployment-78c4d987b8-l5qjj e whatsapp-coreapp-deployment-78c4d987b8-4cpz4 nesse exemplo) ao servidor do WhatsApp. Além disso, o Master principal (whatsapp-master-deployment-8598d7bf6b-9r6lc 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, altere o número de replicas para 3 no arquivo coreapp.yaml:

spec:
  replicas: 3

Depois, reimplante o Coreapp executando:

kubectl apply -f coreapp.yaml

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

horizontalpodautoscaler.autoscaling/whatsapp-coreapp-autoscaler unchanged
service/whatsapp-coreapp-service unchanged
deployment.apps/whatsapp-coreapp-deployment configured

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

Realize outra verificação de integridade para verificar se todos os nós estão funcionando corretamente usando uma chamada de API para o nó health, com objetivo de conferir se todos os pods estão funcionando de maneira adequada.

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

'health': {
    '172.17.0.10:whatsapp-coreapp-deployment-78c4d987b8-hwqp6': {
        'gateway_status': 'disconnected',
        'role': 'coreapp'
    },
    '172.17.0.11:whatsapp-coreapp-deployment-78c4d987b8-l5qjj': {
        'gateway_status': 'connected',
        'role': 'coreapp'
    },
    '172.17.0.6:whatsapp-master-deployment-8598d7bf6b-56fvn': {
        'gateway_status': 'disconnected',
        'role': 'secondary_master'
    },
    '172.17.0.7:whatsapp-coreapp-deployment-78c4d987b8-4cpz4': {
        'gateway_status': 'connected',
        'role': 'coreapp'
    },
    '172.17.0.8:whatsapp-master-deployment-8598d7bf6b-9r6lc': {
        'gateway_status': 'connected',
        'role': 'primary_master'
    }
},
'meta': {
    'version': 'v2.23.4',
    'api_status': 'stable'
}

Agora o novo contêiner do whatsapp-coreapp-deployment-78c4d987b8-hwqp6 funcionará como um contêiner reserva. No entanto, neste momento, ele não está conectado ao servidor do WhatsApp. Se o whatsapp-coreapp-deployment-78c4d987b8-l5qjj ou o whatsapp-coreapp-deployment-78c4d987b8-4cpz4stops working,whatsapp-coreapp-deployment-78c4d987b8-hwqp6` será conectado ao servidor do WhatsApp para manter a contagem geral de dois fragmentos.

Atualização do 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 na 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 $VERSION para a nova versão

Atualize a variável de ambiente $VERSION para a versão desejada (por exemplo, 2.23.5) na seção containers dos arquivos webapp.yaml, master.yaml e coreapp.yaml.

webapp.yaml

containers:
- name: whatsapp-web
  image: docker.whatsapp.biz/web:v2.23.5

master.yaml

containers:
- name: whatsapp-master
  image: docker.whatsapp.biz/coreapp:v2.23.5

coreapp.yaml

containers:
- name: whatsapp-coreapp
  image: docker.whatsapp.biz/coreapp:v2.23.5

Etapa 2: atualizar os contêineres

Atualize os contêineres do Webapp, do Master e do Coreapp e monitore o status de lançamento.

Webapp

kubectl apply -f webapp.yaml

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

kubectl rollout status deployments/whatsapp-web-deployment

Master

kubectl apply -f master.yaml

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

kubectl rollout status deployments/whatsapp-master-deployment

Coreapp

kubectl apply -f coreapp.yaml

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

kubectl rollout status deployments/whatsapp-coreapp-deployment

Desinstalar o cliente da WhatsApp Business API

Etapa 1: excluir as implantações

Exclua as implantações usando:

kubectl delete -f webapp.yaml
kubectl delete -f master.yaml
kubectl delete -f coreapp.yaml
kubectl delete -f mysql.yaml

Etapa 2: excluir o volume

Exclua o volume usando:

kubectl delete -f volume.yaml

Etapa 3: excluir a chave secreta

Exclua a chave secreta usando:

kubectl delete secrets/whatsapp-config

Solução de problemas

Para verificar se todos os pods estão em execução, use:

kubectl get pods

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

NAME                                           READY   STATUS    RESTARTS   AGE
mysql-deployment-5d4f898-xtkpj                 1/1     Running   0          1h
whatsapp-coreapp-deployment-78c4d987b8-4cpz4   1/1     Running   2          1h
whatsapp-coreapp-deployment-78c4d987b8-hwqp6   1/1     Running   0          24m
whatsapp-coreapp-deployment-78c4d987b8-l5qjj   1/1     Running   2          1h
whatsapp-master-deployment-8598d7bf6b-56fvn    1/1     Running   9          1h
whatsapp-master-deployment-8598d7bf6b-9r6lc    1/1     Running   8          1h
whatsapp-web-deployment-cd4c5785c-f99n4        1/1     Running   0          50m
whatsapp-web-deployment-cd4c5785c-s5phx        1/1     Running   0          50m

Caso algum pod não esteja pronto (ou seja, 0/1 é exibido na coluna READY), é possível obter os registros desse pod específico executando o comando kubectl logs com o nome do pod.

Exemplo:

kubectl logs whatsapp-coreapp-deployment-78c4d987b8-4cpz4 > whatsapp-coreapp-deployment-78c4d987b8-4cpz4.txt

Os registros poderão ser encontrados no arquivo whatsapp-coreapp-deployment-78c4d987b8-4cpz4.txt no diretório atual.

Para coletar os registros de um determinado serviço implantado (como o Webapp), execute o comando kubectl logs com o nome do serviço.

Exemplo:

kubectl logs deployments/whatsapp-web-deployment > whatsapp-web-deployment.txt

Os registros poderão ser encontrados no arquivo whatsapp-web-deployment.txt do diretório atual.

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