Create Instance

Create a new WhatsApp instance with customizable settings and integrations

POST /instance/create

Create a new WhatsApp instance with support for multiple integrations including Baileys, WhatsApp Business API, webhooks, event systems, and chatbot platforms.

Authentication

This endpoint requires authentication via the apikey header.

apikey: YOUR_API_KEY

Request Body

instanceName · string · required

Unique name for your instance. This identifier is used across all API calls.

token · string

Custom authentication token for this instance. If not provided, a token will be auto-generated.

number · string

WhatsApp number in international format (e.g., 5511999999999). Required for WhatsApp Business API integration.

businessId · string

WhatsApp Business Account ID. Required for WhatsApp Business API integration.

qrcode · boolean · default: "false"

Generate QR code immediately after instance creation for Baileys integration.

integration · string

WhatsApp integration type. Available options:

• WHATSAPP-BAILEYS - WhatsApp Web integration
• WHATSAPP-BUSINESS - Official WhatsApp Business API

Settings

rejectCall · boolean · default: "false"

Automatically reject incoming calls.

msgCall · string

Message to send when rejecting a call. Requires rejectCall to be enabled.

groupsIgnore · boolean · default: "false"

Ignore messages from groups.

alwaysOnline · boolean · default: "false"

Keep WhatsApp status always online.

readMessages · boolean · default: "false"

Automatically mark messages as read.

readStatus · boolean · default: "false"

Automatically read status updates.

syncFullHistory · boolean · default: "false"

Sync full message history when connecting.

Webhook Configuration

webhookUrl · string

URL to receive webhook events.

webhookByEvents · boolean · default: "false"

Send webhooks grouped by event type.

webhookBase64 · boolean · default: "true"

Include media files as base64 in webhook payload.

webhookEvents · array

Array of event types to receive. Available events:

• QRCODE_UPDATED
• MESSAGES_UPSERT
• MESSAGES_UPDATE
• MESSAGES_DELETE
• SEND_MESSAGE
• CONNECTION_UPDATE
• CALL And more…

Proxy Configuration

proxyHost · string

Proxy server hostname or IP address.

proxyPort · string

Proxy server port.

proxyProtocol · string

Proxy protocol: http or https.

proxyUsername · string

Proxy authentication username (optional).

proxyPassword · string

Proxy authentication password (optional).

Event System Integration

rabbitmqEnabled · boolean · default: "false"

Enable RabbitMQ event publishing.

rabbitmqEvents · array

Array of events to publish to RabbitMQ.

sqsEnabled · boolean · default: "false"

Enable AWS SQS event publishing.

sqsEvents · array

Array of events to publish to SQS.

natsEnabled · boolean · default: "false"

Enable NATS event publishing.

natsEvents · array

Array of events to publish to NATS.

Chatwoot Integration

chatwootAccountId · string

Chatwoot account ID.

chatwootToken · string

Chatwoot access token.

chatwootUrl · string

Chatwoot instance URL.

chatwootSignMsg · boolean

Sign messages with agent name in Chatwoot.

chatwootReopenConversation · boolean

Automatically reopen conversations.

chatwootConversationPending · boolean

Set new conversations as pending.

chatwootImportContacts · boolean · default: "true"

Import contacts to Chatwoot.

chatwootImportMessages · boolean · default: "true"

Import message history to Chatwoot.

chatwootDaysLimitImportMessages · number · default: "60"

Number of days to import messages from history.

chatwootMergeBrazilContacts · boolean · default: "false"

Merge Brazilian contacts (removes 9th digit).

chatwootNameInbox · string

Custom inbox name in Chatwoot. Defaults to instance name.

Response

instance · object

Instance information

instanceName · string

Name of the created instance

instanceId · string

Unique instance identifier (UUID)

integration · string

Integration type used

status · string

Connection status: open, close, connecting

webhookWaBusiness · string

Webhook URL for WhatsApp Business (if applicable)

accessTokenWaBusiness · string

Access token for WhatsApp Business webhook (if applicable)

hash · string

Authentication token for this instance. Use this in the apikey header for instance-specific operations.

webhook · object

Webhook configuration

webhookUrl · string

Configured webhook URL

webhookByEvents · boolean

Events grouped by type

webhookBase64 · boolean

Media included as base64

websocket · object

WebSocket configuration

enabled · boolean

WebSocket events enabled

rabbitmq · object

RabbitMQ configuration

enabled · boolean

RabbitMQ events enabled

sqs · object

SQS configuration

enabled · boolean

SQS events enabled

nats · object

NATS configuration

enabled · boolean

NATS events enabled

settings · object

Instance settings

rejectCall · boolean

Reject calls setting

msgCall · string

Call rejection message

