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

# Atualizar Campanha

> Atualizar parcialmente a configuração de uma campanha

# Atualizar Campanha

Atualiza parcialmente uma campanha existente. Todos os campos são opcionais — apenas os campos que você enviar serão atualizados. Use [Atualizar Status da Campanha](/api-reference/endpoints/update-campaign-status) para alterar apenas o status (`draft → active → paused → completed`).

## Endpoint

```
PUT /api/v1/campaigns/{campaign_id}
```

## Parâmetros de caminho

<ParamField path="campaign_id" type="string" required>
  UUID da campanha a ser atualizada.
</ParamField>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

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

## Corpo da requisição

Todos os campos são opcionais. Envie apenas o que você quer alterar. As regras de validação e faixas correspondem a [Criar Campanha](/api-reference/endpoints/create-campaign).

### Identificação

<ParamField body="name" type="string">
  Nome da campanha. Máximo de 255 caracteres.
</ParamField>

<ParamField body="description" type="string">
  Descrição livre.
</ParamField>

<ParamField body="campaign_type" type="string">
  Categoria da campanha. Opções: `sales`, `follow_up`, `reminder`, `custom`.
</ParamField>

<ParamField body="agent_id" type="string">
  UUID do agente. Deve existir em seu ambiente.
</ParamField>

### Agendamento

<ParamField body="start_date" type="string">
  Formato: `YYYY-MM-DD`.
</ParamField>

<ParamField body="end_date" type="string">
  Data de término opcional. Deve ser após `start_date`. Formato: `YYYY-MM-DD`. Envie `null` para limpar.
</ParamField>

<ParamField body="days_of_week" type="array">
  Array de números de dias da semana (`1`–`7`, onde `1` = Segunda-feira). Mínimo de 1 entrada.
</ParamField>

<ParamField body="call_time_ranges" type="array">
  Janelas de horário. Array de objetos `{start: "HH:MM", end: "HH:MM"}` (formato 24h). Mínimo de 1 entrada. O `end` de cada janela deve ser após seu `start`.
</ParamField>

<ParamField body="timezone" type="string">
  Fuso horário IANA (ex: `America/Sao_Paulo`). Máximo de 50 caracteres.
</ParamField>

### Retry e Cooldown

<ParamField body="initial_call_delay" type="integer">
  Atraso inicial em segundos. Faixa: `0`+.
</ParamField>

<ParamField body="max_retries" type="integer">
  Faixa: `0`–`10`.
</ParamField>

<ParamField body="retry_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

<ParamField body="auto_complete" type="boolean">
  Auto-transição para `completed` quando todos os contatos forem processados.
</ParamField>

<ParamField body="retry_on_no_conversion" type="boolean">
  Retenta chamadas que foram completadas sem conversão.
</ParamField>

<ParamField body="enable_post_completion_cooldown" type="boolean" />

<ParamField body="post_completion_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

<ParamField body="success_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

<ParamField body="voicemail_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

<ParamField body="no_answer_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

<ParamField body="busy_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

<ParamField body="failed_cooldown_hours" type="integer">
  Faixa: `1`–`168`.
</ParamField>

### Do-Not-Call (DNC)

<ParamField body="do_not_call_enabled" type="boolean" />

<ParamField body="do_not_call_list_source" type="string">
  Opções: `environment`, `global`, `custom`.
</ParamField>

<ParamField body="do_not_call_custom_list" type="array">
  Array de números de telefone (E.164). Usado quando `do_not_call_list_source` é `custom`.
</ParamField>

<ParamField body="auto_add_to_dnc_enabled" type="boolean" />

<ParamField body="auto_dnc_trigger_statuses" type="array" />

<ParamField body="auto_dnc_trigger_errors" type="array" />

## Exemplos

<RequestExample>
  ```bash theme={null}
  # Update only the call windows + timezone
  curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "call_time_ranges": [
        {"start": "10:00", "end": "12:00"},
        {"start": "14:00", "end": "16:00"}
      ],
      "timezone": "America/Sao_Paulo"
    }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      call_time_ranges: [
        { start: '10:00', end: '12:00' },
        { start: '14:00', end: '16:00' }
      ],
      timezone: 'America/Sao_Paulo'
    })
  });

  const result = await response.json();
  ```

  ```python theme={null}
  import requests

  url = "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1"
  headers = {
      "Authorization": "Bearer talq_your_environment_token_here",
      "Content-Type": "application/json"
  }
  data = {
      "call_time_ranges": [
          {"start": "10:00", "end": "12:00"},
          {"start": "14:00", "end": "16:00"}
      ],
      "timezone": "America/Sao_Paulo"
  }

  response = requests.put(url, headers=headers, json=data)
  result = response.json()
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Switch to custom DNC list and tighten retry policy
  curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "max_retries": 2,
      "retry_cooldown_hours": 12,
      "success_cooldown_hours": 168,
      "do_not_call_enabled": true,
      "do_not_call_list_source": "custom",
      "do_not_call_custom_list": ["+5511987654321"],
      "auto_add_to_dnc_enabled": true,
      "auto_dnc_trigger_statuses": ["completed"]
    }'
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "campaign-uuid-1",
      "name": "Sales Campaign Q1",
      "campaign_type": "sales",
      "status": "active",
      "agent_id": "agent-uuid-1",
      "start_date": "2024-01-01",
      "end_date": null,
      "days_of_week": [1, 2, 3, 4, 5],
      "call_time_ranges": [
        {"start": "10:00", "end": "12:00"},
        {"start": "14:00", "end": "16:00"}
      ],
      "timezone": "America/Sao_Paulo",
      "max_retries": 3,
      "retry_cooldown_hours": 24,
      "do_not_call_enabled": false,
      "updated_at": "2024-01-15T11:30:00Z"
    }
  }
  ```
</ResponseExample>

## Respostas de erro

### 422 Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "call_time_ranges.0.end": [
        "The call time ranges.0.end must be a date after call time ranges.0.start."
      ]
    }
  }
  ```
</ResponseExample>

### 404 Não Encontrada

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Campaign not found"
  }
  ```
</ResponseExample>

### 409 Conflict — Chamadas Ativas

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Cannot update schedule while there are queued calls. Pause the campaign first.",
    "code": "CAMPAIGN_HAS_ACTIVE_CALLS"
  }
  ```
</ResponseExample>

## Observações

* Use `PATCH /v1/campaigns/{id}/status` para alterar o status — é um endpoint separado com sua própria validação.
* Atualizar `call_time_ranges` ou `timezone` enquanto a campanha está `active` pode atrasar chamadas enfileiradas até que elas voltem a se encaixar nas novas janelas.
* Enviar `"end_date": null` limpa uma data de término previamente definida.

## Endpoints relacionados

* [Obter Campanha](/api-reference/endpoints/get-campaign)
* [Atualizar Status da Campanha](/api-reference/endpoints/update-campaign-status)
* [Excluir Campanha](/api-reference/endpoints/delete-campaign)
* [Listar Campanhas](/api-reference/endpoints/list-campaigns)