Boas Práticas

Siga estas recomendações para maximizar a eficiência, evitar problemas de ban e garantir a melhor experiência para seus usuários.

Evitando Ban do WhatsApp

O WhatsApp possui sistemas anti-spam rigorosos. Siga estas práticas para manter sua conta segura:

Violações podem resultar em ban temporário ou permanente do número. Use a API de forma responsável.

O que fazer

Respeite intervalos entre mensagens

Envie no máximo 1 mensagem a cada 2-3 segundos para o mesmo contato. Para contatos diferentes, mantenha um intervalo de 500ms-1s.

const delay = (ms: number) => new Promise(r => setTimeout(r, ms));

for (const contact of contacts) {
  await client.messages.sendText(sessionId, {
    to: contact.phone,
    text: message,
  });
  await delay(1000); // 1 segundo entre mensagens
}

Envie apenas para contatos que consentiram

Só envie mensagens para pessoas que explicitamente optaram por receber comunicações. Mantenha registros de opt-in.

Personalize mensagens

Evite enviar a mesma mensagem idêntica para muitas pessoas. Use variáveis como nome, data, valores específicos.

// Ruim - Mensagem idêntica
"Confira nossa promoção!"

// Bom - Mensagem personalizada
`Olá ${nome}! Temos uma oferta especial para você: ${produto} com ${desconto}% off!`

Construa histórico gradualmente

Novos números devem começar com baixo volume e aumentar gradualmente ao longo de semanas.

Semana	Mensagens/dia
1	10-20
2	30-50
3	50-100
4+	100+

Mantenha conversas bidirecionais

Contas que apenas enviam mensagens sem receber respostas são suspeitas. Incentive interação e responda rapidamente.

O que NÃO fazer

Spam em massa

Enviar mensagens não solicitadas para listas compradas ou números aleatórios.

Mensagens repetitivas

Enviar a mesma mensagem idêntica para centenas de pessoas.

Volume alto imediato

Começar a usar um número novo com alto volume de mensagens.

Ignorar bloqueios

Tentar contatar pessoas que bloquearam seu número.

Gerenciamento de Sessões

Reconexão Automática

Configure handlers para reconectar automaticamente quando a sessão desconectar:

// Via Webhooks
app.post('/webhook', (req, res) => {
  const event = req.body;
  
  if (event.type === 'session.disconnected') {
    const { sessionId, data } = event;
    
    // Apenas reconecta se foi desconexão não intencional
    if (data.reason !== 'logged_out') {
      setTimeout(async () => {
        try {
          await client.sessions.connect(sessionId);
          console.log(`Sessão ${sessionId} reconectada`);
        } catch (error) {
          console.error('Falha ao reconectar:', error);
        }
      }, 5000); // Aguarda 5s antes de reconectar
    }
  }
  
  res.status(200).send('OK');
});

Monitoramento de Status

Verifique periodicamente o status das sessões:

async function monitorSessions() {
  const sessions = await client.sessions.list();
  
  for (const session of sessions) {
    if (session.status === 'disconnected') {
      // Notificar ou tentar reconectar
      await notifyAdmin(`Sessão ${session.name} está desconectada`);
    }
  }
}

// Executar a cada 5 minutos
setInterval(monitorSessions, 5 * 60 * 1000);

Segurança

Proteja suas Credenciais

Use variáveis de ambiente

# .env (nunca commite este arquivo!)
OXENTY_API_KEY=oxt_sk_xxxxxxxx
WEBHOOK_SECRET=whsec_xxxxxxxx

const client = new OxentyClient({
  apiKey: process.env.OXENTY_API_KEY,
});

Rotacione keys regularmente

Crie novas API Keys periodicamente e revogue as antigas no Dashboard.

Use permissões mínimas

Ao criar API Keys, conceda apenas as permissões necessárias para cada integração específica.

Validação de Webhooks

Sempre valide a assinatura dos webhooks antes de processá-los:

import crypto from 'crypto';

function validateWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Performance

Use Cache

Cache respostas que mudam pouco para reduzir requisições:

import NodeCache from 'node-cache';

const cache = new NodeCache({ stdTTL: 300 }); // 5 minutos

async function getSessions() {
  const cached = cache.get('sessions');
  if (cached) return cached;
  
  const sessions = await client.sessions.list();
  cache.set('sessions', sessions);
  
  return sessions;
}

