Skip to main content
POST
/
create-instance
Create Instance
curl --request POST \
  --url https://app.hypersender.com/api/whatsapp/v1/create-instance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone": "+201234567890",
  "name": "MyInstanceName",
  "webhook_url": "https://yourdomain.com/webhooks/whatsapp"
}
'
{
  "id": "c9a1dd76-5678-4f9d-9012-a5b78de100c3",
  "name": "MyInstanceName",
  "phone": "+201234567890",
  "service_type": "whatsapp",
  "status": "SCAN_QR_CODE",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAA...",
  "access_token": "234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1",
  "created_at": "2025-05-26T10:12:45"
}
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: 
<img src="data:image/png;base64,{qr_code}" alt="WhatsApp QR Code" />

​
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:

Example:

"iVBORw0KGgoAAAANSUhEUgAAA..."