Integrar HookMyApp

O que Integrar HookMyApp faz?

HookMyApp é um intermediário da API Business do WhatsApp. Este skill ensina agentes de IA a usarem o @gethookmyapp/cli para integrar o aplicativo do usuário com um WABA sandbox compartilhado (para desenvolvimento e testes) ou um WABA de produção provisionado (via inscrição incorporada do Meta). A CLI gerencia a emissão de credenciais, o ciclo de vida do túnel e a configuração de webhooks — seu código nunca precisa chamar a API HookMyApp diretamente.

Orientação para o Agente

Princípios Chave

• A CLI é a fonte da verdade. Nunca incorpore credenciais diretamente no código gerado. Execute hookmyapp sandbox env --write .env ou hookmyapp env <waba-id> e deixe o aplicativo do usuário ler as variáveis de ambiente.
• Os flags de workspace e ambiente definem o escopo de cada chamada. Quando o usuário tiver vários workspaces ou operar em staging e produção, passe --workspace <id> e --env staging|production explicitamente, em vez de confiar nos padrões.
• Etapas no navegador não podem ser automatizadas. login e channels connect abrem abas no navegador que o humano deve concluir. Não finja automatizá-las — devolva o terminal com uma instrução clara.
• Sandbox não é produção. Sandbox é um WABA compartilhado com 5 chaves de ambiente, sem templates e com destinatário fixo no telefone da sessão. Produção é seu próprio WABA com 3 chaves de ambiente e suporte total a templates. Os dois não são intercambiáveis — escolha um baseado no objetivo do usuário antes de gerar código.

Quando Solicitar Ação Humana

Use um blockquote > **AÇÃO HUMANA NECESSÁRIA:** <ação> sempre que o próximo passo não for automatizável:

• hookmyapp login — abre uma aba do navegador para login.
• hookmyapp channels connect — abre o popup de inscrição incorporada do Meta; o usuário escolhe negócio, WABA e número de telefone.
• Selecionar --env production em qualquer operação destrutiva (webhook set, logout).
• Rotacionar um ACCESS_TOKEN vazado — deve ocorrer no Painel do Aplicativo Meta, não via CLI.

Regras de Segurança

• Nunca cole a saída de env <waba-id> ou token <waba-id> em chats, tickets ou logs. Redirecione para um gerenciador de segredos ou arquivo .env que o usuário controle.
• Nunca execute workspace use sem confirmar o ID alvo. Executar comandos no workspace errado pode modificar o WABA errado.
• Nunca execute webhook set --env production sem confirmação humana explícita da URL. Apontar webhooks de produção para uma URL de desenvolvimento descarta silenciosamente mensagens de clientes recebidas.
• Nunca gere exemplos de mensagens template no sandbox. Templates são rejeitados pelo sandbox-proxy; gerar tal código só perde tempo do usuário.
• Nunca execute hookmyapp channels disable <waba-id> sem confirmação humana explícita. Desativar o encaminhamento = descarte silencioso de mensagens recebidas; nenhum erro é exibido ao cliente. Use channels show <waba-id> ou health <waba-id> para verificar o estado antes e depois.
• Sinalize hookmyapp config set env <name> como uma alteração persistente. Ele escreve o arquivo de configuração da CLI e afeta toda invocação subsequente em qualquer shell até hookmyapp config unset env. Prefira o flag por invocação --env <name> quando a intenção for única.

Pré-requisitos

• Node.js 18 ou superior (para a CLI e o servidor webhook típico).
• Uma conta HookMyApp. Cadastre-se em https://app.hookmyapp.com/signup.
• Para produção: uma conta do Business Manager do Facebook (para a inscrição incorporada channels connect).

Dois Caminhos: Sandbox vs Produção

Aspecto	Sandbox (dev / testes)	Produção
WABA	Compartilhado, gerenciado pela HookMyApp	Seu, provisionado via inscrição incorporada do Meta
Etapa de configuração	sandbox start --phone +<E164>	channels connect (popup do navegador)
Chaves de ambiente	5: VERIFY_TOKEN (emitido pela CLI por sessão), PORT, WHATSAPP_API_URL, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID	5 (mesmo formato que sandbox): VERIFY_TOKEN (escolhido pelo usuário; definido via webhook set --verify-token), PORT, WHATSAPP_API_URL (→ graph.facebook.com/v22.0), WHATSAPP_ACCESS_TOKEN (de env <waba-id> ACCESS_TOKEN), WHATSAPP_PHONE_NUMBER_ID (de env <waba-id> PHONE_NUMBER_ID). WABA_ID emitido por env não é usado pelo kit.
Túnel de entrada	sandbox listen (Cloudflare)	Sua própria URL pública HTTPS + webhook set --verify-token
Destinatário	Fixo no telefone da sessão (lado do servidor)	Qualquer usuário do WhatsApp que te enviou mensagem primeiro
Templates	Bloqueados (apenas texto)	Suportados
Painel Meta	Não necessário	Necessário para revisão do aplicativo e aprovação de templates

