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

# FAQ

> Perguntas frequentes sobre a Wapizap API

# Perguntas Frequentes

## Geral

<AccordionGroup>
  <Accordion title="O que é a Wapizap API?">
    A Wapizap API é uma API RESTful para integração com WhatsApp. Permite enviar e receber mensagens, gerenciar grupos, configurar webhooks e muito mais - tudo de forma programática.
  </Accordion>

  <Accordion title="A Wapizap API é oficial do WhatsApp?">
    Não. A Wapizap utiliza a biblioteca Baileys para conexão com WhatsApp Web. Para a API oficial do WhatsApp Business, consulte a documentação da Meta.
  </Accordion>

  <Accordion title="Posso usar para envio em massa (spam)?">
    **Não.** O uso para spam viola nossos termos de uso e pode resultar em banimento da conta WhatsApp. Use de forma responsável e respeite os usuários.
  </Accordion>

  <Accordion title="Quantas instâncias posso criar?">
    Depende do seu plano:

    * **Free**: 1 instância
    * **Starter**: 3 instâncias
    * **Pro**: 10 instâncias
    * **Enterprise**: Ilimitado
  </Accordion>
</AccordionGroup>

***

## Instâncias e Conexão

<AccordionGroup>
  <Accordion title="Como conectar uma instância ao WhatsApp?">
    1. Crie uma instância via API
    2. Obtenha o QR code ou código de pareamento
    3. No WhatsApp do celular, vá em **Configurações → Aparelhos conectados**
    4. Escaneie o QR code ou digite o código de pareamento
  </Accordion>

  <Accordion title="Por que minha instância desconecta?">
    Possíveis causas:

    * Deslogou do WhatsApp no celular
    * Muitos dispositivos conectados (limite de 4)
    * Inatividade prolongada
    * Problemas de rede

    **Solução:** Reconecte a instância e verifique se não excedeu o limite de dispositivos.
  </Accordion>

  <Accordion title="O QR code expirou, o que fazer?">
    QR codes expiram em 60 segundos. Faça uma nova requisição ao endpoint `/instances/{id}/qrcode` para gerar um novo.
  </Accordion>

  <Accordion title="Posso usar o mesmo número em múltiplas instâncias?">
    **Não.** Cada número WhatsApp só pode estar conectado a uma instância por vez.
  </Accordion>

  <Accordion title="Preciso manter o celular conectado?">
    **Não.** Após escanear o QR code, a conexão é independente. O celular pode ficar offline ou desligado.
  </Accordion>
</AccordionGroup>

***

## Mensagens

<AccordionGroup>
  <Accordion title="Qual o formato correto do número?">
    Use formato internacional **sem símbolos**:

    * Correto: `5511999999999`
    * Incorreto: `+55 (11) 99999-9999`

    Formato: `[código país][DDD][número]`
  </Accordion>

  <Accordion title="Como enviar para grupos?">
    Use o ID do grupo no campo `to`. O ID tem formato `120363XXXXX@g.us`.

    ```json theme={null}
    {
      "instanceId": "sua-instancia",
      "to": "120363123456789012@g.us",
      "type": "text",
      "text": "Mensagem para o grupo"
    }
    ```
  </Accordion>

  <Accordion title="Quais tipos de mídia são suportados?">
    | Tipo      | Formatos            | Tamanho Máximo |
    | --------- | ------------------- | -------------- |
    | Imagem    | JPG, PNG, WEBP, GIF | 16 MB          |
    | Vídeo     | MP4, 3GP            | 64 MB          |
    | Áudio     | MP3, OGG, M4A, WAV  | 16 MB          |
    | Documento | PDF, DOC, XLS, etc. | 100 MB         |
  </Accordion>

  <Accordion title="Por que a mensagem não foi entregue?">
    Possíveis causas:

    * Número não existe no WhatsApp (use `/contacts/check` para validar)
    * Você foi bloqueado pelo destinatário
    * Problema de conexão da instância
    * Rate limit excedido
  </Accordion>

  <Accordion title="Como saber se a mensagem foi lida?">
    Configure um webhook para o evento `message.ack`. Os status são:

    * `1` = Enviado (um check)
    * `2` = Entregue (dois checks)
    * `3` = Lido (checks azuis)
  </Accordion>
</AccordionGroup>

***

