Skip to main content

​
GET /instance/connect/:instanceName

Connect a WhatsApp instance to the WhatsApp servers. For Baileys integration, this generates a QR code that you scan with WhatsApp mobile app. For already connected instances, this returns the current connection state.

​
Authentication

This endpoint requires authentication via the apikey header. 
apikey: YOUR_API_KEY

​
Path Parameters

​
instanceName
string
required
Name of the instance you want to connect. This is the instanceName you specified when creating the instance.

​
Query Parameters

​
number
string
WhatsApp phone number to connect (optional). Used for pairing with phone number instead of QR code.

​
Response

The response varies based on the current connection state:

​
Already Connected (state: open)

​
instance
object
Instance information
​
instanceName
string
Name of the instance
​
state
string
Current connection state (open)

​
Connecting (state: connecting)

​
code
string
Raw QR code string
​
base64
string
QR code as base64-encoded image. Display this in an <img> tag or QR code reader.
​
pairingCode
string
Pairing code for phone number authentication (when using number parameter)

​
Disconnected (state: close)

After initiating connection, returns QR code:
​
code
string
Raw QR code string
​
base64
string
QR code as base64-encoded image
​
pairingCode
string
Pairing code (if number parameter provided)

​
Examples

curl -X GET "https://api.example.com/instance/connect/my-instance" \
  -H "apikey: YOUR_API_KEY"

​
Response Examples

Already Connected
{
  "instance": {
    "instanceName": "my-instance",
    "state": "open"
  }
}
QR Code Response
{
  "code": "2@v1j2k3l4m5n6o7p8q9r0s1t2u3v4w5x6y7z8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o3p4...",
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAADsUlEQVR42uyYTY7jMAyE..."
}
Pairing Code Response
{
  "pairingCode": "ABCD-EFGH",
  "code": "2@...",
  "base64": "data:image/png;base64,..."
}
Error - Instance Not Found
{
  "error": true,
  "message": "The \"my-instance\" instance does not exist"
}

​
Connection Flow

  1. Call the connect endpoint - Initiates connection and receives QR code
  2. Display QR code to user - Show the base64 image for scanning
  3. User scans QR code - Open WhatsApp > Settings > Linked Devices > Link a Device
  4. Monitor connection status - Poll the /instance/connectionState/:instanceName endpoint
  5. Connection confirmed - Status changes to open
QR Code Expiration: QR codes expire after approximately 60 seconds. If the user doesn’t scan in time, call the endpoint again to get a fresh QR code.

​
Connection States

StateDescriptionAction Required
openInstance is connectedNone - ready to use
connectingConnection in progressDisplay QR code
closeInstance is disconnectedCall connect endpoint

​
Integration Types

This endpoint behaves differently based on your integration:

​
WHATSAPP-BAILEYS

  • Generates QR code for WhatsApp Web authentication
  • Supports pairing code with phone number
  • Requires QR code scan or pairing code entry

​
WHATSAPP-BUSINESS

  • Does not require QR code
  • Connection managed through Meta Business API
  • Returns connection state only

​
Error Handling

The API returns standard HTTP status codes:
  • 200 - Success (returns QR code or connection state)
  • 400 - Bad request (instance doesn’t exist)
  • 401 - Unauthorized (invalid API key)
  • 500 - Internal server error
Common error scenarios:
  1. Instance doesn’t exist: Verify the instanceName is correct
  2. Already connecting: Wait for current connection attempt to complete or timeout
  3. Authentication failed: Check that your API key is valid
Do not attempt to connect an instance that is already in “connecting” state. Wait for the current attempt to complete or timeout before retrying.

​
Best Practices

  1. Implement timeout logic: If QR code isn’t scanned within 60 seconds, request a new one
  2. Poll connection state: Check connection status every 3-5 seconds during QR code display
  3. Handle reconnection: If instance disconnects, automatically call connect endpoint
  4. Store connection state: Cache the connection state to minimize API calls
  5. User experience: Show a clear countdown timer for QR code expiration

​
Webhook Integration

Instead of polling, you can configure webhooks to receive connection updates:
CONNECTION_UPDATE Event
{
  "event": "CONNECTION_UPDATE",
  "instance": "my-instance",
  "data": {
    "state": "open",
    "statusReason": 200
  }
}
Subscribe to the CONNECTION_UPDATE event when creating your instance to receive real-time connection notifications.

Build docs developers (and LLMs) love

Get started for freeTalk to us