Instance Status Event

Triggered when your WhatsApp instance connection status changes. This event helps you track when instances connect, disconnect, need QR code scanning, or encounter errors.

Event Type

instance-status

Payload Structure

{
  "event": "instance-status",
  "instanceId": "instance-uuid",
  "data": {
    "instanceId": "instance-uuid",
    "status": "connected",
    "previousStatus": "pending_qr_code_scan",
    "timestamp": 1702500000000,
    "reason": "Connection established",
    "connectedNumber": "5511999999999"
  }
}

Fields

Field	Type	Description
instanceId	string	The instance ID
status	string	Current status (see Status Values)
previousStatus	string | undefined	Previous status before this change
timestamp	number	Unix timestamp in milliseconds
reason	string | undefined	Human-readable reason for the status change
connectedNumber	string | undefined	WhatsApp phone number (when connected)

Status Values

Status	Description
created	Instance was just created
connecting	Instance is attempting to connect
pending_qr_code_scan	Waiting for QR code to be scanned
connected	Successfully connected to WhatsApp
qr_timeout	QR code scanning timed out
stopped	Instance was stopped
manually_stopped	Instance was manually stopped by user
error	Instance encountered an error
payment_pending	Payment required for this instance

Common Status Transitions

Successful Connection Flow

connecting → pending_qr_code_scan → connected

QR Code Timeout

connecting → pending_qr_code_scan → qr_timeout

User Logout

connected → connecting

With reason: "User logged out"

Restart Required

connected → connecting

With reason: "Restart required"

Example Payloads

Instance Connected

{
  "event": "instance-status",
  "instanceId": "abc123",
  "data": {
    "instanceId": "abc123",
    "status": "connected",
    "previousStatus": "pending_qr_code_scan",
    "timestamp": 1702500000000,
    "reason": "Connection established",
    "connectedNumber": "5511999999999"
  }
}

QR Code Generated

{
  "event": "instance-status",
  "instanceId": "abc123",
  "data": {
    "instanceId": "abc123",
    "status": "pending_qr_code_scan",
    "previousStatus": "connecting",
    "timestamp": 1702500000000,
    "reason": "QR code generated"
  }
}

User Logged Out

{
  "event": "instance-status",
  "instanceId": "abc123",
  "data": {
    "instanceId": "abc123",
    "status": "connecting",
    "previousStatus": "connected",
    "timestamp": 1702500000000,
    "reason": "User logged out"
  }
}

QR Code Timeout

{
  "event": "instance-status",
  "instanceId": "abc123",
  "data": {
    "instanceId": "abc123",
    "status": "qr_timeout",
    "previousStatus": "pending_qr_code_scan",
    "timestamp": 1702500000000,
    "reason": "QR code scan timeout"
  }
}

Handling in Code

Using Type Guards

import {
  WebhookEvent,
  isInstanceStatusEvent,
  InstanceStatus
} from '@zapyapi/sdk';

function handleWebhook(event: WebhookEvent) {
  if (isInstanceStatusEvent(event)) {
    const { status, previousStatus, reason, connectedNumber } = event.data;

    console.log(`Instance ${event.instanceId}: ${previousStatus} → ${status}`);

    switch (status) {
      case InstanceStatus.CONNECTED:
        console.log(`Connected as ${connectedNumber}`);
        // Instance is ready to send/receive messages
        break;

      case InstanceStatus.PENDING_QR_CODE_SCAN:
        console.log('Waiting for QR code scan...');
        // Show notification to user to scan QR code
        break;

      case InstanceStatus.QR_TIMEOUT:
        console.log('QR code expired, need to restart');
        // Trigger instance restart or notify user
        break;

      case InstanceStatus.CONNECTING:
        if (reason === 'User logged out') {
          console.log('User logged out from WhatsApp');
          // Handle logout - may need to re-authenticate
        }
        break;

      case InstanceStatus.ERROR:
        console.error('Instance error:', reason);
        // Handle error state
        break;
    }
  }
}

Monitoring Connection Health

import { isInstanceStatusEvent, InstanceStatus } from '@zapyapi/sdk';

// Track instance states
const instanceStates = new Map<string, string>();

function handleWebhook(event: WebhookEvent) {
  if (isInstanceStatusEvent(event)) {
    const { instanceId } = event;
    const { status, previousStatus, timestamp } = event.data;

    // Update state tracking
    instanceStates.set(instanceId, status);

    // Log state transition
    console.log({
      instanceId,
      transition: `${previousStatus} → ${status}`,
      timestamp: new Date(timestamp).toISOString(),
    });

    // Alert on disconnection
    if (
      previousStatus === InstanceStatus.CONNECTED &&
      status !== InstanceStatus.CONNECTED
    ) {
      sendAlert(`Instance ${instanceId} disconnected!`);
    }

    // Alert on successful connection
    if (status === InstanceStatus.CONNECTED) {
      sendNotification(`Instance ${instanceId} is now online`);
    }
  }
}

Use Cases

1. Connection Monitoring - Track when instances connect/disconnect
2. User Notifications - Alert users when QR code scanning is needed
3. Auto-Recovery - Trigger reconnection logic on disconnects
4. Dashboards - Display real-time instance status
5. Logging - Audit trail of connection state changes
6. Alerting - Send alerts when instances go offline