> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# New instance

> Provisions a new instance and, optionally, configures webhook, WebSocket, Chatwoot, proxy, S3, and settings inline in the same request

**Auth:** `TokenAccount` • **Rate-limit:** `20/min` • **Idempotent:** no

## Description

Creates a new WhatsApp instance in your account. The instance is born **disconnected**, the next step is to call [`GET /api/instance/connect/:instance`](/en/api/instance/connect) to obtain the QR code or pairing code.

During creation, you can send, in the same body, the initial configuration of **proxy**, **webhook**, **WebSocket**, **Chatwoot integration**, **behavior settings**, and **S3 storage**. Each block is independent: send only what you need.

<Tip>
  The instance is created within your account quota. If you've reached the limit, you receive `403` with the message `Account instance quota exceeded`, delete an instance you no longer use to free up space.
</Tip>

<Warning>
  Failures in sub-blocks (webhook / websocket / chatwoot) **do not abort** the instance creation. Each block is log-and-continue: the instance is created, the sub-block appears as `enabled: false` or absent in the response, and the server logs describe the cause. For Chatwoot, the failure is also exposed in `chatwoot.status: "error"` + `chatwoot.error: "<message>"` in the return payload.
</Warning>

## Examples

### Minimum

Creates the instance with just the `name`. The `TokenInstance` is generated automatically by the server and returned in `instance.token` in the response, keep it to authenticate subsequent calls.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{"name":"my-instance"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ name: "my-instance" })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={"name": "my-instance"}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{"name":"my-instance"}`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With custom token

Manually sets the `TokenInstance` in the `token` field instead of letting the server generate one. Useful for reusing a value already registered in another system, the token must be unique within your account.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":  "my-instance",
      "token": "my-custom-token-123"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:  "my-instance",
      token: "my-custom-token-123"
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":  "my-instance",
          "token": "my-custom-token-123"
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":  "my-instance",
          "token": "my-custom-token-123"
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With custom settings

Creates the instance with the `settings` block already defined: auto-rejects calls with a default message, keeps presence online, disables history sync, and ignores stories. Equivalent to calling `POST /api/instance/settings/:instance` right after.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-instance",
      "autoRejectCalls":      true,
      "callRejectMessage":    "This number does not accept calls.",
      "ignoreGroupMessages":  false,
      "keepOnlineStatus":     true,
      "autoReadMessages":     false,
      "disableHistorySync":   true,
      "ignoreStatus":         true
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:                "my-instance",
      autoRejectCalls:     true,
      callRejectMessage:   "This number does not accept calls.",
      ignoreGroupMessages: false,
      keepOnlineStatus:    true,
      autoReadMessages:    false,
      disableHistorySync:  true,
      ignoreStatus:        true
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":                "my-instance",
          "autoRejectCalls":     True,
          "callRejectMessage":   "This number does not accept calls.",
          "ignoreGroupMessages": False,
          "keepOnlineStatus":    True,
          "autoReadMessages":    False,
          "disableHistorySync":  True,
          "ignoreStatus":        True
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":                "my-instance",
          "autoRejectCalls":     true,
          "callRejectMessage":   "This number does not accept calls.",
          "ignoreGroupMessages": false,
          "keepOnlineStatus":    true,
          "autoReadMessages":    false,
          "disableHistorySync":  true,
          "ignoreStatus":        true
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With proxy

Provisions the instance pointing to an authenticated SOCKS5 proxy. The password is encrypted at-rest with AES-256-GCM and is never returned in the response.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":          "my-instance",
      "proxyEnabled":  true,
      "proxyProtocol": "socks5",
      "proxyHost":     "proxy.company.com",
      "proxyPort":     "1080",
      "proxyUsername": "user",
      "proxyPassword": "proxy-password"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:          "my-instance",
      proxyEnabled:  true,
      proxyProtocol: "socks5",
      proxyHost:     "proxy.company.com",
      proxyPort:     "1080",
      proxyUsername: "user",
      proxyPassword: "proxy-password"
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":          "my-instance",
          "proxyEnabled":  True,
          "proxyProtocol": "socks5",
          "proxyHost":     "proxy.company.com",
          "proxyPort":     "1080",
          "proxyUsername": "user",
          "proxyPassword": "proxy-password"
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":          "my-instance",
          "proxyEnabled":  true,
          "proxyProtocol": "socks5",
          "proxyHost":     "proxy.company.com",
          "proxyPort":     "1080",
          "proxyUsername": "user",
          "proxyPassword": "proxy-password"
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With webhook

In the same request, configures the `default` webhook to receive only the `message.exchange` and `call.update` events, with custom `Authorization` to validate the source. Media is not sent in base64, the destination fetches via the returned URL.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":                 "my-instance",
      "webhookEnabled":       true,
      "webhookURL":           "https://myapp.com/webhook",
      "webhookAuthorization": "Bearer secret-key-123",
      "webhookByEvents":      false,
      "webhookEvents":        ["message.exchange", "call.update"],
      "webhookMediaBase64":   false
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:                 "my-instance",
      webhookEnabled:       true,
      webhookURL:           "https://myapp.com/webhook",
      webhookAuthorization: "Bearer secret-key-123",
      webhookByEvents:      false,
      webhookEvents:        ["message.exchange", "call.update"],
      webhookMediaBase64:   false
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":                 "my-instance",
          "webhookEnabled":       True,
          "webhookURL":           "https://myapp.com/webhook",
          "webhookAuthorization": "Bearer secret-key-123",
          "webhookByEvents":      False,
          "webhookEvents":        ["message.exchange", "call.update"],
          "webhookMediaBase64":   False
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":                 "my-instance",
          "webhookEnabled":       true,
          "webhookURL":           "https://myapp.com/webhook",
          "webhookAuthorization": "Bearer secret-key-123",
          "webhookByEvents":      false,
          "webhookEvents":        ["message.exchange", "call.update"],
          "webhookMediaBase64":   false
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With WebSocket

Enables real-time broadcast via WebSocket filtering by the `message.exchange` and `call.update` events. Useful for dashboards and bots that need minimum latency without exposing a public webhook endpoint.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":                 "my-instance",
      "websocketEnabled":     true,
      "websocketEvents":      ["message.exchange", "call.update"],
      "websocketMediaBase64": false
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:                 "my-instance",
      websocketEnabled:     true,
      websocketEvents:      ["message.exchange", "call.update"],
      websocketMediaBase64: false
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":                 "my-instance",
          "websocketEnabled":     True,
          "websocketEvents":      ["message.exchange", "call.update"],
          "websocketMediaBase64": False
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":                 "my-instance",
          "websocketEnabled":     true,
          "websocketEvents":      ["message.exchange", "call.update"],
          "websocketMediaBase64": false
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With S3

Points media storage to an AWS S3 bucket (`us-east-1`), with prefix `media/` to organize uploads. The `s3SecretKey` is encrypted at-rest and never appears in the response.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":         "my-instance",
      "s3Enabled":    true,
      "s3Region":     "us-east-1",
      "s3Bucket":     "my-media-bucket",
      "s3AccessKey":  "AKIA...",
      "s3SecretKey":  "secret...",
      "s3Endpoint":   "https://s3.amazonaws.com",
      "s3PathPrefix": "media/"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:         "my-instance",
      s3Enabled:    true,
      s3Region:     "us-east-1",
      s3Bucket:     "my-media-bucket",
      s3AccessKey:  "AKIA...",
      s3SecretKey:  "secret...",
      s3Endpoint:   "https://s3.amazonaws.com",
      s3PathPrefix: "media/"
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":         "my-instance",
          "s3Enabled":    True,
          "s3Region":     "us-east-1",
          "s3Bucket":     "my-media-bucket",
          "s3AccessKey":  "AKIA...",
          "s3SecretKey":  "secret...",
          "s3Endpoint":   "https://s3.amazonaws.com",
          "s3PathPrefix": "media/"
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":         "my-instance",
          "s3Enabled":    true,
          "s3Region":     "us-east-1",
          "s3Bucket":     "my-media-bucket",
          "s3AccessKey":  "AKIA...",
          "s3SecretKey":  "secret...",
          "s3Endpoint":   "https://s3.amazonaws.com",
          "s3PathPrefix": "media/"
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### With Chatwoot

Provisions the instance already linked to a Chatwoot inbox (`WhatsApp - Orion`), with active agent signature and automatic reopening of resolved conversations. If Chatwoot activation fails, the instance is created anyway and the `chatwoot` object returns with `status: "error"`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":                  "support",
      "chatwootEnabled":       true,
      "chatwootBaseUrl":       "https://chatwoot.example.com",
      "chatwootAccountId":     5,
      "chatwootApiToken":      "sk_live_abc123...",
      "chatwootInboxName":     "WhatsApp - Orion",
      "chatwootSignMessages":  true,
      "chatwootIgnoreGroups":  false,
      "chatwootStartAsPending": false,
      "chatwootReopenResolved": true
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:                   "support",
      chatwootEnabled:        true,
      chatwootBaseUrl:        "https://chatwoot.example.com",
      chatwootAccountId:      5,
      chatwootApiToken:       "sk_live_abc123...",
      chatwootInboxName:      "WhatsApp - Orion",
      chatwootSignMessages:   true,
      chatwootIgnoreGroups:   false,
      chatwootStartAsPending: false,
      chatwootReopenResolved: true
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":                   "support",
          "chatwootEnabled":        True,
          "chatwootBaseUrl":        "https://chatwoot.example.com",
          "chatwootAccountId":      5,
          "chatwootApiToken":       "sk_live_abc123...",
          "chatwootInboxName":      "WhatsApp - Orion",
          "chatwootSignMessages":   True,
          "chatwootIgnoreGroups":   False,
          "chatwootStartAsPending": False,
          "chatwootReopenResolved": True
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":                   "support",
          "chatwootEnabled":        true,
          "chatwootBaseUrl":        "https://chatwoot.example.com",
          "chatwootAccountId":      5,
          "chatwootApiToken":       "sk_live_abc123...",
          "chatwootInboxName":      "WhatsApp - Orion",
          "chatwootSignMessages":   true,
          "chatwootIgnoreGroups":   false,
          "chatwootStartAsPending": false,
          "chatwootReopenResolved": true
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Complete

Combines every block in the same request: custom token, SOCKS5 proxy, webhook, WebSocket, Chatwoot integration, behavior settings, and S3 storage. Each block remains independent, failures in sub-blocks don't abort the instance creation.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "name":  "marketing",
      "token": "my-custom-token-123",

      "proxyEnabled":  true,
      "proxyProtocol": "socks5",
      "proxyHost":     "proxy.company.com",
      "proxyPort":     "1080",
      "proxyUsername": "user",
      "proxyPassword": "proxy-password",

      "webhookEnabled":       true,
      "webhookURL":           "https://myserver.com/webhook",
      "webhookAuthorization": "Bearer secret-key-123",
      "webhookByEvents":      false,
      "webhookEvents":        ["message.exchange", "call.update"],
      "webhookMediaBase64":   false,

      "websocketEnabled":     true,
      "websocketEvents":      ["message.exchange", "call.update"],
      "websocketMediaBase64": false,

      "chatwootEnabled":        true,
      "chatwootBaseUrl":        "https://chatwoot.example.com",
      "chatwootAccountId":      5,
      "chatwootApiToken":       "sk_live_abc123...",
      "chatwootInboxName":      "Marketing",
      "chatwootSignMessages":   true,
      "chatwootIgnoreGroups":   false,
      "chatwootStartAsPending": false,
      "chatwootReopenResolved": true,

      "autoRejectCalls":     true,
      "callRejectMessage":   "This number does not accept calls.",
      "ignoreGroupMessages": false,
      "keepOnlineStatus":    true,
      "autoReadMessages":    false,
      "disableHistorySync":  false,
      "ignoreStatus":        true,

      "s3Enabled":    true,
      "s3Region":     "us-east-1",
      "s3Bucket":     "my-media-bucket",
      "s3AccessKey":  "AKIA...",
      "s3SecretKey":  "secret...",
      "s3Endpoint":   "https://s3.amazonaws.com",
      "s3PathPrefix": "media/"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/new", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name:  "marketing",
      token: "my-custom-token-123",

      proxyEnabled:  true,
      proxyProtocol: "socks5",
      proxyHost:     "proxy.company.com",
      proxyPort:     "1080",
      proxyUsername: "user",
      proxyPassword: "proxy-password",

      webhookEnabled:       true,
      webhookURL:           "https://myserver.com/webhook",
      webhookAuthorization: "Bearer secret-key-123",
      webhookByEvents:      false,
      webhookEvents:        ["message.exchange", "call.update"],
      webhookMediaBase64:   false,

      websocketEnabled:     true,
      websocketEvents:      ["message.exchange", "call.update"],
      websocketMediaBase64: false,

      chatwootEnabled:        true,
      chatwootBaseUrl:        "https://chatwoot.example.com",
      chatwootAccountId:      5,
      chatwootApiToken:       "sk_live_abc123...",
      chatwootInboxName:      "Marketing",
      chatwootSignMessages:   true,
      chatwootIgnoreGroups:   false,
      chatwootStartAsPending: false,
      chatwootReopenResolved: true,

      autoRejectCalls:     true,
      callRejectMessage:   "This number does not accept calls.",
      ignoreGroupMessages: false,
      keepOnlineStatus:    true,
      autoReadMessages:    false,
      disableHistorySync:  false,
      ignoreStatus:        true,

      s3Enabled:    true,
      s3Region:     "us-east-1",
      s3Bucket:     "my-media-bucket",
      s3AccessKey:  "AKIA...",
      s3SecretKey:  "secret...",
      s3Endpoint:   "https://s3.amazonaws.com",
      s3PathPrefix: "media/"
    })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "name":  "marketing",
          "token": "my-custom-token-123",

          "proxyEnabled":  True,
          "proxyProtocol": "socks5",
          "proxyHost":     "proxy.company.com",
          "proxyPort":     "1080",
          "proxyUsername": "user",
          "proxyPassword": "proxy-password",

          "webhookEnabled":       True,
          "webhookURL":           "https://myserver.com/webhook",
          "webhookAuthorization": "Bearer secret-key-123",
          "webhookByEvents":      False,
          "webhookEvents":        ["message.exchange", "call.update"],
          "webhookMediaBase64":   False,

          "websocketEnabled":     True,
          "websocketEvents":      ["message.exchange", "call.update"],
          "websocketMediaBase64": False,

          "chatwootEnabled":        True,
          "chatwootBaseUrl":        "https://chatwoot.example.com",
          "chatwootAccountId":      5,
          "chatwootApiToken":       "sk_live_abc123...",
          "chatwootInboxName":      "Marketing",
          "chatwootSignMessages":   True,
          "chatwootIgnoreGroups":   False,
          "chatwootStartAsPending": False,
          "chatwootReopenResolved": True,

          "autoRejectCalls":     True,
          "callRejectMessage":   "This number does not accept calls.",
          "ignoreGroupMessages": False,
          "keepOnlineStatus":    True,
          "autoReadMessages":    False,
          "disableHistorySync":  False,
          "ignoreStatus":        True,

          "s3Enabled":    True,
          "s3Region":     "us-east-1",
          "s3Bucket":     "my-media-bucket",
          "s3AccessKey":  "AKIA...",
          "s3SecretKey":  "secret...",
          "s3Endpoint":   "https://s3.amazonaws.com",
          "s3PathPrefix": "media/"
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "name":  "marketing",
          "token": "my-custom-token-123",

          "proxyEnabled":  true,
          "proxyProtocol": "socks5",
          "proxyHost":     "proxy.company.com",
          "proxyPort":     "1080",
          "proxyUsername": "user",
          "proxyPassword": "proxy-password",

          "webhookEnabled":       true,
          "webhookURL":           "https://myserver.com/webhook",
          "webhookAuthorization": "Bearer secret-key-123",
          "webhookByEvents":      false,
          "webhookEvents":        ["message.exchange", "call.update"],
          "webhookMediaBase64":   false,

          "websocketEnabled":     true,
          "websocketEvents":      ["message.exchange", "call.update"],
          "websocketMediaBase64": false,

          "chatwootEnabled":        true,
          "chatwootBaseUrl":        "https://chatwoot.example.com",
          "chatwootAccountId":      5,
          "chatwootApiToken":       "sk_live_abc123...",
          "chatwootInboxName":      "Marketing",
          "chatwootSignMessages":   true,
          "chatwootIgnoreGroups":   false,
          "chatwootStartAsPending": false,
          "chatwootReopenResolved": true,

          "autoRejectCalls":     true,
          "callRejectMessage":   "This number does not accept calls.",
          "ignoreGroupMessages": false,
          "keepOnlineStatus":    true,
          "autoReadMessages":    false,
          "disableHistorySync":  false,
          "ignoreStatus":        true,

          "s3Enabled":    true,
          "s3Region":     "us-east-1",
          "s3Bucket":     "my-media-bucket",
          "s3AccessKey":  "AKIA...",
          "s3SecretKey":  "secret...",
          "s3Endpoint":   "https://s3.amazonaws.com",
          "s3PathPrefix": "media/"
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/new", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Success response

The response includes the generated **TokenInstance** and the summary of every configured integration (proxy, webhook, websocket, chatwoot, settings, s3). Save the `instance.token`, it's what authenticates subsequent calls of the instance itself.

```json 201 Created theme={null}
{
  "success": true,
  "message": "Instance created",
  "instance": {
    "id": "5e1d...",
    "name": "my-instance",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "numberJid": null,
    "proxy": {
      "enabled": false,
      "host": null,
      "port": null,
      "protocol": null,
      "username": null,
      "password": null
    },
    "webhook": {
      "enabled": true,
      "url": "https://myapp.com/webhook",
      "events": ["message.exchange", "call.update"]
    },
    "websocket": {
      "enabled": true,
      "events": ["message.exchange"],
      "mediaBase64": false
    },
    "chatwoot": {
      "enabled": true,
      "status": "active",
      "bridgeIntegrationId": "int_xyz789abc",
      "baseUrl": "https://chatwoot.example.com",
      "accountId": 5,
      "inboxName": "WhatsApp - Orion"
    },
    "settings": {
      "autoRejectCalls": false,
      "callRejectMessage": "",
      "ignoreGroupMessages": false,
      "keepOnlineStatus": false,
      "autoReadMessages": false,
      "disableHistorySync": true,
      "ignoreStatus": false
    },
    "s3": {
      "enabled": false,
      "region": null,
      "bucket": null,
      "accessKey": null,
      "secretKey": null,
      "endpoint": null,
      "pathPrefix": null
    },
    "createdAt": "2026-04-28T10:30:00Z",
    "updatedAt": "2026-04-28T10:30:00Z"
  }
}
```

<Note>
  The `chatwootApiToken` is not returned in this response (it is exposed in plaintext only by [`GET /api/chatwoot/list/:instance`](/en/api/chatwoot/info)). The `s3.secretKey` and the `proxy.password` are **never** returned by any endpoint.
</Note>

### Chatwoot with error

If the `chatwoot*` block was sent but the configuration failed (e.g., invalid token), the instance **is created anyway** and the `chatwoot` object in the response comes with `status: "error"` and an actionable `error`:

```json theme={null}
"chatwoot": {
  "enabled": false,
  "status": "error",
  "error": "Chatwoot API returned 401 - check the chatwootApiToken"
}
```

You can fix the credentials via `POST /api/chatwoot/set/:instance` without recreating the instance.

## Headers

<ParamField header="token" type="string" required>
  Your **TokenAccount**.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Request body

<ParamField body="name" type="string" required>
  Instance identifier (used in the `:instance` paths in every other endpoint). Cannot be blank and must be unique within your account. Kebab-case or snake\_case is recommended.
</ParamField>

<ParamField body="token" type="string">
  Custom token for the instance. If omitted, it's generated automatically (recommended).
</ParamField>

### Proxy block (optional)

<ParamField body="proxyEnabled" type="boolean">
  Enables the use of a proxy specific to this instance.
</ParamField>

<ParamField body="proxyHost" type="string">
  Proxy IP or hostname.
</ParamField>

<ParamField body="proxyPort" type="string">
  Port as a string (e.g., `"8080"`).
</ParamField>

<ParamField body="proxyProtocol" type="string">
  `http`, `https`, or `socks5`.
</ParamField>

<ParamField body="proxyUsername" type="string">
  Proxy user (optional).
</ParamField>

<ParamField body="proxyPassword" type="string">
  Proxy password (optional, encrypted at-rest with AES-256-GCM).
</ParamField>

### Webhook block (optional)

<ParamField body="webhookEnabled" type="boolean">
  Enables sending events to a URL.
</ParamField>

<ParamField body="webhookURL" type="string">
  URL where RyzeAPI will POST the events.
</ParamField>

<ParamField body="webhookAuthorization" type="string">
  Value RyzeAPI sends in the `Authorization` header of each POST (useful to validate origin). Ex.: `Bearer secret-key-123`.
</ParamField>

<ParamField body="webhookByEvents" type="boolean">
  If `true`, each event type can have its own URL (default: `false`).
</ParamField>

<ParamField body="webhookEvents" type="string[]">
  List of events the instance should dispatch. Ex.: `["message.exchange", "call.update"]`.
</ParamField>

<ParamField body="webhookMediaBase64" type="boolean">
  Includes received media as base64 inside the webhook body.
</ParamField>

<Note>
  The webhook block creates **one** webhook with label `default`. For multiple webhooks per instance, use [`POST /api/events/webhook`](/en/api/events/overview) afterwards.
</Note>

### WebSocket block (optional)

<ParamField body="websocketEnabled" type="boolean">
  Enables event broadcasting via WebSocket for this instance.
</ParamField>

<ParamField body="websocketEvents" type="string[]">
  List of events that will be emitted via WebSocket. If empty with `websocketEnabled=true`, **all** events are emitted.
</ParamField>

<ParamField body="websocketMediaBase64" type="boolean">
  Includes received media as base64 in the WebSocket frames.
</ParamField>

### Chatwoot block (optional)

<ParamField body="chatwootEnabled" type="boolean">
  Enables the Chatwoot integration.
</ParamField>

<ParamField body="chatwootBaseUrl" type="string">
  URL of the Chatwoot installation (e.g., `https://chatwoot.example.com`). **Required** if `chatwootEnabled=true`.
