> ## 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.

# Criar Campanha

> Criar uma nova campanha com agendamento, lógica de retry e regras de do-not-call

# Criar Campanha

Cria uma nova campanha com agendamento, política de retry, cooldowns e regras de do-not-call. Campanhas são criadas com status `draft` — chame [Atualizar Status da Campanha](/api-reference/endpoints/update-campaign-status) com `"status": "active"` para começar a despachar chamadas.

## Endpoint

```
POST /api/v1/campaigns
```

## 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

### Identificação

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

<ParamField body="description" type="string" required={false}>
  Descrição livre da campanha.
</ParamField>

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

<ParamField body="agent_id" type="string" required>
  UUID do agente atribuído à campanha. O agente deve existir em seu ambiente.
</ParamField>

### Agendamento

<ParamField body="start_date" type="string" required>
  Data em que a campanha se torna elegível para despachar chamadas. Formato: `YYYY-MM-DD`.
</ParamField>

<ParamField body="end_date" type="string" required={false}>
  Data de término opcional. Deve ser após `start_date`. Formato: `YYYY-MM-DD`.
</ParamField>

<ParamField body="days_of_week" type="array" required>
  Array de números de dias da semana quando chamadas podem ser realizadas. `1` = Segunda-feira, `7` = Domingo. Pelo menos um valor obrigatório.
</ParamField>

<ParamField body="call_time_ranges" type="array" required>
  Janelas de horário (por dia) durante as quais as chamadas podem ser despachadas. Array de objetos com `start` e `end` no formato `HH:MM` (24h). Pelo menos uma janela obrigatória. O `end` de cada janela deve ser após seu `start`.

  Exemplo: `[{"start": "09:00", "end": "12:00"}, {"start": "14:00", "end": "17:00"}]`
</ParamField>

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

### Retry e Cooldown

<ParamField body="initial_call_delay" type="integer" required={false}>
  Atraso inicial (em segundos) antes da primeira tentativa de chamada. Padrão: `0`.
</ParamField>

<ParamField body="max_retries" type="integer" required={false}>
  Tentativas máximas de retry por contato. Faixa: `0`–`10`. Padrão: `3`.
</ParamField>

<ParamField body="retry_cooldown_hours" type="integer" required={false}>
  Horas a aguardar entre tentativas de retry. Faixa: `1`–`168`. Padrão: `24`.
</ParamField>

<ParamField body="auto_complete" type="boolean" required={false}>
  Quando `true`, a campanha automaticamente transita para `completed` assim que todos os contatos forem processados.
</ParamField>

<ParamField body="retry_on_no_conversion" type="boolean" required={false}>
  Quando `true`, chamadas que foram completadas mas não converteram são retentadas após o cooldown.
</ParamField>

<ParamField body="enable_post_completion_cooldown" type="boolean" required={false}>
  Quando `true`, aplica um cooldown a todos os contatos após a conclusão da campanha (impede re-engajamento imediato por outra campanha).
</ParamField>

<ParamField body="post_completion_cooldown_hours" type="integer" required={false}>
  Horas de cooldown aplicadas aos contatos após a conclusão da campanha. Faixa: `1`–`168`. Padrão: `168`.
</ParamField>

#### Cooldowns por status

Estes campos opcionais sobrescrevem `retry_cooldown_hours` para resultados de chamada específicos. Todos na faixa `1`–`168` horas.

<ParamField body="success_cooldown_hours" type="integer" required={false}>
  Cooldown após uma chamada bem-sucedida.
</ParamField>

<ParamField body="voicemail_cooldown_hours" type="integer" required={false}>
  Cooldown após cair no correio de voz.
</ParamField>

<ParamField body="no_answer_cooldown_hours" type="integer" required={false}>
  Cooldown após sem resposta.
</ParamField>

<ParamField body="busy_cooldown_hours" type="integer" required={false}>
  Cooldown após sinal de ocupado.
</ParamField>

<ParamField body="failed_cooldown_hours" type="integer" required={false}>
  Cooldown após uma chamada com falha.
</ParamField>

### Do-Not-Call (DNC)

<ParamField body="do_not_call_enabled" type="boolean" required={false}>
  Quando `true`, os contatos são verificados em uma lista DNC antes do despacho. Padrão: `false`.
</ParamField>

<ParamField body="do_not_call_list_source" type="string" required={false}>
  Origem da lista DNC. Opções:

  * `environment` — lista DNC compartilhada entre todas as campanhas neste ambiente
  * `global` — lista DNC global da plataforma
  * `custom` — lista específica da campanha fornecida em `do_not_call_custom_list`
</ParamField>

<ParamField body="do_not_call_custom_list" type="array" required={false}>
  Array de números de telefone (E.164) bloqueados para esta campanha. Usado apenas quando `do_not_call_list_source` é `custom`.
</ParamField>

<ParamField body="auto_add_to_dnc_enabled" type="boolean" required={false}>
  Quando `true`, contatos que correspondem a `auto_dnc_trigger_statuses` ou `auto_dnc_trigger_errors` são automaticamente adicionados à lista DNC.
</ParamField>

<ParamField body="auto_dnc_trigger_statuses" type="array" required={false}>
  Status de chamada que acionam a adição automática ao DNC. Exemplo: `["completed", "voicemail"]`.
</ParamField>

<ParamField body="auto_dnc_trigger_errors" type="array" required={false}>
  Erros de chamada que acionam a adição automática ao DNC. Exemplo: `["invalid_number", "disconnected"]`.
