Skip to main content
GET
https://api.enviaai.app
/
v1
/
instances
/
{instanceId}
/
status
Instance Status
curl --request GET \
  --url https://api.enviaai.app/v1/instances/{instanceId}/status \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": {
    "id": "inst_abc123",
    "name": "Sales WhatsApp",
    "status": "connected",
    "phone": "5511999999999",
    "profileName": "Sales Team",
    "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
    "qrCode": null,
    "qrCodeExpiresAt": null,
    "lastSeenAt": "2026-02-03T12:00:00.000Z",
    "connectedAt": "2026-02-01T08:30:00.000Z",
    "stats": {
      "messagesSent": 156,
      "messagesReceived": 243,
      "activeChats": 89,
      "unreadMessages": 12
    },
    "health": {
      "uptime": 172800,
      "latency": 45,
      "messageDeliveryRate": 0.98
    }
  }
}

​
Overview

Retrieve detailed status information for a specific WhatsApp instance, including connection state, QR code (if disconnected), and real-time statistics.

​
Path Parameters

​
instanceId
string
required
The unique identifier of the instance

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Instance status details
​
data.id
string
Instance unique identifier
​
data.name
string
Instance display name
​
data.status
string
Current connection status: connected, disconnected, connecting, or qr_pending
​
data.phone
string
Connected phone number (null if disconnected)
​
data.profileName
string
WhatsApp profile name
​
data.profilePicUrl
string
Profile picture URL
​
data.qrCode
string
Base64 encoded QR code image (only when status is qr_pending)
​
data.qrCodeExpiresAt
string
ISO 8601 timestamp when the QR code expires
​
data.lastSeenAt
string
Timestamp of last activity
​
data.connectedAt
string
Timestamp of when the instance connected
​
data.stats
object
Real-time statistics for the instance
​
data.stats.messagesSent
number
Total messages sent today
​
data.stats.messagesReceived
number
Total messages received today
​
data.stats.activeChats
number
Number of active chats
​
data.stats.unreadMessages
number
Total unread messages
​
data.health
object
Health metrics for the connection
​
data.health.uptime
number
Uptime in seconds since last connection
​
data.health.latency
number
Current latency to WhatsApp servers (ms)
​
data.health.messageDeliveryRate
number
Message delivery success rate (0-1)

​
Examples

​
Get Instance Status

const status = await client.instances.getStatus('inst_abc123');

console.log(`Status: ${status.data.status}`);
console.log(`Phone: ${status.data.phone}`);

if (status.data.status === 'qr_pending') {
  // Display QR code to user
  console.log('QR Code:', status.data.qrCode);
}

{
  "success": true,
  "data": {
    "id": "inst_abc123",
    "name": "Sales WhatsApp",
    "status": "connected",
    "phone": "5511999999999",
    "profileName": "Sales Team",
    "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
    "qrCode": null,
    "qrCodeExpiresAt": null,
    "lastSeenAt": "2026-02-03T12:00:00.000Z",
    "connectedAt": "2026-02-01T08:30:00.000Z",
    "stats": {
      "messagesSent": 156,
      "messagesReceived": 243,
      "activeChats": 89,
      "unreadMessages": 12
    },
    "health": {
      "uptime": 172800,
      "latency": 45,
      "messageDeliveryRate": 0.98
    }
  }
}

​
Poll for QR Code Status

When connecting a new instance, poll the status endpoint to display the QR code: 
async function waitForConnection(instanceId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const status = await client.instances.getStatus(instanceId);

    switch (status.data.status) {
      case 'connected':
        console.log('Instance connected!');
        return status.data;

      case 'qr_pending':
        console.log('Scan QR code:', status.data.qrCode);
        break;

      case 'connecting':
        console.log('Connecting...');
        break;
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  throw new Error('Connection timeout');
}

const instance = await waitForConnection('inst_ghi789');

​
Connect a Disconnected Instance

// Request a new QR code
const connectResponse = await client.instances.connect('inst_ghi789');

// Poll for status and display QR code
const status = await client.instances.getStatus('inst_ghi789');
if (status.data.qrCode) {
  // Display QR code to user
  displayQRCode(status.data.qrCode);
}

​
Status Values

StatusDescriptionQR Code Available
connectedInstance is online and operationalNo
disconnectedInstance is offlineNo
connectingInstance is establishing connectionNo
qr_pendingWaiting for QR code scanYes

​
Health Metrics

MetricDescriptionGood Value
uptimeSeconds since last connection> 86400 (24h)
latencyResponse time to WhatsApp (ms)< 100ms
messageDeliveryRateSuccess rate (0-1)> 0.95

​
Error Codes

CodeDescription
instance_not_foundThe instance ID does not exist
rate_limit_exceededRate limit exceeded

​
WebSocket Updates

For real-time status updates, connect to our WebSocket endpoint: 
const ws = new WebSocket('wss://api.enviaai.app/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'instance:inst_abc123:status',
    apiKey: 'your-api-key'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Status update:', data);
};