> ## 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.
# Create Instance
> Create a new WhatsApp instance with a phone number, name, and optional webhook URL for receiving events.
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:
```html theme={null}
```
## 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](/api-reference/enterprise/instance-management/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
## OpenAPI
````yaml v2/api-reference/enterprise/enterprise-collection.json POST /create-instance
openapi: 3.1.0
info:
version: v1.0
title: Hypersender Enterprise API Docs
description: >
The Hypersender Enterprise API provides powerful management capabilities for
WhatsApp instances.
In this Docs you'll learn how to use and integrate Hypersender Enterprise
API into your existing system/service or application using simple API
endpoints.
**What you can Do?**
- Check instance health status
- List all instances with filtering
- Create new WhatsApp instances
- Request new QR codes for authentication
- Restart instances
## Servers (Endpoints)
- Production (activated):
[https://app.hypersender.com/api/whatsapp/v2](https://app.hypersender.com/api/whatsapp/v2)
servers:
- url: https://app.hypersender.com/api/whatsapp/v2
description: Production
security:
- Authorization: []
paths:
/create-instance:
post:
tags:
- Instance Management
summary: Create Instance
description: >-
Creates a new WhatsApp instance associated with a phone number and a
user-defined name. This endpoint is limited to 5 requests per minute.
parameters:
- name: Accept
in: header
description: application/json
schema:
type: string
example: application/json
- name: Content-Type
in: header
description: application/json
schema:
type: string
example: application/json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInstanceRequest'
example:
phone: '+201234567890'
name: MyInstanceName
webhook_url: https://yourdomain.com/webhooks/whatsapp
responses:
'201':
description: Instance created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceWithQRResponse'
example:
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'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests. Please try again later.
security:
- Authorization: []
components:
schemas:
CreateInstanceRequest:
type: object
properties:
phone:
type: string
description: E.164 format phone number (e.g. +201234567890)
example: '+201234567890'
name:
type: string
description: >-
Instance name (max 50 characters, must be unique per user per
service)
example: MyInstanceName
maxLength: 50
webhook_url:
type: string
description: Optional webhook URL (must be a valid https URL)
example: https://yourdomain.com/webhooks/whatsapp
format: uri
required:
- phone
- name
InstanceWithQRResponse:
allOf:
- $ref: '#/components/schemas/InstanceResponse'
- type: object
properties:
qr_code:
type: string
description: >-
Base64-encoded PNG QR code (without data:image/png;base64,
prefix). You must prepend it manually when displaying: 
example: iVBORw0KGgoAAAANSUhEUgAAA...
ValidationError:
type: object
title: ValidationError
properties:
message:
type: string
errors:
type: object
description: Invalid or missing fields will be shown here
statusCode:
type: integer
example: 422
example:
message: The given data was invalid.
errors:
phone:
- The phone field is required.
name:
- The name field is required.
statusCode: 422
required:
- errors
- statusCode
InstanceResponse:
type: object
properties:
id:
type: string
description: Instance UUID
example: fa3d01c4-1234-4c0d-a12f-df319b612f8c
name:
type: string
description: Instance name
example: MyInstanceName
phone:
type: string
description: Phone number in E.164 format
example: '+201234567890'
service_type:
type: string
description: Service type
example: whatsapp
status:
type: string
enum:
- STOPPED
- STARTING
- WORKING
- SCAN_QR_CODE
- FAILED
- PENDING
description: Instance status
example: WORKING
access_token:
type:
- string
- 'null'
description: Access token for the instance
example: 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1
created_at:
type: string
description: Creation timestamp
example: '2025-05-26T10:12:45'
securitySchemes:
Authorization:
type: http
scheme: bearer
description: >-
Bearer token authentication. Example: `Bearer
234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1`
````