Managing Instances

An instance represents a single WhatsApp number connected to Wappfy. Each instance goes through a lifecycle: create, connect, scan QR, use, and eventually disconnect or delete.

Instance Types

Wappfy supports two providers:

Type	Description
`waha`	Self-hosted WhatsApp Web API via WAHA Plus. Full feature support including groups, labels, and contacts.
`cloud_api`	Meta’s official WhatsApp Business Cloud API. Requires a Meta Business account.

Instance Status Values

Throughout its lifecycle, an instance transitions through these statuses:

Status	Description
`created`	Instance record exists but has not been started yet.
`starting`	Instance is booting up and initializing the WhatsApp session.
`scan_qr`	Instance is waiting for you to scan the QR code with your phone.
`connected`	WhatsApp session is active and ready to send/receive messages.
`disconnected`	Session was stopped or lost connection. Can be reconnected.
`failed`	Instance encountered an error during startup or connection.

Lifecycle Overview

Create an Instance

Create a new WhatsApp instance tied to your account.

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

Response:

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

Connect an Instance

Start the WhatsApp session. The instance will transition to starting and then to scan_qr.

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

Response:

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

Get the QR Code

Once the instance reaches scan_qr status, retrieve the QR code to scan with your phone.

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

Response:

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

The QR code expires after approximately 60 seconds. If it expires before you scan it, call the endpoint again to get a fresh code.

Open the QR code image and scan it with WhatsApp > Linked Devices > Link a Device on your phone. Once scanned, the instance status will change to connected.

Check Instance Status

Poll the status endpoint to know when the instance is ready.

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

Response:

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

Instead of polling, set up a webhook for instance.connected and instance.qr events to get notified in real-time.

List All Instances

Retrieve all instances for your account.

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

Response:

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

Disconnect an Instance

Stop the WhatsApp session without deleting the instance. You can reconnect later.

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

Restart an Instance

Restart the WhatsApp session. This is useful if the instance is in a failed state or behaving unexpectedly.

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

Restarting preserves the linked WhatsApp session. You will not need to scan the QR code again.

Logout an Instance

Log out from WhatsApp entirely. This unlinks the phone from the session. You will need to scan the QR code again to reconnect.

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

Logout completely removes the WhatsApp link. Unlike disconnect, you must scan a new QR code to use this instance again.

Delete an Instance

Permanently delete an instance and all its associated data.

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

This action is irreversible. All messages, webhooks, and configuration associated with this instance will be permanently deleted.

Full Lifecycle Example

Here is a complete example that creates an instance, connects it, and polls for the QR code:

# 1. Create the instance
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. Connect the instance
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Wait a moment, then fetch the QR code
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. Poll for connected status
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

Error Handling

Status Code	Description
`404`	Instance not found or does not belong to your account.
`409`	Instance is already in the requested state (e.g., already connected).
`422`	Invalid request body (e.g., missing `name` or invalid `type`).
`429`	Rate limit exceeded. See Rate Limits.

Getting Started

Guides

Managing Instances

Managing Instances

Instance Types

Instance Status Values

Lifecycle Overview

Create an Instance

Connect an Instance

Get the QR Code

Check Instance Status

List All Instances

Disconnect an Instance

Restart an Instance

Logout an Instance

Delete an Instance

Full Lifecycle Example

Error Handling

​Managing Instances

​Instance Types

​Instance Status Values

​Lifecycle Overview

​Create an Instance

​Connect an Instance

​Get the QR Code

​Check Instance Status

​List All Instances

​Disconnect an Instance

​Restart an Instance

​Logout an Instance

​Delete an Instance

​Full Lifecycle Example

​Error Handling

Managing Instances

Instance Types

Instance Status Values

Lifecycle Overview

Create an Instance

Connect an Instance

Get the QR Code

Check Instance Status

List All Instances

Disconnect an Instance

Restart an Instance

Logout an Instance

Delete an Instance

Full Lifecycle Example

Error Handling