Skip to main content

​
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:
TypeDescription
wahaSelf-hosted WhatsApp Web API via WAHA Plus. Full feature support including groups, labels, and contacts.
cloud_apiMeta’s official WhatsApp Business Cloud API. Requires a Meta Business account.

​
Instance Status Values

Throughout its lifecycle, an instance transitions through these statuses:
StatusDescription
createdInstance record exists but has not been started yet.
startingInstance is booting up and initializing the WhatsApp session.
scan_qrInstance is waiting for you to scan the QR code with your phone.
connectedWhatsApp session is active and ready to send/receive messages.
disconnectedSession was stopped or lost connection. Can be reconnected.
failedInstance 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"
  }'
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"
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 CodeDescription
404Instance not found or does not belong to your account.
409Instance is already in the requested state (e.g., already connected).
422Invalid request body (e.g., missing name or invalid type).
429Rate limit exceeded. See Rate Limits.