Processe Webhooks Assíncronamente

Não bloqueie a resposta do webhook com processamento pesado:

import { Queue } from 'bullmq';

const webhookQueue = new Queue('webhooks');

app.post('/webhook', async (req, res) => {
  // Responde imediatamente
  res.status(200).send('OK');
  
  // Processa de forma assíncrona
  await webhookQueue.add('process', req.body);
});

// Worker separado
const worker = new Worker('webhooks', async (job) => {
  const event = job.data;
  
  switch (event.type) {
    case 'message.received':
      await handleNewMessage(event.data);
      break;
    // ...
  }
});

Batch Operations

Quando possível, agrupe operações:

// Ruim - Múltiplas requisições
for (const phone of phones) {
  await client.contacts.check(sessionId, phone);
}

// Bom - Uma requisição
const results = await client.contacts.checkBatch(sessionId, phones);

Tratamento de Erros

Retry com Backoff

Implemente retries inteligentes para falhas temporárias:

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  let lastError: Error;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      lastError = error;
      
      // Não retry para erros de cliente
      if (error.status >= 400 && error.status < 500) {
        throw error;
      }
      
      const delay = baseDelay * Math.pow(2, attempt);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  
  throw lastError;
}

// Uso
const session = await withRetry(() => client.sessions.get(sessionId));

Circuit Breaker

Para alta disponibilidade, implemente circuit breaker:

import CircuitBreaker from 'opossum';

const breaker = new CircuitBreaker(
  (sessionId: string, message: any) => 
    client.messages.sendText(sessionId, message),
  {
    timeout: 10000, // 10s timeout
    errorThresholdPercentage: 50,
    resetTimeout: 30000, // 30s para tentar novamente
  }
);

breaker.on('open', () => {
  console.log('Circuit breaker aberto - API indisponível');
  // Notificar ou usar fallback
});

// Uso
await breaker.fire(sessionId, message);

Logging e Monitoramento

Estruture seus Logs

import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
});

// Log estruturado
logger.info({
  event: 'message_sent',
  sessionId,
  to: message.to,
  messageId: result.messageId,
  duration: Date.now() - startTime,
});

Métricas Importantes

Monitore estas métricas:

Métrica	Alerta se
Taxa de erro	> 5%
Latência P99	> 5s
Sessões desconectadas	> 10%
Taxa de delivery	< 95%
Webhooks falhando	> 3 consecutivos

Checklist de Produção

Antes de ir para produção, verifique:

Início rápido Webhooks

Introdução

Guias

Evitando Ban do WhatsApp

O que fazer

O que NÃO fazer

Spam em massa

Mensagens repetitivas

Volume alto imediato

Ignorar bloqueios

Gerenciamento de Sessões

Reconexão Automática

Monitoramento de Status

Segurança

Proteja suas Credenciais

Validação de Webhooks

Performance

Use Cache

Processe Webhooks Assíncronamente

Batch Operations

Tratamento de Erros

Retry com Backoff

Circuit Breaker

Logging e Monitoramento

Estruture seus Logs

Métricas Importantes

Checklist de Produção

​Evitando Ban do WhatsApp

​O que fazer

​O que NÃO fazer

Spam em massa

Mensagens repetitivas

Volume alto imediato

Ignorar bloqueios

​Gerenciamento de Sessões

​Reconexão Automática

​Monitoramento de Status

​Segurança

​Proteja suas Credenciais

​Validação de Webhooks

​Performance

​Use Cache

​Processe Webhooks Assíncronamente

​Batch Operations

​Tratamento de Erros

​Retry com Backoff

​Circuit Breaker

​Logging e Monitoramento

​Estruture seus Logs

​Métricas Importantes

​Checklist de Produção

Evitando Ban do WhatsApp

O que fazer

O que NÃO fazer

Gerenciamento de Sessões

Reconexão Automática

Monitoramento de Status

Segurança

Proteja suas Credenciais

Validação de Webhooks

Performance

Use Cache

Processe Webhooks Assíncronamente

Batch Operations

Tratamento de Erros

Retry com Backoff

Circuit Breaker

Logging e Monitoramento

Estruture seus Logs

Métricas Importantes

Checklist de Produção