Pular para o conteúdo principal

​
Gerenciando Instâncias

Uma instância representa um único número WhatsApp conectado à Wappfy. Cada instância passa por um ciclo de vida: criar, conectar, escanear QR, usar, e eventualmente desconectar ou excluir.

​
Tipos de Instância

A Wappfy suporta dois provedores:
TipoDescrição
wahaAPI WhatsApp Web auto-hospedada via WAHA Plus. Suporte completo incluindo grupos, etiquetas e contatos.
cloud_apiAPI oficial WhatsApp Business Cloud da Meta. Requer uma conta Meta Business.

​
Valores de Status da Instância

Ao longo do seu ciclo de vida, uma instância transita pelos seguintes status:
StatusDescrição
createdO registro da instância existe, mas ainda não foi iniciado.
startingA instância está inicializando a sessão do WhatsApp.
scan_qrA instância está aguardando você escanear o QR code com seu celular.
connectedA sessão do WhatsApp está ativa e pronta para enviar/receber mensagens.
disconnectedA sessão foi interrompida ou perdeu a conexão. Pode ser reconectada.
failedA instância encontrou um erro durante a inicialização ou conexão.

​
Visão Geral do Ciclo de Vida

​
Criar uma Instância

Crie uma nova instância WhatsApp vinculada à sua conta. 
curl -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu WhatsApp",
    "type": "waha"
  }'
Resposta: 
{
  "data": {
    "id": "inst_abc123",
    "name": "Meu WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}

​
Conectar uma Instância

Inicie a sessão do WhatsApp. A instância passará para o status starting e depois para scan_qr. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: SUA_CHAVE_API"
Resposta: 
{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}

​
Obter o QR Code

Quando a instância atingir o status scan_qr, obtenha o QR code para escanear com seu celular. 
curl https://api.wappfy.io/api/instances/inst_abc123/qr \
  -H "X-Api-Key: SUA_CHAVE_API"
Resposta: 
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
O QR code expira após aproximadamente 60 segundos. Se expirar antes de você escaneá-lo, chame o endpoint novamente para obter um novo código.
Abra a imagem do QR code e escaneie com WhatsApp > Aparelhos Conectados > Conectar um Aparelho no seu celular. Após o escaneamento, o status da instância mudará para connected.

​
Verificar o Status da Instância

Consulte o endpoint de status para saber quando a instância está pronta. 
curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: SUA_CHAVE_API"
Resposta: 
{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}
Em vez de fazer polling, configure um webhook para os eventos instance.connected e instance.qr para ser notificado em tempo real.

​
Listar Todas as Instâncias

Recupere todas as instâncias da sua conta. 
curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: SUA_CHAVE_API"
Resposta: 
{
  "data": [
    {
      "id": "inst_abc123",
      "name": "Meu WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Linha de Suporte",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}

​
Desconectar uma Instância

Pare a sessão do WhatsApp sem excluir a instância. Você pode reconectar depois. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
  -H "X-Api-Key: SUA_CHAVE_API"

​
Reiniciar uma Instância

Reinicie a sessão do WhatsApp. Isso é útil quando a instância está em estado failed ou se comportando de forma inesperada. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: SUA_CHAVE_API"
Reiniciar preserva a sessão vinculada do WhatsApp. Você não precisará escanear o QR code novamente.

​
Fazer Logout de uma Instância

Faça logout do WhatsApp completamente. Isso desvincula o telefone da sessão. Você precisará escanear o QR code novamente para reconectar. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: SUA_CHAVE_API"
O logout remove completamente o vínculo com o WhatsApp. Diferentemente da desconexão, você precisa escanear um novo QR code para usar esta instância novamente.

​
Excluir uma Instância

Exclua permanentemente uma instância e todos os seus dados associados. 
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: SUA_CHAVE_API"
Esta ação é irreversível. Todas as mensagens, webhooks e configurações associadas a esta instância serão permanentemente excluídas.

​
Exemplo Completo do Ciclo de Vida

Aqui está um exemplo completo que cria uma instância, conecta e obtém o QR code: 
# 1. Criar a instância
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"name": "Produção", "type": "waha"}')

INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Instância criada: $INSTANCE_ID"

# 2. Conectar a instância
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: SUA_CHAVE_API"

# 3. Aguardar e obter o QR code
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
  -H "X-Api-Key: SUA_CHAVE_API")

echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code salvo em qr-code.png — escaneie com seu celular"

# 4. Aguardar o status de conexão
while true; do
  STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
    -H "X-Api-Key: SUA_CHAVE_API" | jq -r '.data.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "connected" ]; then
    echo "Instância conectada e pronta!"
    break
  fi
  sleep 2
done

​
Tratamento de Erros

Código de StatusDescrição
404Instância não encontrada ou não pertence à sua conta.
409A instância já está no estado solicitado (ex: já conectada).
422Corpo da requisição inválido (ex: name ausente ou type inválido).
429Limite de requisições excedido. Veja Limites de Requisição.