</ParamField>

<ParamField body="chatwootAccountId" type="integer">
  Numeric ID of the Chatwoot account. **Required** if `chatwootEnabled=true`.
</ParamField>

<ParamField body="chatwootApiToken" type="string">
  Chatwoot account API token (the agent's `access_token`). **Required** if `chatwootEnabled=true`. Encrypted at-rest. Not returned in this response, but exposed in plaintext by [`GET /api/chatwoot/list/:instance`](/en/api/chatwoot/info).
</ParamField>

<ParamField body="chatwootInboxName" type="string">
  Name of the inbox that will be created in Chatwoot (e.g., `"WhatsApp - Orion"`).
</ParamField>

<ParamField body="chatwootSignMessages" type="boolean">
  If `true`, messages sent through the API are prefixed with the Chatwoot agent signature.
</ParamField>

<ParamField body="chatwootIgnoreGroups" type="boolean">
  If `true`, group messages do not become conversations in Chatwoot.
</ParamField>

<ParamField body="chatwootStartAsPending" type="boolean">
  If `true`, new conversations start as `pending` instead of `open`.
</ParamField>

<ParamField body="chatwootReopenResolved" type="boolean">
  If `true`, new messages on resolved conversations reopen them automatically.
</ParamField>

<Warning>
  The Chatwoot integration must be enabled on the server. If it isn't available, the instance creation continues and `chatwoot` returns `enabled: false` (the failure shows up in the server logs). See [the Chatwoot overview](/en/api/chatwoot/overview) for details.
</Warning>

### Settings block (optional)

<ParamField body="autoRejectCalls" type="boolean">
  Automatically rejects incoming calls.
</ParamField>

<ParamField body="callRejectMessage" type="string">
  Automatic message sent to the caller when the call is rejected.
</ParamField>

<ParamField body="ignoreGroupMessages" type="boolean">
  Does not process group messages (useful for 1-to-1 bots).
</ParamField>

<ParamField body="keepOnlineStatus" type="boolean">
  Keeps the instance marked as "online" in WhatsApp.
</ParamField>

<ParamField body="autoReadMessages" type="boolean">
  Automatically marks received messages as read.
</ParamField>

<ParamField body="disableHistorySync" type="boolean" default="true">
  **Default `true`** (history is not synced on the first connection). Send `false` if you want to receive the backlog.
</ParamField>

<ParamField body="ignoreStatus" type="boolean">
  Ignores "status" type messages (stories).
</ParamField>

### S3 block (optional, media storage)

<ParamField body="s3Enabled" type="boolean">
  Enables uploading received media to S3 or MinIO.
</ParamField>

<ParamField body="s3Region" type="string">
  Region (e.g., `us-east-1`).
</ParamField>

<ParamField body="s3Bucket" type="string">
  Bucket name.
</ParamField>

<ParamField body="s3AccessKey" type="string">
  Access Key ID.
</ParamField>

<ParamField body="s3SecretKey" type="string">
  Secret Access Key (encrypted at-rest, never returned).
</ParamField>

<ParamField body="s3Endpoint" type="string">
  Custom endpoint for MinIO or DigitalOcean Spaces. Omit for official AWS S3.
</ParamField>

<ParamField body="s3PathPrefix" type="string">
  Path prefix (e.g., `media/`).
</ParamField>

## Errors

| HTTP | `error.message`                         | When                              |
| :--: | --------------------------------------- | --------------------------------- |
|  400 | `Invalid request body`                  | Malformed JSON                    |
|  400 | `The 'name' field is required`          | `name` missing or blank           |
|  401 | `Invalid token`                         | Invalid TokenAccount              |
|  403 | `Account instance quota exceeded`       | Instance quota reached            |
|  409 | `Instance or token already exists`      | Name or token already in use      |
|  429 | `Rate limit exceeded. Try again later.` | More than 20 creations per minute |
|  500 | `Failed to create instance`             | Internal error                    |

**Error example:**

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Instance or token already exists"
  }
}
```

## Next

<CardGroup cols={2}>
  <Card title="Connect to WhatsApp" icon="qrcode" href="/en/api/instance/connect">
    Generate the QR code or pairing code to link the number.
  </Card>

  <Card title="Check state" icon="list-check" href="/en/api/instance/list">
    Use `GET /api/instance/list?instanceName=<name>` to inspect the current status.
  </Card>
</CardGroup>