Skip to main content
POST
https://api.enviaai.app
/
v1
/
instances
Create Instance
curl --request POST \
  --url https://api.enviaai.app/v1/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "webhookUrl": "<string>",
  "webhookEvents": [
    {}
  ],
  "settings": {},
  "settings.autoRead": true,
  "settings.autoTyping": true
}
'
{
  "success": true,
  "data": {
    "id": "inst_abc123",
    "name": "Sales WhatsApp",
    "status": "disconnected",
    "phone": null,
    "profileName": null,
    "profilePicUrl": null,
    "webhookUrl": "https://myapp.com/webhooks/whatsapp",
    "webhookEvents": ["message.received", "message.sent"],
    "settings": {
      "autoRead": false,
      "autoTyping": true
    },
    "createdAt": "2026-02-03T12:00:00.000Z"
  }
}

​
Overview

Create a new WhatsApp instance in your account. Each instance represents a separate WhatsApp connection that can send and receive messages.

​
Request Body

​
name
string
required
A descriptive name for the instance (e.g., “Sales WhatsApp”, “Support Team”)
​
webhookUrl
string
URL to receive webhook events for this instance
​
webhookEvents
array
List of events to send to the webhook. See Webhooks for available events.
​
settings
object
Instance settings
​
settings.autoRead
boolean
default:"false"
Automatically mark incoming messages as read
​
settings.autoTyping
boolean
default:"true"
Show typing indicator before sending messages

​
Examples

const instance = await client.instances.create({
  name: 'Sales WhatsApp',
  webhookUrl: 'https://myapp.com/webhooks/whatsapp',
  webhookEvents: ['message.received', 'message.sent'],
  settings: {
    autoRead: false,
    autoTyping: true
  }
});

console.log('Created instance:', instance.id);

​
Response

​
success
boolean
Indicates if the instance was created successfully
​
data
object
The created instance object
​
data.id
string
Unique identifier for the instance
​
data.name
string
Instance display name
​
data.status
string
Current status (always disconnected for new instances)
​
data.createdAt
string
ISO 8601 timestamp of creation
{
  "success": true,
  "data": {
    "id": "inst_abc123",
    "name": "Sales WhatsApp",
    "status": "disconnected",
    "phone": null,
    "profileName": null,
    "profilePicUrl": null,
    "webhookUrl": "https://myapp.com/webhooks/whatsapp",
    "webhookEvents": ["message.received", "message.sent"],
    "settings": {
      "autoRead": false,
      "autoTyping": true
    },
    "createdAt": "2026-02-03T12:00:00.000Z"
  }
}

​
Instance Limits

The number of instances you can create depends on your plan:
PlanMax Instances
Free1
Starter3
Pro10
EnterpriseUnlimited

​
Next Steps

After creating an instance, you’ll need to connect it:

Connect Instance

Connect via QR Code or Official API

Set Up Webhooks

Configure webhook events

​
Error Codes

CodeDescription
instance_limit_reachedYou’ve reached the maximum instances for your plan
invalid_webhook_urlThe webhook URL is not valid
invalid_webhook_eventsOne or more webhook events are invalid