> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oxenty.api.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Boas Práticas

> Dicas essenciais para usar a Oxenty API de forma segura e eficiente

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:

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

### O que fazer

<AccordionGroup>
  <Accordion icon="clock" title="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**.

    ```typescript theme={"system"}
    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
    }
    ```
  </Accordion>

  <Accordion icon="user-check" title="Envie apenas para contatos que consentiram">
    Só envie mensagens para pessoas que explicitamente optaram por receber
    comunicações. Mantenha registros de opt-in.
  </Accordion>

  <Accordion icon="message-circle" title="Personalize mensagens">
    Evite enviar a mesma mensagem idêntica para muitas pessoas. Use variáveis
    como nome, data, valores específicos.

    ```typescript theme={"system"}
    // Ruim - Mensagem idêntica
    "Confira nossa promoção!"

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

  <Accordion icon="history" title="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+          |
  </Accordion>

  <Accordion icon="message-circle" title="Mantenha conversas bidirecionais">
    Contas que apenas enviam mensagens sem receber respostas são suspeitas.
    Incentive interação e responda rapidamente.
  </Accordion>
</AccordionGroup>

### O que NÃO fazer

<CardGroup cols={2}>
  <Card title="Spam em massa" icon="ban">
    Enviar mensagens não solicitadas para listas compradas ou números aleatórios.
  </Card>

  <Card title="Mensagens repetitivas" icon="copy">
    Enviar a mesma mensagem idêntica para centenas de pessoas.
  </Card>

  <Card title="Volume alto imediato" icon="rocket">
    Começar a usar um número novo com alto volume de mensagens.
  </Card>

  <Card title="Ignorar bloqueios" icon="user-x">
    Tentar contatar pessoas que bloquearam seu número.
  </Card>
</CardGroup>

***

## Gerenciamento de Sessões

### Reconexão Automática

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

```typescript theme={"system"}
// 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:

```typescript theme={"system"}
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

<Steps>
  <Step title="Use variáveis de ambiente">
    ```bash theme={"system"}
    # .env (nunca commite este arquivo!)
    OXENTY_API_KEY=oxt_sk_xxxxxxxx
    WEBHOOK_SECRET=whsec_xxxxxxxx
    ```

    ```typescript theme={"system"}
    const client = new OxentyClient({
      apiKey: process.env.OXENTY_API_KEY,
    });
    ```
  </Step>

  <Step title="Rotacione keys regularmente">
    Crie novas API Keys periodicamente e revogue as antigas no Dashboard.
  </Step>

  <Step title="Use permissões mínimas">
    Ao criar API Keys, conceda apenas as permissões necessárias para cada
    integração específica.
  </Step>
</Steps>

### Validação de Webhooks

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

```typescript theme={"system"}
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:

```typescript theme={"system"}
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:

```typescript theme={"system"}
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:

```typescript theme={"system"}
// 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:

```typescript theme={"system"}
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:

```typescript theme={"system"}
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

```typescript theme={"system"}
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:

<Steps>
  <Step title="Segurança">
    * [ ] API Keys em variáveis de ambiente
    * [ ] Validação de webhook implementada
    * [ ] HTTPS em todos os endpoints
    * [ ] Permissões mínimas nas API Keys
  </Step>

  <Step title="Confiabilidade">
    * [ ] Retry com backoff implementado
    * [ ] Reconexão automática de sessões
    * [ ] Circuit breaker para chamadas críticas
    * [ ] Processamento assíncrono de webhooks
  </Step>

  <Step title="Monitoramento">
    * [ ] Logs estruturados
    * [ ] Alertas configurados
    * [ ] Dashboard de métricas
    * [ ] Health checks ativos
  </Step>

  <Step title="Compliance">
    * [ ] Opt-in documentado
    * [ ] Opt-out implementado
    * [ ] Rate limits respeitados
    * [ ] LGPD/GDPR compliance
  </Step>
</Steps>