> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance Settings

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

## Overview

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

<Info>
  These settings apply to the entire instance and affect how your WhatsApp bot behaves.
</Info>

## Authentication

This endpoint requires authentication via the `apikey` header.

<ParamField path="header.apikey" type="string" required>
  Your Evolution API key for authentication.
</ParamField>

## Path Parameters

<ParamField path="path.instanceName" type="string" required>
  The name of your WhatsApp instance.
</ParamField>

## Request Body

<ParamField body="rejectCall" type="boolean" default="false">
  Automatically reject incoming calls.
</ParamField>

<ParamField body="msgCall" type="string">
  Message to send when a call is rejected (only used if `rejectCall` is true).
</ParamField>

<ParamField body="groupsIgnore" type="boolean" default="false">
  Ignore messages from groups (don't trigger webhooks or chatbot responses).
</ParamField>

<ParamField body="alwaysOnline" type="boolean" default="false">
  Keep the instance status as "online" at all times.
</ParamField>

<ParamField body="readMessages" type="boolean" default="false">
  Automatically mark all incoming messages as read.
</ParamField>

<ParamField body="readStatus" type="boolean" default="false">
  Automatically read status updates from contacts.
</ParamField>

<ParamField body="syncFullHistory" type="boolean" default="false">
  Synchronize full message history when connecting (may take longer to connect).
</ParamField>

<ParamField body="wavoipToken" type="string">
  Token for VOIP integration (advanced feature).
</ParamField>

## Response

<ResponseField name="settings" type="object">
  The updated settings object.

  <Expandable title="properties">
    <ResponseField name="instanceId" type="string">
      The instance identifier.
    </ResponseField>

    <ResponseField name="rejectCall" type="boolean">
      Call rejection status.
    </ResponseField>

    <ResponseField name="msgCall" type="string">
      Message sent on call rejection.
    </ResponseField>

    <ResponseField name="groupsIgnore" type="boolean">
      Group message ignore status.
    </ResponseField>

    <ResponseField name="alwaysOnline" type="boolean">
      Always online status.
    </ResponseField>

    <ResponseField name="readMessages" type="boolean">
      Auto-read messages status.
    </ResponseField>

    <ResponseField name="readStatus" type="boolean">
      Auto-read status updates.
    </ResponseField>

    <ResponseField name="syncFullHistory" type="boolean">
      Full history sync status.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Success theme={null}
  {
    "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
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid settings",
    "message": "rejectCall must be a boolean value"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Instance not found",
    "message": "The instance 'my-instance' does not exist"
  }
  ```
</ResponseExample>

## Setting Details

### Call Rejection

<Tabs>
  <Tab title="rejectCall">
    When enabled, all incoming voice and video calls are automatically rejected. Useful for chatbot instances that should only handle text messages.
  </Tab>

  <Tab title="msgCall">
    Customize the message sent when rejecting calls. This helps inform callers why their call was rejected and what they should do instead.
  </Tab>
</Tabs>

### Message Handling

<Tabs>
  <Tab title="readMessages">
    Automatically marks all incoming messages as read. The sender will see blue checkmarks immediately.
  </Tab>

  <Tab title="groupsIgnore">
    When enabled, messages from groups won't trigger webhooks or chatbot responses. Useful when you want to handle only individual chats.
  </Tab>
</Tabs>

### Presence and Status

<Tabs>
  <Tab title="alwaysOnline">
    Keeps your instance showing as "online" continuously. Useful for bot accounts to appear always available.
  </Tab>

  <Tab title="readStatus">
    Automatically views status updates posted by your contacts. They will see that you viewed their status.
  </Tab>
</Tabs>

### History Synchronization

<Tabs>
  <Tab title="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.
  </Tab>
</Tabs>

## Usage Notes

<Tip>
  For chatbot instances, consider enabling `rejectCall`, `alwaysOnline`, and `readMessages` for the best user experience.
</Tip>

<Warning>
  Enabling `syncFullHistory` can significantly slow down instance connection, especially for accounts with large message histories.
</Warning>

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

## Get Current Settings

To retrieve current settings:

```
GET /settings/find/:instanceName
```

This returns the current configuration for your instance.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.example.com/settings/find/my-instance \
    --header 'apikey: YOUR_API_KEY'
  ```
</RequestExample>