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:

Tipo	Descrição
`waha`	API WhatsApp Web auto-hospedada via WAHA Plus. Suporte completo incluindo grupos, etiquetas e contatos.
`cloud_api`	API 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:

Status	Descrição
`created`	O registro da instância existe, mas ainda não foi iniciado.
`starting`	A instância está inicializando a sessão do WhatsApp.
`scan_qr`	A instância está aguardando você escanear o QR code com seu celular.
`connected`	A sessão do WhatsApp está ativa e pronta para enviar/receber mensagens.
`disconnected`	A sessão foi interrompida ou perdeu a conexão. Pode ser reconectada.
`failed`	A 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"
  }'

const response = await fetch("https://api.wappfy.io/api/instances", {
  method: "POST",
  headers: {
    "X-Api-Key": "SUA_CHAVE_API",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Meu WhatsApp",
    type: "waha",
  }),
});

const instance = await response.json();
console.log(instance.data.id); // use este ID em todas as chamadas seguintes

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"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/qr",
  {
    headers: { "X-Api-Key": "SUA_CHAVE_API" },
  }
);

const { data } = await response.json();
// data.qr contém a imagem do QR code em base64

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 Status	Descrição
`404`	Instância não encontrada ou não pertence à sua conta.
`409`	A instância já está no estado solicitado (ex: já conectada).
`422`	Corpo da requisição inválido (ex: `name` ausente ou `type` inválido).
`429`	Limite de requisições excedido. Veja Limites de Requisição.

Primeiros Passos

Guias

Gerenciando Instâncias

Gerenciando Instâncias

Tipos de Instância

Valores de Status da Instância

Visão Geral do Ciclo de Vida

Criar uma Instância

Conectar uma Instância

Obter o QR Code

Verificar o Status da Instância

Listar Todas as Instâncias

Desconectar uma Instância

Reiniciar uma Instância

Fazer Logout de uma Instância

Excluir uma Instância

Exemplo Completo do Ciclo de Vida

Tratamento de Erros

​Gerenciando Instâncias

​Tipos de Instância

​Valores de Status da Instância

​Visão Geral do Ciclo de Vida

​Criar uma Instância

​Conectar uma Instância

​Obter o QR Code

​Verificar o Status da Instância

​Listar Todas as Instâncias

​Desconectar uma Instância

​Reiniciar uma Instância

​Fazer Logout de uma Instância

​Excluir uma Instância

​Exemplo Completo do Ciclo de Vida

​Tratamento de Erros

Gerenciando Instâncias

Tipos de Instância

Valores de Status da Instância

Visão Geral do Ciclo de Vida

Criar uma Instância

Conectar uma Instância

Obter o QR Code

Verificar o Status da Instância

Listar Todas as Instâncias

Desconectar uma Instância

Reiniciar uma Instância

Fazer Logout de uma Instância

Excluir uma Instância

Exemplo Completo do Ciclo de Vida

Tratamento de Erros