Gerenciamento de Instâncias

Este guia explica como criar e gerenciar instâncias do WhatsApp no ZapFlare.

O que são Instâncias?

Uma instância representa uma conexão com o WhatsApp. Cada instância:

• Conecta a um número de telefone único
• Mantém sessão persistente
• Pode enviar e receber mensagens
• Tem webhook próprio para eventos

Criando uma Instância

Via Dashboard

1. Acesse Instâncias no menu
2. Clique em Nova Instância
3. Preencha o nome descritivo
4. Configure o webhook (opcional)
5. Clique em Criar

Via API

const response = await fetch('https://api.zapflare.io/whatsapp/instances', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer SEU_API_KEY'
  },
  body: JSON.stringify({
    name: 'Atendimento Principal',
    description: 'Instância principal de atendimento',
    webhookUrl: 'https://meu-webhook.com/whatsapp',
    webhookEvents: ['message', 'status', 'connection']
  })
});

const instance = await response.json();
console.log('Instância criada:', instance.data.id);

Parâmetros de Criação

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da instância (3-100 caracteres)
description	string	Não	Descrição detalhada
webhookUrl	string	Não	URL para receber eventos
webhookEvents	array	Não	Eventos a receber: message, status, connection

Conectando ao WhatsApp

Após criar a instância:

1. Um QR Code será gerado automaticamente
2. Abra o WhatsApp no celular
3. Vá em Configurações > Dispositivos Conectados
4. Escaneie o QR Code

Importante

• Cada QR Code expira em 20 segundos
• Você tem até 6 tentativas (2 minutos total)
• Se expirar, use o endpoint de regeneração

Monitorando Status

Estados Possíveis

• created - Recém criada
• qr - Aguardando leitura do QR
• connected - Conectada e operacional
• disconnected - Desconectada temporariamente
• banned - Número banido

Verificando Status

const status = await fetch(`https://api.zapflare.io/whatsapp/instances/${instanceId}`, {
  headers: {
    'Cookie': 'auth-session=...'
  }
});

const data = await status.json();
console.log('Status:', data.data.status);

Estados da Instância

Estado	Descrição
initializing	Instância sendo criada
waiting_qr	Aguardando leitura do QR Code
connected	Conectada e operacional
disconnected	Desconectada temporariamente
error	Erro na conexão

Operações com Instâncias

Listar Instâncias

const response = await fetch('https://api.zapflare.io/whatsapp/instances', {
  headers: {
    'Authorization': 'Bearer SEU_API_KEY'
  }
});

Obter Detalhes

const response = await fetch(`https://api.zapflare.io/whatsapp/instances/${instanceId}`, {
  headers: {
    'Authorization': 'Bearer SEU_API_KEY'
  }
});

Atualizar Instância

const response = await fetch(`https://api.zapflare.io/whatsapp/instances/${instanceId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer SEU_API_KEY'
  },
  body: JSON.stringify({
    name: 'Novo Nome',
    webhookUrl: 'https://novo-webhook.com'
  })
});

Desconectar

const response = await fetch(`https://api.zapflare.io/whatsapp/instances/${instanceId}/disconnect`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_API_KEY'
  }
});

Regenerar QR Code

const response = await fetch(`https://api.zapflare.io/whatsapp/instances/${instanceId}/regenerate-qr`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_API_KEY'
  }
});

Deletar Instância

const response = await fetch(`https://api.zapflare.io/whatsapp/instances/${instanceId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer SEU_API_KEY'
  }
});

Boas Práticas

1. Nomeie descritivamente - Use nomes que identifiquem o propósito
2. Configure webhooks - Receba eventos em tempo real
3. Monitore conexões - Implemente reconexão automática
4. Respeite limites - Evite criar instâncias desnecessárias

Próximos Passos

• Enviar mensagens
• Configurar webhooks
• API de instâncias