# Configurar limite e comportamento das chamadas recebidas da instância

`POST /instance/call-settings`

Persiste parcialmente callsMaxConcurrent e/ou incomingCallMode, mesmo desconectada, sem iniciar chamadas ou reiniciar a sessão. Campos omitidos permanecem. expectedCallsConfigVersion opcional exige a versão atual e retorna 409 settings_version_conflict em divergência. Cada POST aceito incrementa callsConfigVersion e grava atomicamente call_settings com limite e modo, mesmo repetindo valores. Alterações de modo valem para novas chamadas. O worker local aplica imediatamente; outro worker aplica na renovação do lease. Rejeições automáticas geram histórico e evento, inclusive quando ocupado, sem consumir uma vaga de atendimento. reject_reply somente solicita resposta ao consumidor: a instância calls não envia texto. A integração deve configurar uma conexão de mensagens, deduplicação e fila persistente. Reduzir o limite preserva chamadas vivas. Mais de uma simultânea e atendimento recebido ainda dependem de homologação real.

## Autenticação

Header obrigatório: `token`. Use o token da instância.

Base URL: a API do servidor selecionado, como `https://1.atendro.cloud`. O domínio `wpp.atendro.cloud` hospeda a documentação e o console.

## Headers adicionais

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `X-Request-Id` | `string` | opcional | ASCII visível sem espaços, 1–128 caracteres. Inválido/ausente é substituído por UUID. Ecoado na resposta. Comprimento máximo: `128` |

## Corpo da requisição

Formato: `application/json`. Corpo obrigatório.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `callsMaxConcurrent` | `integer` | condicional | Limite próprio de ligações simultâneas da instância calls: voz e vídeo, recebidas e realizadas, incluindo ringing/connecting/active e reservas de discagem. Acima de 1 ainda depende de homologação em chamadas reais. Mínimo: `1`. Máximo: `8` |
| `incomingCallMode` | `string` | condicional | Comportamento para novas chamadas recebidas: allow permite atendimento humano; reject recusa no servidor; reject_reply recusa e solicita ao consumidor resposta por uma conexão de mensagens vinculada. Não atende automaticamente. O envio do texto é independente da recusa. Modelo: [IncomingCallMode](https://wpp.atendro.cloud/docs/modelos/incoming-call-mode.md). Valores: `"allow"`, `"reject"`, `"reject_reply"` |
| `expectedCallsConfigVersion` | `integer` | opcional | Comparação condicional opcional. Se diferente da versão salva, retorna 409 settings_version_conflict sem alterar a instância. Enviar junto a pelo menos um campo de configuração. Mínimo: `0`. Formato: `int64` |

Pelo menos uma destas combinações deve ser válida:

- `callsMaxConcurrent`
- `incomingCallMode`

## Resposta 200

Limite e snapshot persistidos na mesma transação; instance.callsMaxConcurrent e instance.callsConfigVersion são os valores canônicos. Compare a versão com respostas e eventos em trânsito.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `instance` | `object` | obrigatório |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "callId": "CHAMADA_DE_TESTE",
  "direction": "outbound",
  "number": "12025550123",
  "status": "ringing",
  "startedAt": "2026-09-18T00:00:00Z"
}
```

## Resposta 400

invalid_calls_max_concurrent (obrigatório, inteiro de 1 a 8), invalid_json ou invalid_body.

## Resposta 401

unauthorized: header ausente, inválido ou duplicado. Bearer/query/instancekey não substituem admintoken/token.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "unauthorized"
}
```

## Resposta 409

wrong_instance_kind: configuração exclusiva de instâncias calls.

## Resposta 502

storage_unavailable (Retry-After=5). Algumas rotas também retornam 502 por falha da conexão/mídia; consultar error.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "storage_unavailable"
}
```

## Exemplos de requisição

Defina as variáveis no ambiente privado e substitua os dados sintéticos antes de usar. Os exemplos não executam operações nesta página.

### cURL

```sh
curl --request POST "$ATENDROZAP_URL/instance/call-settings" \
  --header "token: $ATENDROZAP_INSTANCE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "callsMaxConcurrent": 2
}'
```

### JavaScript

```javascript
const baseUrl = process.env.ATENDROZAP_URL;
let path = "/instance/call-settings";
const url = new URL(path, baseUrl);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "token": process.env.ATENDROZAP_INSTANCE_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "callsMaxConcurrent": 2
  }),
});

if (!response.ok) {
  throw new Error(`AtendroZAP: HTTP ${response.status}`);
}
const result = await response.json();
```

## Relacionados

- [Chamadas de voz e vídeo](https://wpp.atendro.cloud/docs/api/ligacoes.md)
- [Autenticação](https://wpp.atendro.cloud/docs/guias/autenticacao.md)
- [Erros e idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md)