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

# Obter Chamadas do Agente

> Recuperar uma lista de chamadas para um agente específico

# Obter Chamadas do Agente

Recuperar uma lista de chamadas para um agente específico com opções de filtragem por status, direção e datas.

## Endpoint

```
GET /api/v1/agents/{agent_id}/calls
```

## Parâmetros de caminho

<ParamField path="agent" type="string" required>
  O identificador único do agente. Você pode encontrá-lo na lista de agentes.
</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>

## Parâmetros de consulta

<ParamField query="status" type="string" required={false}>
  Filtrar por status da chamada. Opções: `initiated`, `ringing`, `answered`, `completed`, `failed`, `busy`, `no-answer`
</ParamField>

<ParamField query="direction" type="string" required={false}>
  Filtrar por direção da chamada. Opções: `inbound`, `outbound`
</ParamField>

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

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

<ParamField query="search" type="string" required={false}>
  Pesquisar em números de telefone ou SID da chamada
</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 chamadas de um agente
  curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 1: Obter todas as chamadas de um agente
  const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls', {
    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 por chamadas completadas
  curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?status=completed&direction=outbound&per_page=50" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 2: Filtrar por chamadas completadas
  const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?status=completed&direction=outbound&per_page=50', {
    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 3: Filtrar por período específico
  curl -X GET "https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?date_from=2024-01-01&date_to=2024-01-31" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 3: Filtrar por período específico
  const response = await fetch('https://app.talkover.ai/api/v1/agents/agent-uuid-1/calls?date_from=2024-01-01&date_to=2024-01-31', {
    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": "uuid",
        "sid": "call_sid_123",
        "to": "+5511987654321",
        "to_formatted": "(123) 456-7890",
        "from": "+0987654321",
        "from_formatted": "(098) 765-4321",
        "is_testing": false,
        "direction": "outbound",
        "status": "completed",
        "duration": 120,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "uuid-2",
        "sid": "call_sid_456",
        "to": "+5511976543210",
        "to_formatted": "(987) 654-3210",
        "from": "+5511987654321",
        "from_formatted": "(123) 456-7890",
        "is_testing": true,
        "direction": "inbound",
        "status": "answered",
        "duration": 85,
        "created_at": "2024-01-01T01:00:00Z",
        "updated_at": "2024-01-01T01:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 20,
      "total": 50,
      "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 chamada.

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

    <ResponseField name="sid" type="string" required>
      SID da chamada do provedor de telefonia.
    </ResponseField>

    <ResponseField name="to" type="string" required>
      Número de telefone de destino em formato E.164.
    </ResponseField>

    <ResponseField name="to_formatted" type="string" required>
      Número de telefone de destino formatado para exibição.
    </ResponseField>

    <ResponseField name="from" type="string" required>
      Número de telefone de origem em formato E.164.
    </ResponseField>

    <ResponseField name="from_formatted" type="string" required>
      Número de telefone de origem formatado para exibição.
    </ResponseField>

    <ResponseField name="is_testing" type="boolean" required>
      Se a chamada é uma chamada de teste.
    </ResponseField>

    <ResponseField name="direction" type="string" required>
      Direção da chamada. Opções: `inbound`, `outbound`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status atual da chamada. Opções: `initiated`, `ringing`, `answered`, `completed`, `failed`, `busy`, `no-answer`.
    </ResponseField>

    <ResponseField name="duration" type="integer">
      Duração da chamada em segundos (quando aplicável).
    </ResponseField>

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

    <ResponseField name="updated_at" type="string" required>
      Timestamp ISO 8601 quando a chamada 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

### 404 Não Encontrado

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

### 422 Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "status": [
        "The selected status is invalid."
      ],
      "direction": [
        "The selected direction is invalid."
      ],
      "date_from": [
        "The date from field must be a valid date."
      ],
      "date_to": [
        "The date to field must be a valid date."
      ]
    }
  }
  ```
</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 |
| ------------------ | ------------------------------------------- | ----------- |
| `AGENT_NOT_FOUND`  | Agente especificado não existe              | 404         |
| `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 específicos do agente.** Este endpoint filtra automaticamente as chamadas pelo agente especificado.
</Info>

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

<Info>
  **Filtros de data.** Use `date_from` e `date_to` para filtrar chamadas por período específico.
</Info>

<Info>
  **Análise de desempenho.** Use este endpoint para analisar o desempenho de agentes específicos.
</Info>

## Melhores Práticas

1. **Use paginação** - Sempre use paginação para grandes conjuntos de dados
2. **Filtre por período** - Use filtros de data para analisar chamadas em períodos específicos
3. **Monitore status** - Filtre por status para acompanhar o progresso das chamadas
4. **Analise desempenho** - Use este endpoint para avaliar o desempenho de agentes específicos
5. **Identifique testes** - Use `is_testing` para separar chamadas de teste das de produção

## Endpoints relacionados

* **Listar Chamadas**: `GET /api/v1/calls`
* **Obter Agente**: `GET /api/v1/agents/{agent_id}`
* **Fazer Chamada**: `POST /api/v1/calls`
* **Listar Agentes**: `GET /api/v1/agents`