Onboarding de cliente de agência no WhatsApp em 15 minutos: cronograma e script

Tenha pronto o saldo da conta (a agência paga, o cliente não precisa de conta), o padrão de nome e o endereço do webhook do seu sistema. Se faltar saldo para a taxa de ativação, a criação falha e a chamada trava. Consulte antes o GET /instances/cost, que informa a taxa de ativação, o valor proporcional e o saldo necessário.

Combine na confirmação da reunião uma única exigência: o cliente precisa estar com o celular que tem o número, com o WhatsApp aberto. É isso que evita o pior atraso do onboarding, o cliente que 'volta já' com o aparelho.

Crie a instância por API, com nome padronizado e o identificador do cliente no campo metadata, que acompanha a consulta da instância. O exemplo abaixo mostra o custo, a criação e a checagem de status. O campo metadata é um texto JSON, por isso o escape no exemplo.

Em seguida, no painel da instância, gere o link de conexão. No código do produto, o link tem prazo de validade e pode ser revogado, e abre uma página onde o cliente escaneia o QR code, sem criar conta. Defina a marca do cliente (nome, logo e cor) antes de enviar, para ele ver a identidade dele na página.

# Minute 3: check cost, then create the client's instance
curl "https://api.zapzapapi.com/api/v1/instances/cost" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

curl -X POST "https://api.zapzapapi.com/api/v1/instances" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"name":"clinica-sol-vendas","systemName":"Clinica Sol","metadata":"{\"clientId\":\"cli_042\",\"owner\":\"ana\"}"}'

# Minute 10: confirm the number is connected before the first real message
curl "https://api.zapzapapi.com/api/v1/INSTANCE_ID/instance/status" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

Mande o link pelo chat da reunião e peça: abra no celular que tem o número, toque para conectar e escaneie o QR code pelo WhatsApp (aparelhos conectados). Fique em silêncio nessa hora: o QR expira e o cliente erra mais quando é interrompido. Se expirar, gere de novo e reenvie.

Mensagem pronta para colar: "Olá! Aqui está o link para conectar o WhatsApp da [Empresa] à plataforma. Abra no celular que tem o número, escaneie o QR code e pronto. Leva cerca de um minuto. Se o código expirar, me avise que gero outro." Confirme no status da instância que o número ficou conectado antes de seguir.

Configure o webhook da instância para o seu sistema e use o teste de webhook da API (POST /instances/{id}/webhook/test), que envia um evento de teste assinado com o segredo da instância. Confira que o seu endpoint validou a assinatura e respondeu 200. Para fazer isso de forma segura, veja o guia de webhooks idempotentes.

Depois peça ao cliente que mande uma mensagem de outro celular para o número conectado e veja o evento chegar no seu sistema. Responda com um send/text curto. Esse teste de ida e volta vale mais do que qualquer garantia verbal.

Entregue o acesso ao portal do cliente (por link, ou por número e senha, enviados por canais diferentes) com as seções que você decidiu mostrar. Diga o que ele vai ver e quando: leads, vendas e desempenho do período. Combine quem reconecta o QR se o número cair, e a data da primeira revisão.

Feche com o alinhamento de risco, em uma frase: é uma solução não oficial, o WhatsApp pode limitar ou bloquear o número, e por isso o número novo começa devagar. Aponte o aquecimento de chip e, se o cliente tem anúncio, o fluxo de leads por cliente. O checklist completo está em checklist de onboarding.