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:

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