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