# Consultar histórico de chamadas

`GET /call/history`

Histórico persistente da instância, do mais novo ao mais antigo. Independente da conexão e da retenção de eventos/áudio. Paginação por before/nextCursor; não aceita token na query.

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

## Parâmetros de consulta

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `limit` | `integer` | opcional | Itens por página. Padrão: `50`. Mínimo: `1`. Máximo: `100` |
| `before` | `string` | opcional | Cursor nextCursor da página anterior. |
| `direction` | `string` | opcional | Direção da chamada. Valores: `"inbound"`, `"outbound"` |
| `answered` | `boolean` | opcional | Filtra pela ocorrência do atendimento. |
| `status` | `string` | opcional | Estado atual/final. Valores: `"ringing"`, `"connecting"`, `"active"`, `"ended"` |
| `from` | `string` | opcional | Início do intervalo, inclusivo. Formato: `date-time` |
| `to` | `string` | opcional | Fim do intervalo, exclusivo. Formato: `date-time` |

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

Não há corpo de requisição definido para esta operação.

## Resposta 200

Página do histórico.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `calls` | `array<object>` | obrigatório | — |
| `calls[].callId` | `string` | obrigatório | — |
| `calls[].direction` | `string` | obrigatório | Valores: `"inbound"`, `"outbound"` |
| `calls[].number` | `string` | obrigatório | Identidade telefônica canônica, quando conhecida. |
| `calls[].jid` | `string` | opcional | — |
| `calls[].status` | `string` | obrigatório | Valores: `"ringing"`, `"connecting"`, `"active"`, `"ended"` |
| `calls[].startedAt` | `string` | obrigatório | Formato: `date-time` |
| `calls[].answeredAt` | `string` | opcional | Momento do aceite remoto ou do atendimento local; não depende do primeiro áudio. Formato: `date-time` |
| `calls[].endedAt` | `string` | opcional | Formato: `date-time` |
| `calls[].endReason` | `string` | opcional | hangup, rejected, ring_timeout, closed ou motivo do motor. |
| `calls[].endedBy` | `string` | opcional | Valores: `"local"`, `"remote"` |
| `calls[].answered` | `boolean` | opcional | Verdadeiro a partir do aceite, mesmo antes de o áudio iniciar. |
| `calls[].mediaStartedAt` | `string` | opcional | Momento em que o motor confirmou mídia recebida. Formato: `date-time` |
| `calls[].durationSeconds` | `number` | opcional | Tempo entre atendimento e encerramento; zero para chamadas sem atendimento ou ainda em curso. Mínimo: `0` |
| `calls[].recording` | `object` | opcional |  Modelo: [CallRecording](https://wpp.atendro.cloud/docs/modelos/call-recording.md). |
| `hasMore` | `boolean` | obrigatório | — |
| `nextCursor` | `string` | obrigatório | Usar como before na próxima página; vazio quando não há mais resultados. |

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

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

## 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, not_connected, owned_elsewhere ou invalid_call_state; conferir 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). |

## Resposta default

Falha; usar HTTP status e error. 404 rota inexistente; 405 método inválido com Allow. Ver catálogo no guia de integração.

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

## 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 GET "$ATENDROZAP_URL/call/history" \
  --header "token: $ATENDROZAP_INSTANCE_TOKEN"
```

### JavaScript

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

const response = await fetch(url, {
  method: "GET",
  headers: {
    "token": process.env.ATENDROZAP_INSTANCE_TOKEN
  },
});

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

## Relacionados

- [Chamadas de voz](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)