Instances API

Endpoints for managing your WhatsApp instances, including listing, connecting, and configuring webhooks.

Creating New Instances

To create new instances programmatically, you need a partner account. See the Partner API for details.

List Instances

Returns a paginated list of all your WhatsApp instances.

GET /api/instances

Query Parameters

Parameter	Type	Required	Default	Description
page	number	No	1	Page number (minimum: 1)
limit	number	No	100	Items per page (1-100)

Response

{
  "data": [
    {
      "instanceId": "instance-123",
      "name": "My WhatsApp Instance",
      "status": "connected",
      "whatsappJid": "5511999999999@c.us",
      "whatsappLid": "5511999999999@lid",
      "whatsappId": "5511999999999",
      "whatsappName": "My Company",
      "whatsappProfilePicUrl": "https://example.com/profile-pic.jpg",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "isFirstPage": true,
  "isLastPage": true,
  "currentPage": 1,
  "previousPage": null,
  "nextPage": null,
  "pageCount": 1,
  "totalCount": 1
}

Instance Status Values

Status	Description
created	Instance created, not yet started
connecting	Instance is connecting to WhatsApp
pending_qr_code_scan	Waiting for QR code scan
connected	Instance is connected and ready
stopped	Instance was stopped
manually_stopped	Instance was manually stopped by user
error	Instance encountered an error
qr_timeout	QR code scan timed out
payment_pending	Payment required to continue

Example

curl -X GET "https://api.zapyapi.com/api/instances?page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

---

Get QR Code

Gets the QR code for connecting a WhatsApp instance. The user must scan this QR code with their WhatsApp mobile app.

GET /api/instances/{instanceId}/qr

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Response

{
  "instanceId": "my-whatsapp-instance",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expiresAt": 1672531200000,
  "attempt": 1
}

Field	Type	Description
instanceId	string	Instance identifier
qrCode	string	QR code as base64 image or raw string
expiresAt	number	Expiration timestamp (milliseconds)
attempt	number	QR code generation attempt number

Example

curl -X GET "https://api.zapyapi.com/api/instances/my-instance/qr" \
  -H "x-api-key: YOUR_API_KEY"

---

Restart Instance

Restarts a WhatsApp instance. Use this to reconnect after disconnection or errors.

POST /api/instances/{instanceId}/restart

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Response

{}

Returns an empty object on success.

Example

curl -X POST "https://api.zapyapi.com/api/instances/my-instance/restart" \
  -H "x-api-key: YOUR_API_KEY"

---

Logout Instance

Logs out a WhatsApp instance. This disconnects the WhatsApp session and requires re-scanning the QR code to reconnect.

POST /api/instances/{instanceId}/logout

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Response

{}

Returns an empty object on success.

Example

curl -X POST "https://api.zapyapi.com/api/instances/my-instance/logout" \
  -H "x-api-key: YOUR_API_KEY"

---

Webhook Configuration

Create or Update Webhook

Creates or updates the webhook configuration for an instance. Webhooks allow you to receive real-time events from your WhatsApp instance.

POST /api/instances/{instanceId}/webhook-config

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Request Body

{
  "webhookUrl": "https://api.example.com/webhooks/whatsapp",
  "secret": "your-secret-key",
  "isActive": true
}

Field	Type	Required	Default	Description
webhookUrl	string	Yes	-	URL to receive webhook events
secret	string	No	-	Secret key for signature verification
isActive	boolean	Yes	true	Whether the webhook is active

Response

{
  "id": "webhook-config-uuid",
  "instanceId": "my-instance",
  "webhookUrl": "https://api.example.com/webhooks/whatsapp",
  "secret": "your-secret-key",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Example

curl -X POST "https://api.zapyapi.com/api/instances/my-instance/webhook-config" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.example.com/webhooks/whatsapp",
    "secret": "my-secret-key",
    "isActive": true
  }'

---

Get Webhook Configuration

Gets the current webhook configuration for an instance.

GET /api/instances/{instanceId}/webhook-config

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Response

{
  "id": "webhook-config-uuid",
  "instanceId": "my-instance",
  "webhookUrl": "https://api.example.com/webhooks/whatsapp",
  "secret": "your-secret-key",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Example

curl -X GET "https://api.zapyapi.com/api/instances/my-instance/webhook-config" \
  -H "x-api-key: YOUR_API_KEY"

---

Delete Webhook Configuration

Deletes the webhook configuration for an instance. The instance will stop sending webhook events.

DELETE /api/instances/{instanceId}/webhook-config

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Response

{}

Returns an empty object on success.

Example

curl -X DELETE "https://api.zapyapi.com/api/instances/my-instance/webhook-config" \
  -H "x-api-key: YOUR_API_KEY"