> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wachat.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Instance
> Create a new WhatsApp instance from an external application. The created instance is saved to your Wachat account and appears automatically in Settings > Instance. WhatsApp Baileys instances return a QR code in the same response.
Create a new WhatsApp instance from an external application using your Wachat API key.
The instance is automatically saved to your account and will appear in **Settings > Instance** inside the dashboard. For WhatsApp Baileys instances, the response also includes a QR code immediately, so you do not need to call the QR endpoint after creating the instance.
`instance.instanceName` is the display name shown in Wachat. Use `instance.apiInstanceName` for future API calls such as sending messages, checking state, logout, and delete.
## Displaying the QR Code
Use the `qrcode.base64` value as an image source in your application.
The Mintlify API playground shows the QR code value as JSON. It does not automatically render `qrcode.base64` as an image preview.
```html theme={null}
```
You can also use `qrcode.imageUrl` to render the QR code through an image endpoint:
```html theme={null}
```
For an auto-updating QR display that changes to a success message after the user scans it, use `qrcode.liveUrl`:
```html theme={null}
```
If the QR code expires, request a fresh QR code using `GET /instance/qr`.
## Return QR Image Directly
If you want the create request to return the QR code as an image instead of JSON, add `response=image` to the URL:
```bash theme={null}
curl -X POST "https://app.wachat.net/api/v1/instance/create?response=image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instanceName": "store-jakarta",
"number": "628123456789",
"integration": "WHATSAPP-BAILEYS"
}' \
--output qr.png
```
The instance display name is returned in `X-Instance-Name`. Use `X-Api-Instance-Name` for future API calls.
## OpenAPI
````yaml POST /instance/create
openapi: 3.0.3
info:
title: Wachat Enterprise API
description: >
Welcome to the official Wachat API reference. Wachat provides
developer-friendly, ultra-reliable infrastructure to scale your WhatsApp
communications programmatically.
Easily deploy automated messaging pipelines, orchestrate interactive
customer engagement patterns, verify phone numbers instantly, and control
containerized WhatsApp instances via a secure, production-grade REST
architecture.
version: 1.0.0
servers:
- url: https://app.wachat.net/api/v1
description: Live Production Gateway
security:
- bearerAuth: []
paths:
/instance/create:
post:
tags:
- Session Lifecycle Infrastructure
summary: Create WhatsApp Instance
description: >-
Create a new WhatsApp instance from an external application. The created
instance is saved to your Wachat account and appears automatically in
Settings > Instance. WhatsApp Baileys instances return a QR code in the
same response.
parameters:
- in: query
name: response
required: false
schema:
type: string
enum:
- json
- image
default: json
description: >-
Set to image to return the QR code directly as image/png instead of
JSON.
example: image
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- instanceName
properties:
instanceName:
type: string
description: >-
Friendly instance name. Wachat will add a unique prefix
before saving the final instance name.
example: jakarta_store
number:
type: string
description: Optional WhatsApp phone number with country code.
example: '628123456789'
integration:
type: string
description: Instance integration type.
enum:
- WHATSAPP-BAILEYS
- WHATSAPP-BUSINESS
default: WHATSAPP-BAILEYS
example: WHATSAPP-BAILEYS
rejectCalls:
type: boolean
description: Reject incoming WhatsApp calls automatically.
example: false
ignoreGroups:
type: boolean
description: Ignore group messages for this instance.
example: false
alwaysOnline:
type: boolean
description: Keep the instance online when possible.
example: true
readMessages:
type: boolean
description: Mark incoming messages as read.
example: false
readStatus:
type: boolean
description: Read status updates.
example: false
metaToken:
type: string
description: Required only for WHATSAPP-BUSINESS integrations.
metaBusinessId:
type: string
description: Required only for WHATSAPP-BUSINESS integrations.
metaPhoneNumberId:
type: string
description: Required only for WHATSAPP-BUSINESS integrations.
examples:
baileys:
summary: Create a WhatsApp Baileys instance
value:
instanceName: jakarta_store
number: '628123456789'
integration: WHATSAPP-BAILEYS
responses:
'201':
description: >-
Instance created successfully. For WhatsApp Baileys, the QR code is
returned immediately.
content:
image/png:
schema:
type: string
format: binary
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
instance:
type: object
properties:
id:
type: integer
example: 26
instanceName:
type: string
description: Display name shown in Wachat.
example: jakarta_store
displayName:
type: string
example: jakarta_store
apiInstanceName:
type: string
description: >-
Unique instance name used for future Wachat API
requests.
example: t1_mq9r2jov_jakarta_store
internalName:
type: string
description: Same value as apiInstanceName.
example: t1_mq9r2jov_jakarta_store
number:
type: string
example: '628123456789'
integration:
type: string
example: WHATSAPP-BAILEYS
qrcode:
type: object
nullable: true
description: QR code data returned for WhatsApp Baileys instances.
properties:
pairingCode:
type: string
nullable: true
example: PKRFWHWE
code:
type: string
nullable: true
base64:
type: string
nullable: true
description: >-
Base64 image data URI. Use this value as an image src
to display the QR code.
example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
imageUrl:
type: string
nullable: true
description: >-
URL that returns the QR code directly as an image. Add
apiKey as a query parameter when using it inside an
img tag.
example: >-
https://app.wachat.net/api/v1/instance/qr/image?instanceName=t1_mq9r2jov_jakarta_store
liveUrl:
type: string
nullable: true
description: >-
URL that returns a live HTML QR page. Add apiKey as a
query parameter when using it inside an iframe.
example: >-
https://app.wachat.net/api/v1/instance/qr/live?instanceName=t1_mq9r2jov_jakarta_store
count:
type: integer
nullable: true
example: 1
qrError:
type: string
nullable: true
description: >-
Present when the instance was created but the QR code
could not be fetched.
example: null
'400':
description: Invalid request payload.
'401':
description: Missing or invalid API key.
'403':
description: >-
Subscription, limit, or channel restriction prevented instance
creation.
'502':
description: >-
The Wachat API could not create the instance or return a valid
instance ID.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate your integration payloads by injecting your premium secure
Wachat Account API Private Secret Key inside standard Authorization
Bearer header vectors.
````