Encerrar Chamada

O endpoint POST /api/calls/{id}/end encerra uma chamada do seu projeto: o status muda para ended, o link deixa de funcionar e os participantes conectados são avisados em tempo real e removidos da sala.

Requisição

POST /api/calls/{id}/end

Cabeçalhos:

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer SUA_API_KEY`

Parâmetros de caminho:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string (UUID)	Sim	Identificador da chamada

Este endpoint não recebe corpo.

O que acontece ao encerrar

A chamada é marcada como ended e o link é invalidado permanentemente — o encerramento via API é sempre definitivo.
Os participantes ainda conectados são notificados em tempo real e removidos da sala. O campo participantsNotified da resposta indica se essa notificação foi entregue ao servidor de tempo real.
Os webhooks configurados no projeto são disparados: o evento de sessão call_ended e o evento de ciclo de vida call.ended (veja Configuração de Webhooks).
Se a gravação estava habilitada, o processamento das gravações e transcrições é iniciado.

Projetos com link reutilizável

Em projetos configurados com o modo de encerramento de link reutilizável, os encerramentos feitos de dentro da própria sala apenas resetam a sala — o link continua válido para uma próxima conversa e o webhook disparado é call.reset. O encerramento por este endpoint da API, porém, é sempre definitivo e invalida o link.

Exemplos

cURL

curl -X POST "https://api.videochamada.com.br/api/calls/9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f/end" \
  -H "Authorization: Bearer SUA_API_KEY"

Python (requests)

import requests

call_id = "9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f"
response = requests.post(
    f"https://api.videochamada.com.br/api/calls/{call_id}/end",
    headers={"Authorization": "Bearer SUA_API_KEY"},
)
print(response.json())

Node.js (axios)

const axios = require('axios');

const callId = '9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f';
const response = await axios.post(
  `https://api.videochamada.com.br/api/calls/${callId}/end`,
  null,
  { headers: { Authorization: 'Bearer SUA_API_KEY' } },
);
console.log(response.data);

Resposta

Exemplo de resposta:

{
  "message": "Call ended successfully",
  "call": {
    "id": "9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f",
    "created": "2026-08-30T10:00:00.000Z",
    "updated": "2026-08-30T10:35:00.000Z",
    "deleted": null,
    "started": "2026-08-30T10:05:00.000Z",
    "ended": "2026-08-30T10:35:00.000Z",
    "expiresAt": "2026-08-30T12:00:00.000Z",
    "status": "ended",
    "totalBillableMinutes": "30.50",
    "projectId": "c4a1e9d2-3b5f-4a6c-8d7e-9f0a1b2c3d4e",
    "recording": true
  },
  "participantsNotified": true
}

Campos:

Campo	Descrição
`message`	Confirmação do encerramento (`Call ended successfully`)
`call`	Objeto da chamada encerrada
`call.status`	Sempre `ended` após o encerramento
`call.ended`	Data e hora do encerramento
`call.totalBillableMinutes`	Total de minutos faturáveis, como string decimal (ex.: `"30.50"`)
`participantsNotified`	`true` se os participantes conectados foram notificados em tempo real do encerramento; `false` se a notificação falhou (a chamada é encerrada mesmo assim)

Erros

Status	Mensagem	Quando ocorre
400	`Call is already ended`	A chamada já estava encerrada
401	`Invalid API key`	Chave inválida ou revogada, ou IP fora da lista de IPs permitidos da chave
401	`Call does not belong to this project`	A chamada existe, mas pertence a outro projeto
404	`Call not found`	Não existe chamada com esse `id`

Boas práticas

Verifique o status antes de encerrar: consulte GET /api/calls/{id}/status para evitar o erro Call is already ended.
Trate participantsNotified: false: a chamada foi encerrada, mas os participantes podem não ter recebido o aviso imediato — considere reexibir a informação no seu sistema.
Encerre chamadas ociosas: encerrar chamadas que não serão mais usadas invalida links pendentes e mantém seus relatórios limpos. Chamadas com expiresAt também são encerradas automaticamente após a expiração (exceto em projetos com link reutilizável, em que a expiração reinicia a sala via call.reset).
Auditoria: registre no seu sistema quem solicitou o encerramento e quando.

O encerramento é definitivo

Uma vez encerrada pela API, a chamada não pode ser reaberta e o link não volta a funcionar. Certifique-se de que os participantes concluíram a conversa antes de encerrar.