# CallHistory

Estrutura de dados do contrato OpenAPI.

## Campos

| 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, unknown ou motivo do motor. Um terminate remoto sem motivo explícito (ausente, vazio ou só espaços) é hangup/remote: solicitação remota de encerramento, sem comprovar ação humana. Motivos explícitos são preservados; callbacks genéricos sem motivo continuam unknown. O primeiro motivo fica no histórico; registros antigos não são reclassificados. |
| `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). |
| `calls[].video` | `boolean` | obrigatório | Verdadeiro quando a chamada é ou foi de vídeo (negociado em qualquer direção em algum momento). Permanece no histórico. |
| `calls[].videoState` | `object` | opcional | Estado vivo do vídeo; presente apenas enquanto a chamada não terminou. Os campos sending/receiving refletem o fluxo negociado, não quadros efetivamente trafegando. Modelo: [CallVideoState](https://wpp.atendro.cloud/docs/modelos/call-video-state.md). |
| `calls[].videoRecording` | `object` | opcional | Gravação de vídeo independente do WAV. Campo opcional, presente somente após começar a captura de vídeo. processing indica composição do MP4 em fila após a chamada; não muda o estado ou a ocupação de ligações. O primeiro resultado terminal é preservado. Modelo: [CallVideoRecording](https://wpp.atendro.cloud/docs/modelos/call-video-recording.md). |
| `calls[].incomingCallMode` | `string` | opcional | Comportamento para novas chamadas recebidas: allow permite atendimento humano; reject recusa no servidor; reject_reply recusa e solicita ao consumidor resposta por uma conexão de mensagens vinculada. Não atende automaticamente. O envio do texto é independente da recusa. Modelo: [IncomingCallMode](https://wpp.atendro.cloud/docs/modelos/incoming-call-mode.md). Valores: `"allow"`, `"reject"`, `"reject_reply"` |
| `calls[].callsConfigVersion` | `integer` | opcional | Versão da política congelada na chegada da chamada recebida. Não é seq do evento; mudanças de configuração posteriores não alteram esta decisão. Mínimo: `0`. Formato: `int64` |
| `calls[].rejectionSource` | `string` | opcional | Origem de uma recusa confirmada: política automática, ocupação ou operador. Não confundir com timeout, desligamento remoto ou atendimento em outro dispositivo. Valores: `"policy"`, `"busy"`, `"manual"` |
| `calls[].autoReplyRequested` | `boolean` | opcional | Verdadeiro somente após recusa confirmada por política reject_reply. O consumidor enfileira o texto uma única vez por instância/chamada; este campo não comprova envio da resposta. |
| `hasMore` | `boolean` | obrigatório | — |
| `nextCursor` | `string` | obrigatório | Usar como before na próxima página; vazio quando não há mais resultados. |

## Definição OpenAPI

```json
{
  "type": "object",
  "required": [
    "calls",
    "hasMore",
    "nextCursor"
  ],
  "properties": {
    "calls": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Call"
      }
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextCursor": {
      "type": "string",
      "description": "Usar como before na próxima página; vazio quando não há mais resultados."
    }
  },
  "additionalProperties": false
}
```