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": "[email protected]",
      "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"

---

Check Numbers

Checks if phone numbers are registered on WhatsApp.

POST /api/instances/{instanceId}/check-numbers

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Request Body

{
  "numbers": ["5511999999999", "5521888888888"]
}

Field	Type	Required	Description
numbers	string[]	Yes	Array of phone numbers to check

Response

{
  "results": [
    {
      "number": "5511999999999",
      "exists": true,
      "jid": "[email protected]"
    },
    {
      "number": "5521888888888",
      "exists": false
    }
  ]
}

Field	Type	Description
results	array	Array of check results
results[].number	string	The phone number that was checked
results[].exists	boolean	Whether the number is registered on WhatsApp
results[].jid	string	WhatsApp JID (only if exists is true)

Example

curl -X POST "https://api.zapyapi.com/api/instances/my-instance/check-numbers" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["5511999999999", "5521888888888"]
  }'

---

Send Presence

Sends a presence update (typing indicator, online status, etc.) to a contact.

POST /api/instances/{instanceId}/presence

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier

Request Body

{
  "to": "5511999999999",
  "presence": "composing"
}

Field	Type	Required	Description
to	string	Yes	Recipient phone number or chat ID
presence	string	Yes	Presence type (see below)

Presence Types

Value	Description
composing	Show typing indicator
recording	Show recording audio indicator
paused	Stop typing indicator
available	Show as online
unavailable	Show as offline

Response

Returns 204 No Content on success.

Example

# Show typing indicator
curl -X POST "https://api.zapyapi.com/api/instances/my-instance/presence" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "presence": "composing"
  }'

# Show recording indicator
curl -X POST "https://api.zapyapi.com/api/instances/my-instance/presence" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "presence": "recording"
  }'

---

Get Profile Picture

Gets the profile picture URL for a contact.

GET /api/instances/{instanceId}/contacts/{phone}/profile-picture

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier
phone	string	Yes	Phone number or WhatsApp JID

Response

{
  "url": "https://example.com/profile-picture.jpg"
}

Field	Type	Description
url	string | null	Profile picture URL (null if not available)

Example

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

---

Block Contact

Blocks a contact on WhatsApp.

POST /api/instances/{instanceId}/contacts/{phone}/block

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier
phone	string	Yes	Phone number or WhatsApp JID to block

Response

Returns 204 No Content on success.

Example

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

---

Unblock Contact

Unblocks a previously blocked contact.

DELETE /api/instances/{instanceId}/contacts/{phone}/block

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier
phone	string	Yes	Phone number or WhatsApp JID to unblock

Response

Returns 204 No Content on success.

Example

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

---

Get Group Metadata

Gets metadata for a WhatsApp group, including participants.

GET /api/instances/{instanceId}/groups/{groupId}

Path Parameters

Parameter	Type	Required	Description
instanceId	string	Yes	WhatsApp instance identifier
groupId	string	Yes	Group JID (e.g., [email protected])

Response

{
  "id": "[email protected]",
  "subject": "My Group Name",
  "description": "Group description here",
  "owner": "[email protected]",
  "creation": 1672531200,
  "participants": [
    {
      "id": "[email protected]",
      "admin": "superadmin"
    },
    {
      "id": "[email protected]",
      "admin": "admin"
    },
    {
      "id": "[email protected]",
      "admin": null
    }
  ]
}

Field	Type	Description
id	string	Group JID
subject	string	Group name
description	string | null	Group description
owner	string | null	Group owner JID
creation	number	Creation timestamp (Unix seconds)
participants	array	List of group participants
participants[].id	string	Participant JID
participants[].admin	string | null	Admin status: superadmin, admin, or null

Example

curl -X GET "https://api.zapyapi.com/api/instances/my-instance/groups/[email protected]" \
  -H "x-api-key: YOUR_API_KEY"