Instance Settings

Configure instance-level settings and behaviors for your WhatsApp instance.

POST /settings/set/:instanceName

cURL

curl --request POST \
  --url https://api.example.com/settings/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "rejectCall": true,
    "msgCall": "Sorry, I cannot take calls at the moment. Please send a message.",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": false,
    "syncFullHistory": false
  }'

const response = await fetch(
  'https://api.example.com/settings/set/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      rejectCall: true,
      msgCall: 'Sorry, I cannot take calls at the moment. Please send a message.',
      groupsIgnore: false,
      alwaysOnline: true,
      readMessages: true,
      readStatus: false,
      syncFullHistory: false
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/settings/set/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'rejectCall': True,
        'msgCall': 'Sorry, I cannot take calls at the moment. Please send a message.',
        'groupsIgnore': False,
        'alwaysOnline': True,
        'readMessages': True,
        'readStatus': False,
        'syncFullHistory': False
    }
)

data = response.json()

201 Success

{
  "settings": {
    "instanceId": "my-instance",
    "rejectCall": true,
    "msgCall": "Sorry, I cannot take calls at the moment. Please send a message.",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": false,
    "syncFullHistory": false
  }
}

{
  "error": "Invalid settings",
  "message": "rejectCall must be a boolean value"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Overview

You can customize various settings for your WhatsApp instance, including call handling, message reading behavior, and history synchronization.

These settings apply to the entire instance and affect how your WhatsApp bot behaves.

Authentication

This endpoint requires authentication via the apikey header.

header.apikey · string · required

Your Evolution API key for authentication.

Path Parameters

path.instanceName · string · required

The name of your WhatsApp instance.

Request Body

rejectCall · boolean · default: "false"

Automatically reject incoming calls.

msgCall · string

Message to send when a call is rejected (only used if rejectCall is true).

groupsIgnore · boolean · default: "false"

Ignore messages from groups (don’t trigger webhooks or chatbot responses).

alwaysOnline · boolean · default: "false"

Keep the instance status as “online” at all times.

readMessages · boolean · default: "false"

Automatically mark all incoming messages as read.

readStatus · boolean · default: "false"

Automatically read status updates from contacts.

syncFullHistory · boolean · default: "false"

Synchronize full message history when connecting (may take longer to connect).

wavoipToken · string

Token for VOIP integration (advanced feature).

Response

settings · object

The updated settings object.

Show properties

instanceId · string

The instance identifier.

rejectCall · boolean

Call rejection status.

msgCall · string

Message sent on call rejection.

groupsIgnore · boolean

Group message ignore status.

alwaysOnline · boolean

Always online status.

readMessages · boolean

Auto-read messages status.

readStatus · boolean

Auto-read status updates.

syncFullHistory · boolean

Full history sync status.

cURL

curl --request POST \
  --url https://api.example.com/settings/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "rejectCall": true,
    "msgCall": "Sorry, I cannot take calls at the moment. Please send a message.",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": false,
    "syncFullHistory": false
  }'

const response = await fetch(
  'https://api.example.com/settings/set/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      rejectCall: true,
      msgCall: 'Sorry, I cannot take calls at the moment. Please send a message.',
      groupsIgnore: false,
      alwaysOnline: true,
      readMessages: true,
      readStatus: false,
      syncFullHistory: false
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/settings/set/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'rejectCall': True,
        'msgCall': 'Sorry, I cannot take calls at the moment. Please send a message.',
        'groupsIgnore': False,
        'alwaysOnline': True,
        'readMessages': True,
        'readStatus': False,
        'syncFullHistory': False
    }
)

data = response.json()

201 Success

{
  "settings": {
    "instanceId": "my-instance",
    "rejectCall": true,
    "msgCall": "Sorry, I cannot take calls at the moment. Please send a message.",
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": false,
    "syncFullHistory": false
  }
}

{
  "error": "Invalid settings",
  "message": "rejectCall must be a boolean value"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Setting Details

Call Rejection

rejectCall

When enabled, all incoming voice and video calls are automatically rejected. Useful for chatbot instances that should only handle text messages.

msgCall

Customize the message sent when rejecting calls. This helps inform callers why their call was rejected and what they should do instead.

Message Handling

readMessages

Automatically marks all incoming messages as read. The sender will see blue checkmarks immediately.

groupsIgnore

When enabled, messages from groups won’t trigger webhooks or chatbot responses. Useful when you want to handle only individual chats.

Presence and Status

alwaysOnline

Keeps your instance showing as “online” continuously. Useful for bot accounts to appear always available.

readStatus

Automatically views status updates posted by your contacts. They will see that you viewed their status.

History Synchronization

syncFullHistory

When enabled, the instance will download and sync complete message history on first connection. This may significantly increase connection time but ensures all historical data is available.

Usage Notes

For chatbot instances, consider enabling rejectCall, alwaysOnline, and readMessages for the best user experience.

Enabling syncFullHistory can significantly slow down instance connection, especially for accounts with large message histories.

You can update settings at any time without needing to restart the instance. Changes take effect immediately.

Get Current Settings

To retrieve current settings:

GET /settings/find/:instanceName

This returns the current configuration for your instance.

cURL

curl --request GET \
  --url https://api.example.com/settings/find/my-instance \
  --header 'apikey: YOUR_API_KEY'