Escolha sandbox quando o usuário estiver desenvolvendo ou depurando em localhost e quiser zero burocracia com o Meta para iteração diária. Escolha produção quando o usuário estiver implantando para WABAs reais de clientes (inscrição incorporada do Meta necessária uma vez, por WABA).

Início Rápido: Sandbox

Sete passos do zero a um receptor webhook em execução que ecoa mensagens recebidas do WhatsApp:

1. Instale a CLI

npm install -g @gethookmyapp/cli

2. Faça login

hookmyapp login

AÇÃO HUMANA NECESSÁRIA: Uma aba do navegador abre para login no HookMyApp. Complete o login lá; a CLI aguarda o callback e armazena as credenciais localmente.

Alternativa — sem navegador via código bootstrap (para colagem por IA / CI):

hookmyapp login --code <bootstrap>

Se o humano já tiver gerado um código bootstrap do painel HookMyApp (Configurações → CLI → "Gerar código bootstrap"), ele pode colá-lo neste flag e pular completamente a aba do navegador. O código é de uso único e expira rapidamente — exiba um > **AÇÃO HUMANA NECESSÁRIA:** apenas para a colagem. Sai com código diferente de zero se o código estiver expirado ou consumido. Veja references/auth.md para a sintaxe completa dos flags.

3. Clone o kit inicial

git clone https://github.com/hookmyapp/webhook-starter-kit.git
cd webhook-starter-kit
npm install

O kit inicial é um aplicativo Express mínimo com um receptor de assinatura verificada em /webhook e um helper sendMessage. Ele lê as cinco chaves de ambiente que sandbox env --write produz.

4. Obtenha os valores do ambiente

hookmyapp sandbox env --write .env

Escreve VERIFY_TOKEN, PORT, WHATSAPP_API_URL, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID em .env.

5. Inicie o servidor (terminal 1)

npm start

O Express escuta em localhost:3000/webhook por padrão.

6. Inicie o túnel sandbox (terminal 2)

hookmyapp sandbox listen --phone +<seu-telefone>

Abre um túnel Cloudflare de um hostname público gerenciado pela HookMyApp para localhost:3000/webhook. Os padrões do túnel da CLI (--port 3000, --path /webhook) correspondem ao kit inicial, então nenhum flag é necessário para o caso comum.

7. (Opcional) Envie uma resposta de teste

hookmyapp sandbox send --phone +<seu-telefone> --message "olá"

Você receberá a mensagem no telefone da sessão. (O sandbox fixa o destinatário no telefone da sessão — não há flag de destino; o sandbox-proxy rejeita envios para qualquer outro número.)

Agora envie uma mensagem do WhatsApp da sua conta pessoal para o número sandbox — você verá o payload recebido registrado no terminal 1 e receberá a resposta automática do kit inicial no WhatsApp.

Configuração Completa: Produção

Sete passos para integrar um WABA real para uso em produção:

1. Faça login

hookmyapp login

2. Selecione um workspace

hookmyapp workspace list
hookmyapp workspace use <workspace-id>

# Ou crie um novo:
hookmyapp workspace new "Acme Produção"

3. Conecte um WABA

hookmyapp channels connect

AÇÃO HUMANA NECESSÁRIA: O popup de inscrição incorporada do Meta abre. Faça login no Facebook Business, escolha ou crie um WABA, escolha um número de telefone e conceda acesso ao aplicativo HookMyApp. Se o popup for bloqueado, a CLI imprime a URL para abrir manualmente.

4. Encontre o ID do WABA

hookmyapp channels list
# waba_id: 1276334778010256
# business_name: Acme Inc
# phone_numbers: [+15551234567]

5. Obtenha as chaves de ambiente de produção

hookmyapp env 1276334778010256 > .env.whatsapp

hookmyapp env <waba-id> emite três chaves. Mapeie-as para o .env de cinco chaves do kit:

Saída de hookmyapp env <waba-id>	Chave do kit .env	Notas
WABA_ID	(não usado pelo kit)	Mantenha para referência; o kit não lê.
ACCESS_TOKEN	WHATSAPP_ACCESS_TOKEN	Token de acesso Meta de longa duração.
PHONE_NUMBER_ID	WHATSAPP_PHONE_NUMBER_ID	ID do número de telefone Meta.
—	WHATSAPP_API_URL	Defina como https://graph.facebook.com/v22.0 em produção.
—	VERIFY_TOKEN	Escolhido pelo usuário; definido via hookmyapp webhook set <waba-id> --verify-token <token> (veja passo 6), NÃO emitido por hookmyapp env.
—	PORT	Permanece 3000 ou o que o kit estava usando no sandbox.

