Skip to main content
GET
https://api.enviaai.app
/
v1
/
instances
List Instances
curl --request GET \
  --url https://api.enviaai.app/v1/instances \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": [
    {
      "id": "inst_abc123",
      "name": "Sales WhatsApp",
      "phone": "5511999999999",
      "status": "connected",
      "profileName": "Sales Team",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "createdAt": "2026-01-01T10:00:00.000Z",
      "lastSeenAt": "2026-02-03T12:00:00.000Z",
      "webhookUrl": "https://myapp.com/webhooks/whatsapp",
      "settings": {
        "autoRead": false,
        "autoTyping": true
      }
    },
    {
      "id": "inst_def456",
      "name": "Support WhatsApp",
      "phone": "5521988888888",
      "status": "connected",
      "profileName": "Support Team",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "createdAt": "2026-01-15T14:30:00.000Z",
      "lastSeenAt": "2026-02-03T11:45:00.000Z",
      "webhookUrl": "https://myapp.com/webhooks/whatsapp",
      "settings": {
        "autoRead": true,
        "autoTyping": true
      }
    },
    {
      "id": "inst_ghi789",
      "name": "Marketing WhatsApp",
      "phone": null,
      "status": "disconnected",
      "profileName": null,
      "profilePicUrl": null,
      "createdAt": "2026-02-01T09:00:00.000Z",
      "lastSeenAt": "2026-02-02T18:30:00.000Z",
      "webhookUrl": null,
      "settings": {
        "autoRead": false,
        "autoTyping": false
      }
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Overview

Get a list of all WhatsApp instances associated with your account. Returns instance details including connection status, phone number, and configuration.

Query Parameters

status
string
Filter by status: connected, disconnected, connecting, or all (default)
limit
number
default:"50"
Maximum number of instances to return (1-100)
offset
number
default:"0"
Number of instances to skip for pagination

Response

success
boolean
Indicates if the request was successful
data
array
Array of instance objects
data[].id
string
Unique identifier for the instance
data[].name
string
Display name of the instance
data[].phone
string
Phone number connected to the instance (if connected)
data[].status
string
Current status: connected, disconnected, or connecting
data[].profileName
string
WhatsApp profile name
data[].profilePicUrl
string
URL of the WhatsApp profile picture
data[].createdAt
string
ISO 8601 timestamp of instance creation
data[].lastSeenAt
string
ISO 8601 timestamp of last activity
data[].webhookUrl
string
Configured webhook URL for this instance
pagination
object
Pagination metadata

Examples

List All Instances

const instances = await client.instances.list();

instances.data.forEach(instance => {
  console.log(`${instance.name}: ${instance.status}`);
});
{
  "success": true,
  "data": [
    {
      "id": "inst_abc123",
      "name": "Sales WhatsApp",
      "phone": "5511999999999",
      "status": "connected",
      "profileName": "Sales Team",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "createdAt": "2026-01-01T10:00:00.000Z",
      "lastSeenAt": "2026-02-03T12:00:00.000Z",
      "webhookUrl": "https://myapp.com/webhooks/whatsapp",
      "settings": {
        "autoRead": false,
        "autoTyping": true
      }
    },
    {
      "id": "inst_def456",
      "name": "Support WhatsApp",
      "phone": "5521988888888",
      "status": "connected",
      "profileName": "Support Team",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
      "createdAt": "2026-01-15T14:30:00.000Z",
      "lastSeenAt": "2026-02-03T11:45:00.000Z",
      "webhookUrl": "https://myapp.com/webhooks/whatsapp",
      "settings": {
        "autoRead": true,
        "autoTyping": true
      }
    },
    {
      "id": "inst_ghi789",
      "name": "Marketing WhatsApp",
      "phone": null,
      "status": "disconnected",
      "profileName": null,
      "profilePicUrl": null,
      "createdAt": "2026-02-01T09:00:00.000Z",
      "lastSeenAt": "2026-02-02T18:30:00.000Z",
      "webhookUrl": null,
      "settings": {
        "autoRead": false,
        "autoTyping": false
      }
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Filter Connected Instances

const connectedInstances = await client.instances.list({
  status: 'connected'
});

console.log(`${connectedInstances.data.length} instances are online`);

Get Instance by ID

While this endpoint lists all instances, you can get a specific instance using:
const instance = await client.instances.get('inst_abc123');
console.log(instance);

Instance Settings

Each instance can have the following settings:
SettingTypeDescription
autoReadbooleanAutomatically mark incoming messages as read
autoTypingbooleanShow typing indicator before sending messages
webhookUrlstringURL to receive webhook events for this instance
webhookEventsarrayList of events to send to the webhook

Status Values

StatusDescription
connectedInstance is online and ready to send/receive messages
disconnectedInstance is offline and needs to be reconnected
connectingInstance is in the process of connecting

Error Codes

CodeDescription
invalid_parametersInvalid query parameters
rate_limit_exceededRate limit exceeded