Skip to main content
POST
https://api.enviaai.app
/
v1
/
instances
/
{instanceId}
/
connect
Connect Instance
curl --request POST \
  --url https://api.enviaai.app/v1/instances/{instanceId}/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "method": "<string>",
  "businessId": "<string>",
  "phoneNumberId": "<string>",
  "accessToken": "<string>"
}
'
{
  "success": true,
  "status": "qr_pending",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qrCodeExpiresAt": "2026-02-03T12:05:00.000Z"
}

​
Overview

Connect a WhatsApp instance to start sending and receiving messages. EnviaAI supports two connection methods:

Official API (Meta)

Connect via Meta’s official WhatsApp Business API. Recommended for production.

QR Code

Connect by scanning a QR code with WhatsApp. Quick setup for testing.

​
Connection Methods

The Official WhatsApp Business API provides:
  • Higher reliability - Direct connection to Meta’s infrastructure
  • Better deliverability - Messages are less likely to be blocked
  • Official support - Backed by Meta’s terms of service
  • Business verification - Verified business badge on your profile
const response = await client.instances.connect('inst_abc123', {
  method: 'official',
  businessId: 'your-meta-business-id',
  phoneNumberId: 'your-phone-number-id',
  accessToken: 'your-meta-access-token'
});

​
QR Code (Unofficial API)

Connect by scanning a QR code with your WhatsApp mobile app.
Important DisclaimerThe QR Code connection method uses an unofficial WhatsApp API. By using this method:
  • Your WhatsApp account may be banned without notice
  • We do not guarantee message delivery or account stability
  • EnviaAI is not responsible for any consequences to your account
  • This method is recommended only for testing and development
For production use, we strongly recommend the Official API.
// Request QR code
const response = await client.instances.connect('inst_abc123', {
  method: 'qrcode'
});

// Display QR code to user
if (response.qrCode) {
  console.log('Scan this QR code:', response.qrCode);
}

// Poll for connection status
const status = await client.instances.getStatus('inst_abc123');

​
Path Parameters

​
instanceId
string
required
The unique identifier of the instance to connect

​
Request Body

​
method
string
required
Connection method: official or qrcode
​
businessId
string
Meta Business ID (required for official method)
​
phoneNumberId
string
Meta Phone Number ID (required for official method)
​
accessToken
string
Meta Access Token (required for official method)

​
Response

​
success
boolean
Indicates if the connection was initiated successfully
​
status
string
Current status: connecting, qr_pending, or connected
​
qrCode
string
Base64 encoded QR code image (only for qrcode method)
​
qrCodeExpiresAt
string
ISO 8601 timestamp when the QR code expires
{
  "success": true,
  "status": "qr_pending",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qrCodeExpiresAt": "2026-02-03T12:05:00.000Z"
}

​
QR Code Flow

When using QR code connection, follow this flow:
1

Request QR Code

Call the connect endpoint with method: "qrcode"
2

Display QR Code

Show the returned QR code image to the user
3

User Scans

User opens WhatsApp > Settings > Linked Devices > Link a Device
4

Poll Status

Poll the Instance Status endpoint until status is connected
async function connectWithQRCode(instanceId) {
  // Step 1: Request QR code
  const connect = await client.instances.connect(instanceId, {
    method: 'qrcode'
  });

  // Step 2: Display QR code
  displayQRCode(connect.qrCode);

  // Step 3-4: Poll for connection
  while (true) {
    const status = await client.instances.getStatus(instanceId);

    if (status.data.status === 'connected') {
      console.log('Connected!', status.data.phone);
      return status.data;
    }

    if (status.data.status === 'qr_pending' && status.data.qrCode !== connect.qrCode) {
      // QR code refreshed, update display
      displayQRCode(status.data.qrCode);
    }

    await sleep(2000); // Wait 2 seconds before next poll
  }
}

​
Comparison: Official vs QR Code

FeatureOfficial APIQR Code
Setup complexityHigher (requires Meta Business verification)Lower (scan and go)
ReliabilityHighMedium
Risk of banNonePossible
Message templatesRequired for 24h+ conversationsNot required
Best forProductionDevelopment/Testing
CostMeta charges applyFree

​
Error Codes

CodeDescription
instance_not_foundThe instance ID does not exist
instance_already_connectedThe instance is already connected
invalid_methodInvalid connection method
invalid_credentialsInvalid Meta API credentials
meta_verification_requiredMeta Business verification required