O kit lê 5 chaves de ambiente tanto no sandbox quanto na produção — apenas os VALORES diferem. Veja references/env.md para o esquema completo e orientação sobre gerenciamento de segredos.

6. Configure a URL do webhook

hookmyapp webhook set 1276334778010256 \
  --url https://api.acme.com/whatsapp/webhook \
  --verify-token <seu-token-escolhido>

Escolha um VERIFY_TOKEN forte e aleatório (32+ caracteres) e passe-o via --verify-token. Esta é a chave HMAC que o encaminhador usará para assinar cada webhook recebido (X-HookMyApp-Signature-256).

Na configuração inicial de produção, --verify-token é obrigatório — o encaminhador não tem token anterior para preservar. Em chamadas subsequentes de webhook set, você pode omitir --verify-token para rotação apenas de URL (o token definido anteriormente permanece em vigor).

AÇÃO HUMANA NECESSÁRIA: Antes de executar isso, confirme com o humano que a URL é o endpoint de produção pretendido. Um erro de digitação aqui descarta silenciosamente mensagens de clientes recebidas.

A URL deve responder 200 OK com VERIFY_TOKEN como corpo de texto simples no GET de verificação do Meta (HookMyApp realiza esta verificação em seu nome quando você executa webhook set).

7. Verifique a saúde

hookmyapp health 1276334778010256

Verifique se todos os números de telefone estão VERIFIED, o webhook está verified: true e a classificação de qualidade é GREEN.

A produção suporta mensagens template — veja references/sending-messages.md para a estrutura de payload type: "template" e o fluxo de aprovação.

Referência de Comandos

Grupo	Propósito	Referência completa
auth	Fazer login e logout.	references/auth.md
billing	Mostrar status da assinatura, abrir portal Stripe, atualizar plano.	references/billing.md
channels	Conectar, listar, mostrar, ativar/desativar e desconectar WABAs.	references/channels.md
config	Definir/obter/desdefinir configuração persistente da CLI (ex.: --env padrão).	references/config.md
env	Imprimir as 3 chaves de ambiente de produção para um WABA.	references/env.md
health	Verificar saúde do WABA (números de telefone, webhook, classificação de qualidade).	references/health.md
sandbox	Iniciar sessão, escrever env de 5 chaves, abrir túnel, enviar mensagens de teste.	references/sandbox.md
token	Imprimir apenas o ACCESS_TOKEN de longa duração.	references/token.md
webhook	Definir e mostrar a URL do webhook de produção em um WABA.	references/webhook.md
workspace	Listar, selecionar, renomear e gerenciar membros do workspace (escopo de locação).	references/workspace.md

Opções Globais

Todo comando aceita estes flags:

• --json — emite JSON em vez de tabelas formatadas (encaminhe com jq).
• --human — força saída legível por humanos (padrão quando stdout é um TTY).
• --workspace <slug> — substitui o workspace ativo para esta invocação. Aceita nome, slug OU id do workspace (ws_XXXXXXXX).
• --env <name> — substitui o ambiente padrão para esta invocação. Um de: local, staging, production. Padrão é o que hookmyapp config get env retornar, ou production se não definido.
• --debug — imprime corpos completos de requisição/resposta HTTP e stack traces para solução de problemas.
• --help — imprime uso e flags disponíveis para o comando.

Enviando Mensagens

Uma vez que o ambiente está populado, enviar é um único POST HTTP para a Graph API v22.0 do Meta (ou o proxy sandbox, quando WHATSAPP_API_URL é substituído). Token Bearer no cabeçalho Authorization, corpo JSON com messaging_product: "whatsapp", número de destino (E.164) e type: "text" ou type: "template".

O código do seu aplicativo não muda entre sandbox e produção — apenas os três valores WHATSAPP_* mudam. Exemplos de código completos (JS com fetch, Python com httpx, payloads de template) estão em references/sending-messages.md.

Formato do Payload do Webhook

HookMyApp encaminha o corpo do webhook do Meta literalmente. O envelope tem entry[].changes[].value.messages[] para mensagens recebidas:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1276334778010256",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "phone_number_id": "1080996501762047" },
            "messages": [
              {
                "from": "15551234567",
                "id": "wamid.abc123...",
                "timestamp": "1716300000",
                "type": "text",
                "text": { "body": "olá" }
              }
            ]
          }
        }
      ]
    }
  ]
}

Verificação de Assinatura

O encaminhador do HookMyApp assina cada webhook de saída — tanto no sandbox quanto na produção — com uma assinatura HMAC-SHA256 enviada a…