Controle de Gravação Durante a Chamada

Os endpoints POST /api/calls/{id}/recordings e DELETE /api/calls/{id}/recordings permitem habilitar e desabilitar a gravação de uma chamada em andamento. Isso é útil para fluxos de consentimento: você pode criar a chamada sem gravação, pedir o consentimento dos participantes e só então habilitar — ou desabilitar imediatamente se o consentimento for revogado.

Como a gravação é decidida

A gravação de uma chamada pode ser definida em três níveis:

1. Padrão do projeto — a configuração de gravação do projeto vale para chamadas que não definirem nada.
2. Na criação da chamada — o campo recording (booleano) no corpo de POST /api/calls sobrescreve o padrão do projeto para aquela chamada.
3. Durante a chamada — os endpoints desta página habilitam ou desabilitam a gravação a qualquer momento, sobrescrevendo os dois anteriores.

Quando você habilita ou desabilita a gravação em uma chamada em andamento, os aplicativos dos participantes são notificados em tempo real: a gravação começa (ou para) imediatamente, sem que ninguém precise recarregar a página.

Desabilitar gravação

Desabilita a gravação da chamada — por exemplo, quando um participante revoga o consentimento. Os participantes conectados são notificados em tempo real e param de gravar imediatamente. Credenciais de upload já emitidas para trechos anteriores podem continuar válidas por algumas horas, então fragmentos em trânsito ainda podem ser concluídos — mas nenhuma gravação nova é iniciada.

Os arquivos já gravados até o momento não são apagados: eles seguem o ciclo normal de processamento e a política de retenção do projeto.

Requisição

DELETE https://api.videochamada.com.br/api/calls/{id}/recordings

Cabeçalhos:

Authorization: Bearer {API_TOKEN}

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
id	string (path)	Sim	ID da chamada

Exemplos

curl -X DELETE "https://api.videochamada.com.br/api/calls/{id}/recordings" \
  -H "Authorization: Bearer {API_TOKEN}"

import requests

response = requests.delete(
    "https://api.videochamada.com.br/api/calls/{id}/recordings",
    headers={"Authorization": "Bearer {API_TOKEN}"},
)
print(response.json())  # {"disabled": true}

const response = await fetch(
  'https://api.videochamada.com.br/api/calls/{id}/recordings',
  {
    method: 'DELETE',
    headers: { Authorization: 'Bearer {API_TOKEN}' },
  },
);
const { disabled } = await response.json(); // true

Resposta

{
  "disabled": true
}

Campo	Tipo	Descrição
disabled	boolean	true confirmando que a gravação foi desabilitada

Operação idempotente

Desabilitar uma chamada que não está gravando também retorna {"disabled": true}. É seguro repetir a requisição.

Trate falhas repetindo a requisição

Se a notificação em tempo real aos participantes falhar momentaneamente, a requisição retorna erro — mas o estado de gravação desabilitada já fica persistido. Repita a requisição até receber {"disabled": true} para garantir que os participantes conectados também foram notificados a parar.

Erros

Status	Mensagem	Quando
404	Call not found	A chamada não existe
403	Call does not belong to this project	A chamada pertence a outro projeto (API key incorreta)

Boas práticas

• Fluxo de consentimento: crie a chamada com "recording": false, colete o consentimento dos participantes (por exemplo, via sua própria interface) e chame POST .../recordings quando todos aceitarem.
• Revogação imediata: ao receber uma revogação de consentimento, chame DELETE .../recordings imediatamente — os participantes param de gravar em tempo real.
• Guarde o id da gravação: o id retornado ao habilitar identifica a gravação da chamada e pode ser correlacionado com a listagem de gravações depois do término.