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

# Listar Campanhas

> Recuperar uma lista de campanhas para o ambiente autenticado

# Listar Campanhas

Recuperar uma lista de campanhas para o ambiente autenticado com opções de filtragem por status, tipo de campanha, agente e datas.

## Endpoint

```
GET /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>

## Parâmetros de consulta

<ParamField query="status" type="string" required={false}>
  Filtrar por status da campanha. Opções: `draft`, `active`, `paused`, `completed`, `cancelled`
</ParamField>

<ParamField query="campaign_type" type="string" required={false}>
  Filtrar por tipo de campanha. Opções: `sales`, `follow_up`, `reminder`, `custom`
</ParamField>

<ParamField query="agent_id" type="string" required={false}>
  Filtrar por ID do agente.
</ParamField>

<ParamField query="date_from" type="string" required={false}>
  Filtrar campanhas a partir da data (formato: YYYY-MM-DD).
</ParamField>

<ParamField query="date_to" type="string" required={false}>
  Filtrar campanhas até a data (formato: YYYY-MM-DD).
</ParamField>

<ParamField query="search" type="string" required={false}>
  Pesquisar no nome ou descrição da campanha.
</ParamField>

<ParamField query="per_page" type="integer" required={false}>
  Número de itens por página (padrão: 20, máximo: 100).
</ParamField>

<ParamField query="page" type="integer" required={false}>
  Número da página (padrão: 1).
</ParamField>

## Exemplos de Requisição

<RequestExample>
  ```bash theme={null}
  # Requisição 1: Obter todas as campanhas
  curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 1: Obter todas as campanhas
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Requisição 2: Filtrar campanhas ativas de vendas
  curl -X GET "https://app.talkover.ai/api/v1/campaigns?status=active&campaign_type=sales&per_page=50" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 2: Filtrar campanhas ativas de vendas
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns?status=active&campaign_type=sales&per_page=50', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "campaign-uuid-1",
        "name": "Campanha de Vendas Q1",
        "description": "Campanha de vendas outbound para Q1",
        "status": "active",
        "campaign_type": "sales",
        "start_date": "2024-01-01",
        "days_of_week": [1, 2, 3, 4, 5],
        "earliest_call_time": "09:00:00",
        "latest_call_time": "17:00:00",
        "timezone": "America/Sao_Paulo",
        "agent_id": "agent-uuid-1",
        "initial_call_delay": 0,
        "max_retries": 3,
        "retry_cooldown_hours": 24,
        "agent": {
          "id": "agent-uuid-1",
          "name": "Agente de Vendas",
          "label": "Agente de Vendas Label"
        },
        "stats": {
          "total_calls": 100,
          "completed_calls": 80,
          "failed_calls": 20,
          "success_rate": 80.0
        },
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 20,
      "total": 100,
      "from": 1,
      "to": 20
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a operação foi bem-sucedida.
</ResponseField>

