Skip to main content
GET
/
instances
List Instances
curl --request GET \
  --url https://app.hypersender.com/api/whatsapp/v1/instances \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": "fa3d01c4-1234-4c0d-a12f-df319b612f8c",
    "name": "MyInstanceName",
    "phone": "+201234567890",
    "service_type": "whatsapp",
    "status": "WORKING",
    "access_token": "234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1",
    "created_at": "2025-05-26T10:12:45"
  },
  {
    "id": "c9a1dd76-5678-4f9d-9012-a5b78de100c3",
    "name": "SecondInstance",
    "phone": "+201234567891",
    "service_type": "whatsapp",
    "status": "SCAN_QR_CODE",
    "access_token": null,
    "created_at": "2025-05-25T15:30:22"
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt

Use this file to discover all available pages before exploring further.

List all WhatsApp instances associated with your authenticated account. Use filters to narrow down results by UUID, name, phone number, or status.

​
Filtering Options

You can filter the list of instances using the following query parameters:
  • filter[uuid] - Filter by instance UUID (exact match)
  • filter[name] - Filter by instance name (partial match)
  • filter[phone] - Filter by phone number (exact match)
  • filter[status] - Filter by instance status

​
Response Fields

Each instance in the response includes:
  • id - Instance UUID
  • name - Instance name
  • phone - Phone number in E.164 format
  • service_type - Service type (whatsapp)
  • status - Current instance status
  • access_token - Access token for the instance (null if not yet connected)
  • created_at - Creation timestamp

​
Example Use Cases

  • Display all instances in your application dashboard
  • Filter instances by status to show only active ones
  • Search for a specific instance by name or phone number
  • Monitor all instances created at a specific time
Use the filter[status] parameter with value WORKING to get only active and ready instances.

​
Instance Status Values

  • STOPPED: Instance is stopped
  • STARTING: Instance is starting up
  • WORKING: Instance is running and ready
  • SCAN_QR_CODE: Waiting for QR code scan
  • FAILED: Instance failed to start
  • PENDING: Awaiting server assignment

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Example: Bearer 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1

Headers

​
Accept
string

application/json

Example:

"application/json"

Query Parameters

​
filter[uuid]
string

Filter by instance UUID

​
filter[name]
string

Filter by instance name (partial match)

​
filter[phone]
string

Filter by phone number

​
filter[status]
enum<string>

Filter by instance status

Available options:
STOPPED,
STARTING,
WORKING,
SCAN_QR_CODE,
FAILED,
PENDING

Response

200 - application/json

Successful response

​
id
string

Instance UUID

Example:

"fa3d01c4-1234-4c0d-a12f-df319b612f8c"

​
name
string

Instance name

Example:

"MyInstanceName"

​
phone
string

Phone number in E.164 format

Example:

"+201234567890"

​
service_type
string

Service type

Example:

"whatsapp"

​
status
enum<string>

Instance status

Available options:
STOPPED,
STARTING,
WORKING,
SCAN_QR_CODE,
FAILED,
PENDING
Example:

"WORKING"

​
access_token
string | null

Access token for the instance

Example:

"234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1"

​
created_at
string

Creation timestamp

Example:

"2025-05-26T10:12:45"