</ParamField>

## Exemplos

<RequestExample>
  ```bash theme={null}
  # Basic sales campaign — weekdays 09:00–17:00 New York
  curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Sales Campaign Q1",
      "description": "Outbound sales campaign for Q1",
      "campaign_type": "sales",
      "agent_id": "agent-uuid-1",
      "start_date": "2024-01-01",
      "days_of_week": [1, 2, 3, 4, 5],
      "call_time_ranges": [
        {"start": "09:00", "end": "17:00"}
      ],
      "timezone": "America/Sao_Paulo"
    }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Sales Campaign Q1',
      description: 'Outbound sales campaign for Q1',
      campaign_type: 'sales',
      agent_id: 'agent-uuid-1',
      start_date: '2024-01-01',
      days_of_week: [1, 2, 3, 4, 5],
      call_time_ranges: [
        { start: '09:00', end: '17:00' }
      ],
      timezone: 'America/Sao_Paulo'
    })
  });

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

  ```python theme={null}
  import requests

  url = "https://app.talkover.ai/api/v1/campaigns"
  headers = {
      "Authorization": "Bearer talq_your_environment_token_here",
      "Content-Type": "application/json"
  }
  data = {
      "name": "Sales Campaign Q1",
      "description": "Outbound sales campaign for Q1",
      "campaign_type": "sales",
      "agent_id": "agent-uuid-1",
      "start_date": "2024-01-01",
      "days_of_week": [1, 2, 3, 4, 5],
      "call_time_ranges": [
          {"start": "09:00", "end": "17:00"}
      ],
      "timezone": "America/Sao_Paulo"
  }

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

<RequestExample>
  ```bash theme={null}
  # Campaign with split call windows + custom DNC + per-status cooldowns
  curl -X POST "https://app.talkover.ai/api/v1/campaigns" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Follow-up Campaign",
      "campaign_type": "follow_up",
      "agent_id": "agent-uuid-2",
      "start_date": "2024-01-15",
      "end_date": "2024-03-31",
      "days_of_week": [1, 2, 3, 4, 5],
      "call_time_ranges": [
        {"start": "10:00", "end": "12:00"},
        {"start": "14:00", "end": "17:00"}
      ],
      "timezone": "America/Sao_Paulo",
      "max_retries": 5,
      "retry_cooldown_hours": 48,
      "success_cooldown_hours": 168,
      "voicemail_cooldown_hours": 24,
      "no_answer_cooldown_hours": 12,
      "busy_cooldown_hours": 6,
      "failed_cooldown_hours": 72,
      "do_not_call_enabled": true,
      "do_not_call_list_source": "custom",
      "do_not_call_custom_list": ["+5511987654321", "+5511976543210"],
      "auto_add_to_dnc_enabled": true,
      "auto_dnc_trigger_statuses": ["completed"],
      "auto_dnc_trigger_errors": ["invalid_number"]
    }'
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (201 Created)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "campaign-uuid-1",
      "name": "Sales Campaign Q1",
      "description": "Outbound sales campaign for Q1",
      "campaign_type": "sales",
      "status": "draft",
      "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": "09:00", "end": "17:00"}
      ],
      "timezone": "America/Sao_Paulo",
      "max_retries": 3,
      "retry_cooldown_hours": 24,
      "do_not_call_enabled": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a campanha foi criada com sucesso.
</ResponseField>

<ResponseField name="data" type="object" required>
  O objeto da campanha criada. Novas campanhas começam com `status: "draft"`. Use [Atualizar Status da Campanha](/api-reference/endpoints/update-campaign-status) para ativar.
</ResponseField>

## Respostas de erro

### 422 Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "agent_id": ["The selected agent id is invalid."],
      "call_time_ranges": ["The call time ranges field is required."],
      "call_time_ranges.0.end": ["The call time ranges.0.end must be a date after call time ranges.0.start."],
      "days_of_week.0": ["The days of week.0 must be between 1 and 7."]
    }
  }
  ```
</ResponseExample>

### 401 Não Autorizado

<ResponseExample>
  ```json theme={null}
  {
    "message": "Missing Bearer Token"
  }
  ```
</ResponseExample>

### 403 Proibido — Limite do Plano Atingido

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Your plan does not allow creating more campaigns",
    "code": "CAMPAIGN_LIMIT_REACHED"
  }
  ```
</ResponseExample>

## Observações

* O agente da campanha já deve existir. Crie-o via [Criar Agente](/api-reference/endpoints/create-agent).
* `call_time_ranges` substitui os campos antigos `earliest_call_time`/`latest_call_time`. Múltiplas janelas permitem pular o horário de almoço ou dividir entre manhã e tarde.
* Todos os campos `*_cooldown_hours` têm padrão de `24` se não fornecidos. Use-os para ajustar o comportamento de retry por resultado de chamada.
* As janelas de horário são avaliadas no `timezone` da campanha, não no horário local do chamador.

## Endpoints relacionados

* [Listar Campanhas](/api-reference/endpoints/list-campaigns)
* [Obter Campanha](/api-reference/endpoints/get-campaign)
* [Atualizar Campanha](/api-reference/endpoints/update-campaign)
* [Atualizar Status da Campanha](/api-reference/endpoints/update-campaign-status)
* [Realizar Chamada de Campanha](/api-reference/endpoints/make-campaign-call)