<ResponseField name="data" type="array" required>
  Array de objetos de campanha.

  <Expandable title="Objeto de Campanha">
    <ResponseField name="id" type="string" required>
      Identificador único da campanha.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Nome da campanha.
    </ResponseField>

    <ResponseField name="description" type="string">
      Descrição da campanha.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status da campanha. Opções: `draft`, `active`, `paused`, `completed`, `cancelled`.
    </ResponseField>

    <ResponseField name="campaign_type" type="string" required>
      Tipo da campanha. Opções: `sales`, `follow_up`, `reminder`, `custom`.
    </ResponseField>

    <ResponseField name="start_date" type="string" required>
      Data de início da campanha (formato: YYYY-MM-DD).
    </ResponseField>

    <ResponseField name="days_of_week" type="array" required>
      Array de dias da semana (1=Segunda, 7=Domingo).
    </ResponseField>

    <ResponseField name="earliest_call_time" type="string" required>
      Horário mais cedo para fazer chamadas (formato: HH:MM:SS).
    </ResponseField>

    <ResponseField name="latest_call_time" type="string" required>
      Horário mais tarde para fazer chamadas (formato: HH:MM:SS).
    </ResponseField>

    <ResponseField name="timezone" type="string" required>
      Fuso horário para agendamento de chamadas.
    </ResponseField>

    <ResponseField name="agent_id" type="string" required>
      ID do agente atribuído à campanha.
    </ResponseField>

    <ResponseField name="initial_call_delay" type="integer" required>
      Atraso inicial da chamada em segundos.
    </ResponseField>

    <ResponseField name="max_retries" type="integer" required>
      Número máximo de tentativas.
    </ResponseField>

    <ResponseField name="retry_cooldown_hours" type="integer" required>
      Tempo de espera entre tentativas em horas.
    </ResponseField>

    <ResponseField name="agent" type="object" required>
      Informações do agente.

      <Expandable title="Objeto do Agente">
        <ResponseField name="id" type="string" required>
          ID do agente.
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Nome do agente.
        </ResponseField>

        <ResponseField name="label" type="string" required>
          Label do agente.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stats" type="object" required>
      Estatísticas da campanha.

      <Expandable title="Objeto de Estatísticas">
        <ResponseField name="total_calls" type="integer" required>
          Número total de chamadas.
        </ResponseField>

        <ResponseField name="completed_calls" type="integer" required>
          Número de chamadas completadas.
        </ResponseField>

        <ResponseField name="failed_calls" type="integer" required>
          Número de chamadas falhadas.
        </ResponseField>

        <ResponseField name="success_rate" type="number" required>
          Taxa de sucesso em porcentagem.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      Timestamp ISO 8601 quando a campanha foi criada.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      Timestamp ISO 8601 quando a campanha foi atualizada pela última vez.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Metadados de paginação.

  <Expandable title="Objeto de Paginação">
    <ResponseField name="current_page" type="integer" required>
      Número da página atual.
    </ResponseField>

    <ResponseField name="last_page" type="integer" required>
      Número da última página.
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Número de itens por página.
    </ResponseField>

    <ResponseField name="total" type="integer" required>
      Número total de itens.
    </ResponseField>

    <ResponseField name="from" type="integer" required>
      Número do item inicial da página atual.
    </ResponseField>

    <ResponseField name="to" type="integer" required>
      Número do item final da página atual.
    </ResponseField>
  </Expandable>
</ResponseField>

## Respostas de erro

### 422 Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "status": [
        "The selected status is invalid."
      ],
      "campaign_type": [
        "The selected campaign type is invalid."
      ]
    }
  }
  ```
</ResponseExample>

### 401 Não Autorizado

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

### 500 Erro do Servidor

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## Códigos de erro

| Código             | Descrição                                   | Status HTTP |
| ------------------ | ------------------------------------------- | ----------- |
| `VALIDATION_ERROR` | Validação dos parâmetros de consulta falhou | 422         |
| `INVALID_TOKEN`    | Token de autenticação inválido ou ausente   | 401         |
| `SERVER_ERROR`     | Erro interno do servidor ocorreu            | 500         |

## Notas Importantes

<Info>
  **Filtros disponíveis.** Use filtros para encontrar campanhas específicas por status, tipo ou agente.
</Info>

<Info>
  **Estatísticas incluídas.** Cada campanha inclui estatísticas de desempenho.
</Info>

<Info>
  **Suporte à paginação.** Use parâmetros `page` e `per_page` para navegar pelos resultados.
</Info>

<Info>
  **Pesquisa de texto.** Use o parâmetro `search` para pesquisar no nome ou descrição.
</Info>

## Melhores Práticas

1. **Use filtros** - Aproveite os filtros para encontrar campanhas específicas
2. **Monitore estatísticas** - Acompanhe as estatísticas de desempenho das campanhas
3. **Use paginação** - Sempre use paginação para grandes conjuntos de dados
4. **Pesquise eficientemente** - Use pesquisa de texto para encontrar campanhas rapidamente
5. **Verifique status** - Monitore o status das campanhas regularmente

## Endpoints relacionados

* **Criar Campanha**: `POST /api/v1/campaigns`
* **Obter Campanha**: `GET /api/v1/campaigns/{campaign_id}`
* **Atualizar Campanha**: `PUT /api/v1/campaigns/{campaign_id}`
* **Atualizar Status da Campanha**: `PATCH /api/v1/campaigns/{campaign_id}/status`
* **Excluir Campanha**: `DELETE /api/v1/campaigns/{campaign_id}`
* **Fazer Chamada de Campanha**: `POST /api/v1/campaigns/{campaign_id}/call`