Gestion de instancias

Una instancia representa un unico numero de WhatsApp conectado a Wappfy. Cada instancia pasa por un ciclo de vida: crear, conectar, escanear QR, usar y eventualmente desconectar o eliminar.

Tipos de instancia

Wappfy soporta dos proveedores:

Tipo	Descripcion
`waha`	API de WhatsApp Web autoalojada mediante WAHA Plus. Soporte completo de funcionalidades incluyendo grupos, etiquetas y contactos.
`cloud_api`	API oficial de WhatsApp Business Cloud de Meta. Requiere una cuenta Meta Business.

Valores de estado de la instancia

A lo largo de su ciclo de vida, una instancia transiciona entre estos estados:

Estado	Descripcion
`created`	El registro de la instancia existe pero aun no ha sido iniciada.
`starting`	La instancia esta iniciandose y configurando la sesion de WhatsApp.
`scan_qr`	La instancia esta esperando a que escanees el codigo QR con tu telefono.
`connected`	La sesion de WhatsApp esta activa y lista para enviar/recibir mensajes.
`disconnected`	La sesion fue detenida o perdio la conexion. Puede reconectarse.
`failed`	La instancia encontro un error durante el inicio o la conexion.

Vista general del ciclo de vida

Crear una instancia

Crea una nueva instancia de WhatsApp asociada a tu cuenta.

curl -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My WhatsApp",
    "type": "waha"
  }'

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

const instance = await response.json();
console.log(instance.data.id); // use this ID for all subsequent calls

Respuesta:

{
  "data": {
    "id": "inst_abc123",
    "name": "My WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}

Conectar una instancia

Inicia la sesion de WhatsApp. La instancia pasara al estado starting y luego a scan_qr.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: YOUR_API_KEY"

Respuesta:

{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}

Obtener el codigo QR

Una vez que la instancia alcance el estado scan_qr, recupera el codigo QR para escanearlo con tu telefono.

curl https://api.wappfy.io/api/instances/inst_abc123/qr \
  -H "X-Api-Key: YOUR_API_KEY"

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

const { data } = await response.json();
// data.qr contains a base64-encoded QR code image

Respuesta:

{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}

El codigo QR expira aproximadamente despues de 60 segundos. Si expira antes de escanearlo, llama al endpoint nuevamente para obtener un codigo nuevo.

Abre la imagen del codigo QR y escaneala con WhatsApp > Dispositivos vinculados > Vincular un dispositivo en tu telefono. Una vez escaneado, el estado de la instancia cambiara a connected.

Verificar el estado de la instancia

Consulta el endpoint de estado para saber cuando la instancia esta lista.

curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: YOUR_API_KEY"

Respuesta:

{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}

En lugar de hacer polling, configura un webhook para los eventos instance.connected e instance.qr para recibir notificaciones en tiempo real.

Listar todas las instancias

Recupera todas las instancias de tu cuenta.

curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY"

Respuesta:

{
  "data": [
    {
      "id": "inst_abc123",
      "name": "My WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Support Line",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}

Desconectar una instancia

Detiene la sesion de WhatsApp sin eliminar la instancia. Puedes reconectar despues.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
  -H "X-Api-Key: YOUR_API_KEY"

Reiniciar una instancia

Reinicia la sesion de WhatsApp. Esto es util si la instancia esta en estado failed o se comporta de manera inesperada.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: YOUR_API_KEY"

Reiniciar preserva la sesion de WhatsApp vinculada. No necesitaras escanear el codigo QR nuevamente.

Cerrar sesion de una instancia

Cierra la sesion de WhatsApp completamente. Esto desvincula el telefono de la sesion. Necesitaras escanear el codigo QR nuevamente para reconectar.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: YOUR_API_KEY"

Cerrar sesion elimina completamente el vinculo con WhatsApp. A diferencia de desconectar, debes escanear un nuevo codigo QR para usar esta instancia de nuevo.

Eliminar una instancia

Elimina permanentemente una instancia y todos sus datos asociados.

curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: YOUR_API_KEY"

Esta accion es irreversible. Todos los mensajes, webhooks y configuracion asociados a esta instancia seran eliminados permanentemente.

Ejemplo de ciclo de vida completo

Aqui tienes un ejemplo completo que crea una instancia, la conecta y consulta el codigo QR:

# 1. Crear la instancia
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "type": "waha"}')

INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Created instance: $INSTANCE_ID"

# 2. Conectar la instancia
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Esperar un momento, luego obtener el codigo QR
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
  -H "X-Api-Key: YOUR_API_KEY")

echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code saved to qr-code.png — scan it with your phone"

# 4. Consultar el estado hasta que este conectado
while true; do
  STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
    -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "connected" ]; then
    echo "Instance is connected and ready!"
    break
  fi
  sleep 2
done

Manejo de errores

Codigo de estado	Descripcion
`404`	Instancia no encontrada o no pertenece a tu cuenta.
`409`	La instancia ya esta en el estado solicitado (por ejemplo, ya conectada).
`422`	Cuerpo de solicitud invalido (por ejemplo, falta `name` o `type` invalido).
`429`	Limite de tasa excedido. Consulta Limites de tasa.

Primeros Pasos

Guías

Gestion de instancias

Gestion de instancias

Tipos de instancia

Valores de estado de la instancia

Vista general del ciclo de vida

Crear una instancia

Conectar una instancia

Obtener el codigo QR

Verificar el estado de la instancia

Listar todas las instancias

Desconectar una instancia

Reiniciar una instancia

Cerrar sesion de una instancia

Eliminar una instancia

Ejemplo de ciclo de vida completo

Manejo de errores

​Gestion de instancias

​Tipos de instancia

​Valores de estado de la instancia

​Vista general del ciclo de vida

​Crear una instancia

​Conectar una instancia

​Obtener el codigo QR

​Verificar el estado de la instancia

​Listar todas las instancias

​Desconectar una instancia

​Reiniciar una instancia

​Cerrar sesion de una instancia

​Eliminar una instancia

​Ejemplo de ciclo de vida completo

​Manejo de errores

Gestion de instancias

Tipos de instancia

Valores de estado de la instancia

Vista general del ciclo de vida

Crear una instancia

Conectar una instancia

Obtener el codigo QR

Verificar el estado de la instancia

Listar todas las instancias

Desconectar una instancia

Reiniciar una instancia

Cerrar sesion de una instancia

Eliminar una instancia

Ejemplo de ciclo de vida completo

Manejo de errores