Skip to main content

​
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

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
  }'

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us