ama4devs
EN PT

Quick start

Do docker run a um webhook assinado e à resposta do usuário. Cada chamada abaixo roda como está escrita contra um container novo.

  1. Suba

    Diga onde a sua aplicação recebe os webhooks e o segredo para assiná-los.

    docker run --rm -p 3010:3010 \
  -e WEBHOOK_URL=http://host.docker.internal:4000/webhooks/whatsapp \
  -e WEBHOOK_SECRET=my-app-secret \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/instituto-ama/whatsapp-mock:latest

    Sobe com uma empresa, a WhatsApp Business Account 100000000000001 e o número 1234567890, registrado e com ligações ativadas. O painel fica em http://localhost:3010.

  2. Aponte sua aplicação

    Mesmos caminhos, mesmos corpos, mesmas respostas, mesmos códigos de erro. Qualquer token bearer é aceito, desde que exista.

    - WHATSAPP_GRAPH_URL=https://graph.facebook.com/v23.0
+ WHATSAPP_GRAPH_URL=http://localhost:3010/v23.0
  WHATSAPP_PHONE_NUMBER_ID=1234567890
  WHATSAPP_TOKEN=test

  3. Crie um template

    Ele passa por uma revisão, aprovada em 2 segundos por padrão, e o veredito chega no webhook message_template_status_update.

    curl -X POST localhost:3010/v23.0/100000000000001/message_templates \
  -H 'Authorization: Bearer test' -H 'Content-Type: application/json' \
  -d '{"name":"appointment_reminder","language":"pt_BR","category":"UTILITY",
       "components":[{"type":"BODY","text":"Olá {{1}}, sua consulta é amanhã às {{2}}.",
         "example":{"body_text":[["Maria","14:30"]]}},
       {"type":"BUTTONS","buttons":[{"type":"QUICK_REPLY","text":"Confirmar"},
         {"type":"QUICK_REPLY","text":"Remarcar"}]}]}'
# → {"id":"…","status":"PENDING","category":"UTILITY"}

  4. Envie

    curl -X POST localhost:3010/v23.0/1234567890/messages \
  -H 'Authorization: Bearer test' -H 'Content-Type: application/json' \
  -d '{"messaging_product":"whatsapp","to":"5511987654321","type":"template",
       "template":{"name":"appointment_reminder","language":{"code":"pt_BR"},
       "components":[{"type":"body","parameters":[
         {"type":"text","text":"Maria"},{"type":"text","text":"14:30"}]}]}}'
# → {"messages":[{"id":"wamid.…","message_status":"accepted"}]}, depois sent, delivered, read

    Abra o painel: a conversa com 5511987654321 mostra o template como o WhatsApp desenha, com os botões.

  5. Responda como o usuário

    Toque num botão ou digite no painel, ou faça isso de um teste com um header:

    curl -X POST localhost:3010/v23.0/1234567890/messages \
  -H 'Authorization: Bearer test' -H 'Content-Type: application/json' \
  -H 'X-Mock-From: 5511987654321' -H 'X-Mock-Contact-Name: Maria Souza' \
  -d '{"messaging_product":"whatsapp","type":"text","text":{"body":"Oi! Quero remarcar."}}'
# → o seu endpoint recebe o webhook messages, assinado com x-hub-signature-256

  6. No seu compose

    services:
  whatsapp:
    image: ghcr.io/instituto-ama/whatsapp-mock:latest
    ports:
      - '3010:3010'
    environment:
      WEBHOOK_URL: http://host.docker.internal:4000/webhooks/whatsapp
      WEBHOOK_SECRET: my-app-secret
      WEBHOOK_LOCALHOST_REWRITE: host.docker.internal
    extra_hosts:
      - 'host.docker.internal:host-gateway'   # Linux
    volumes:
      - whatsapp-data:/app/data               # conversas, templates, números, mídia
volumes:
  whatsapp-data:

    Templates também podem vir de arquivos: todo JSON numa pasta templates/ montada é importado no boot e quando muda.

  7. No CI

    Não guarde nada entre execuções e tire as esperas:

    WHAP_DB=:memory:
MOCK_WEBHOOK_RESPONSE_DELAY_MS=0
MOCK_TEMPLATE_REVIEW_DELAY_MS=0