# Ligar, aceitar ou desligar o vídeo de uma ligação

`POST /call/video`

Ação de vídeo numa chamada atendida da instância calls. Exige capabilities.calls_video=true. start em chamada de áudio pede vídeo ao contato e fica pending até a resposta; em chamada que já negociou vídeo reabre a câmera. accept responde ao pedido do contato (videoState.requested). stop desliga a câmera deste lado sem encerrar a chamada nem o vídeo do contato. Os quadros trafegam por GET /call/{id}/video. Recurso experimental: o caminho de mídia de vídeo do motor ainda não foi homologado em laboratório.

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

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

Formato: `application/json`. Corpo obrigatório.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `callId` | `string` | obrigatório | Comprimento mínimo: `1` |
| `action` | `string` | obrigatório | start liga a câmera deste lado: em chamada só de áudio vira pedido ao contato (pending até a resposta); em chamada que já negociou vídeo apenas reabre o fluxo. accept aceita o pedido do contato (videoState.requested). stop desliga a câmera deste lado ou retira o pedido pendente; o vídeo do contato e o áudio continuam. Valores: `"start"`, `"accept"`, `"stop"` |

## Resposta 200

Estado da chamada após a ação, com videoState.

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

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_call_id, invalid_video_action ou invalid_json.

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

call_not_found.

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

wrong_instance_kind, not_connected, owned_elsewhere ou invalid_call_state (chamada não atendida, já encerrada, ou accept sem pedido do contato).

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

calls_not_supported: módulo desligado; calls_video_not_supported: vídeo desligado no worker (ATENDROZAP_CALLS_VIDEO_ENABLED) ou motor sem vídeo.

| 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": "calls_not_supported"
}
```

## Resposta 502

call_failed: o motor recusou a transiçã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). |

## 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 POST "$ATENDROZAP_URL/call/video" \
  --header "token: $ATENDROZAP_INSTANCE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "callId": "CHAMADA_DE_TESTE",
  "action": "start"
}'
```

### JavaScript

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

const response = await fetch(url, {
  method: "POST",
  headers: {
    "token": process.env.ATENDROZAP_INSTANCE_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "callId": "CHAMADA_DE_TESTE",
    "action": "start"
  }),
});

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

## Relacionados

- [Chamadas de voz e vídeo](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)