groupsIgnore · boolean

Ignore groups setting

alwaysOnline · boolean

Always online setting

readMessages · boolean

Auto-read messages setting

readStatus · boolean

Auto-read status setting

qrcode · object

QR code for Baileys connection (if qrcode: true and integration is Baileys)

code · string

QR code string

base64 · string

QR code as base64 image

chatwoot · object

Chatwoot configuration (if Chatwoot credentials provided)

enabled · boolean

Chatwoot integration enabled

accountId · string

Chatwoot account ID

webhookUrl · string

Chatwoot webhook URL

Examples

Basic Instance

curl -X POST https://api.example.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "qrcode": true
  }'

curl -X POST https://api.example.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "webhook-instance",
    "qrcode": true,
    "webhookUrl": "https://your-server.com/webhook",
    "webhookByEvents": false,
    "webhookBase64": true,
    "webhookEvents": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE"
    ]
  }'

curl -X POST https://api.example.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "configured-instance",
    "qrcode": true,
    "rejectCall": true,
    "msgCall": "Sorry, calls are not accepted.",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": false
  }'

curl -X POST https://api.example.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "business-instance",
    "integration": "WHATSAPP-BUSINESS",
    "number": "5511999999999",
    "businessId": "123456789012345"
  }'

curl -X POST https://api.example.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "chatwoot-instance",
    "qrcode": true,
    "chatwootAccountId": "1",
    "chatwootToken": "your-chatwoot-token",
    "chatwootUrl": "https://chatwoot.example.com",
    "chatwootSignMsg": true,
    "chatwootReopenConversation": true,
    "chatwootConversationPending": false,
    "chatwootImportContacts": true,
    "chatwootImportMessages": true,
    "chatwootDaysLimitImportMessages": 30
  }'

const response = await fetch('https://api.example.com/instance/create', {
  method: 'POST',
  headers: {
    'apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    instanceName: 'my-instance',
    qrcode: true,
    webhookUrl: 'https://your-server.com/webhook',
    readMessages: true,
    alwaysOnline: true
  })
});

const data = await response.json();
console.log('Instance created:', data.instance.instanceName);
console.log('Auth token:', data.hash);

import requests

response = requests.post(
    'https://api.example.com/instance/create',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'instanceName': 'my-instance',
        'qrcode': True,
        'webhookUrl': 'https://your-server.com/webhook',
        'readMessages': True,
        'alwaysOnline': True
    }
)

data = response.json()
print(f"Instance created: {data['instance']['instanceName']}")
print(f"Auth token: {data['hash']}")

<?php
$response = file_get_contents('https://api.example.com/instance/create', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => [
            'apikey: YOUR_API_KEY',
            'Content-Type: application/json'
        ],
        'content' => json_encode([
            'instanceName' => 'my-instance',
            'qrcode' => true,
            'webhookUrl' => 'https://your-server.com/webhook',
            'readMessages' => true,
            'alwaysOnline' => true
        ])
    ]
]));

$data = json_decode($response, true);
echo "Instance created: " . $data['instance']['instanceName'] . "\n";
echo "Auth token: " . $data['hash'] . "\n";
?>

Response Example

Success Response

{
  "instance": {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "integration": "WHATSAPP-BAILEYS",
    "status": "close"
  },
  "hash": "A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D",
  "webhook": {
    "webhookUrl": "https://your-server.com/webhook",
    "webhookByEvents": false,
    "webhookBase64": true
  },
  "websocket": {
    "enabled": false
  },
  "rabbitmq": {
    "enabled": false
  },
  "sqs": {
    "enabled": false
  },
  "nats": {
    "enabled": false
  },
  "settings": {
    "rejectCall": false,
    "msgCall": "",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": false,
    "syncFullHistory": false
  },
  "qrcode": {
    "code": "2@abc123...",
    "base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Error Response

{
  "error": true,
  "message": "The \"instanceName\" cannot be empty"
}

Important: Save the hash value from the response. You’ll need it as your apikey for all subsequent API calls related to this instance.

If you provide Chatwoot credentials (chatwootAccountId, chatwootToken, chatwootUrl), all three fields are required along with chatwootSignMsg, chatwootReopenConversation, and chatwootConversationPending.

Error Handling

The API returns standard HTTP status codes:

• 201 - Instance created successfully
• 400 - Bad request (validation error)
• 401 - Unauthorized (invalid API key)
• 500 - Internal server error

Common error scenarios:

1. Missing instanceName: The instanceName field is required
2. Invalid integration: Unknown integration type specified
3. Invalid proxy: Proxy configuration test failed
4. Chatwoot validation: Missing required Chatwoot fields when partial config provided
5. Business API requirements: Missing number field for WhatsApp Business integration