Skip to main content
POST
Create Instance
Create a new WhatsApp instance associated with a phone number and a user-defined name. Upon creation, you’ll receive a QR code to scan with your WhatsApp mobile app.

Rate Limit

This endpoint is limited to 5 requests per minute to prevent abuse.

Request Body

  • phone (required) - Phone number in E.164 format (e.g., +201234567890)
  • name (required) - Instance name (max 50 characters, must be unique per user per service)
  • webhook_url (optional) - HTTPS webhook URL to receive WhatsApp events

Response

Upon successful creation, you’ll receive:
  • Instance details (id, name, phone, service_type, status)
  • qr_code - Base64-encoded PNG QR code for WhatsApp authentication
  • access_token - Bearer token for authenticating API requests
  • created_at - Creation timestamp

QR Code Display

The QR code is returned as a base64-encoded PNG without the data URI prefix. To display it in HTML:

Next Steps

After creating the instance:
  1. Display the QR code to the user
  2. Open WhatsApp on the mobile device
  3. Go to Settings > Linked Devices
  4. Scan the QR code
  5. Wait for the instance status to change to WORKING
The QR code expires after a certain time. If it expires, use the Request New QR Code endpoint to generate a fresh one.
Set up a webhook URL to receive real-time events from your WhatsApp instance, including incoming messages and connection status updates.

Validation Errors

Common validation errors (422 status):
  • Missing phone or name field
  • Invalid phone number format
  • Instance name already exists
  • Invalid webhook URL (must be HTTPS)
  • Name exceeds 50 characters

Authorizations

Authorization
string
header
required

Bearer token authentication. Example: Bearer 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1

Headers

Accept
string

application/json

Example:

"application/json"

Content-Type
string

application/json

Example:

"application/json"

Body

application/json
phone
string
required

E.164 format phone number (e.g. +201234567890)

Example:

"+201234567890"

name
string
required

Instance name (max 50 characters, must be unique per user per service)

Maximum string length: 50
Example:

"MyInstanceName"

webhook_url
string<uri>

Optional webhook URL (must be a valid https URL)

Example:

"https://yourdomain.com/webhooks/whatsapp"

Response

Instance created successfully

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"

qr_code
string

Base64-encoded PNG QR code (without data:image/png;base64, prefix). You must prepend it manually when displaying: [Image blocked: No description]

Example:

"iVBORw0KGgoAAAANSUhEUgAAA..."