## Webhooks

<AccordionGroup>
  <Accordion title="O que são webhooks?">
    Webhooks são notificações HTTP enviadas para sua aplicação quando eventos acontecem (nova mensagem, status de entrega, etc.). Em vez de ficar consultando a API, você recebe os dados automaticamente.
  </Accordion>

  <Accordion title="Meu webhook não está recebendo dados">
    Verifique:

    1. A URL é acessível publicamente (não localhost)
    2. Usa HTTPS em produção
    3. Responde com HTTP 200 em menos de 5 segundos
    4. O webhook está ativo no dashboard
  </Accordion>

  <Accordion title="Como testar webhooks localmente?">
    Use um serviço de túnel como:

    * **ngrok**: `ngrok http 3000`
    * **Cloudflare Tunnel**: `cloudflared tunnel --url http://localhost:3000`

    Use a URL gerada como endpoint do webhook.
  </Accordion>

  <Accordion title="Os webhooks têm retry automático?">
    Sim. Se seu servidor não responder com 2xx:

    * 1ª tentativa: Imediata
    * 2ª tentativa: Após 1 minuto
    * 3ª tentativa: Após 5 minutos
    * 4ª tentativa: Após 30 minutos

    Após 4 falhas, o webhook é desativado.
  </Accordion>
</AccordionGroup>

***

## Limites e Planos

<AccordionGroup>
  <Accordion title="Quais são os rate limits?">
    | Operação           | Limite                  |
    | ------------------ | ----------------------- |
    | Enviar mensagens   | 30/minuto por instância |
    | Criar instâncias   | 10/hora                 |
    | Requisições gerais | 120/minuto              |

    Veja detalhes em [Rate Limits](/support/rate-limits).
  </Accordion>

  <Accordion title="O que acontece se exceder o rate limit?">
    Você receberá erro HTTP 429 com o tempo para aguardar. Implemente exponential backoff para lidar com isso automaticamente.
  </Accordion>

  <Accordion title="Como fazer upgrade do plano?">
    Acesse o [Dashboard](https://dashboard.wapizap.com) → **Configurações** → **Plano** e selecione o plano desejado.
  </Accordion>
</AccordionGroup>

***

## Segurança

<AccordionGroup>
  <Accordion title="Minhas mensagens são armazenadas?">
    Mensagens são processadas em tempo real e **não são armazenadas** permanentemente em nossos servidores. Apenas metadados necessários para o funcionamento são mantidos temporariamente.
  </Accordion>

  <Accordion title="A conexão é criptografada?">
    Sim. Todas as comunicações usam HTTPS/TLS. A criptografia ponta-a-ponta do WhatsApp é mantida.
  </Accordion>

  <Accordion title="Como proteger minha API Key?">
    * Use variáveis de ambiente (não hardcode)
    * Nunca exponha em código frontend
    * Rotacione periodicamente
    * Use chaves diferentes para dev/prod
  </Accordion>

  <Accordion title="Posso restringir acesso por IP?">
    Sim, no plano Enterprise. Entre em contato com o suporte para configurar whitelist de IPs.
  </Accordion>
</AccordionGroup>

***

## Problemas Técnicos

<AccordionGroup>
  <Accordion title="Erro 'Instance not connected'">
    A instância perdeu conexão com o WhatsApp. Reconecte usando:

    1. `POST /instances/{id}/connect` para gerar novo QR code
    2. Escaneie o QR code no celular
  </Accordion>

  <Accordion title="Erro 'Invalid number'">
    O número não está registrado no WhatsApp. Use `/contacts/check` para validar números antes de enviar mensagens.
  </Accordion>

  <Accordion title="Erro 'Rate limit exceeded'">
    Você excedeu o limite de requisições. Aguarde o tempo indicado na resposta e implemente throttling na sua aplicação.
  </Accordion>

  <Accordion title="A API está fora do ar?">
    Verifique nosso [Status Page](https://status.wapizap.com) para informações sobre incidentes. Se o problema persistir, contate o suporte.
  </Accordion>
</AccordionGroup>

***

## Não encontrou sua pergunta?

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/support/troubleshooting">
    Guia de solução de problemas
  </Card>

  <Card title="Suporte" icon="headset" href="mailto:support@wapizap.com">
    Entre em contato conosco
  </Card>
</CardGroup>