Listar Eventos de uma Chamada

O endpoint GET /api/calls/{id}/events retorna a linha do tempo completa de uma chamada: início e fim, entradas, saídas, reconexões e desconexões de participantes. Use-o para auditoria, análise de qualidade e relatórios detalhados de participação.

Requisição

GET /api/calls/{id}/events

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

Parâmetros de consulta:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	Filtra os eventos por um tipo específico (veja a lista de tipos abaixo)

Exemplos

cURL

# Listar todos os eventos
curl -X GET "https://api.videochamada.com.br/api/calls/9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f/events" \
  -H "Authorization: Bearer SUA_API_KEY"

# Filtrar apenas eventos de entrada
curl -X GET "https://api.videochamada.com.br/api/calls/9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f/events?type=participant_joined" \
  -H "Authorization: Bearer SUA_API_KEY"

Python (requests)

import requests

call_id = "9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f"

# Listar todos os eventos
response = requests.get(
    f"https://api.videochamada.com.br/api/calls/{call_id}/events",
    headers={"Authorization": "Bearer SUA_API_KEY"},
)

# Filtrar por tipo
filtered = requests.get(
    f"https://api.videochamada.com.br/api/calls/{call_id}/events",
    headers={"Authorization": "Bearer SUA_API_KEY"},
    params={"type": "participant_joined"},
)
print(response.json())

Node.js (axios)

const axios = require('axios');

const callId = '9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f';

// Listar todos os eventos
const response = await axios.get(
  `https://api.videochamada.com.br/api/calls/${callId}/events`,
  { headers: { Authorization: 'Bearer SUA_API_KEY' } },
);

// Filtrar por tipo
const filtered = await axios.get(
  `https://api.videochamada.com.br/api/calls/${callId}/events`,
  {
    headers: { Authorization: 'Bearer SUA_API_KEY' },
    params: { type: 'participant_joined' },
  },
);
console.log(response.data);

Resposta

A resposta é um array direto de eventos (não um objeto com data), ordenado do mais recente para o mais antigo. Se o seu processamento depende da ordem cronológica, reordene pelo campo timestamp no seu lado.

Exemplo de resposta:

[
  {
    "id": "8b9c0d1e-2f3a-4b4c-d5e6-f7a8b9c0d1e2",
    "type": "participant_left",
    "participantName": "Maria Santos",
    "sessionId": "a9b8c7d6-e5f4-4a3b-2c1d-0e9f8a7b6c5d",
    "timestamp": "2026-08-30T10:35:30.000Z"
  },
  {
    "id": "7a8b9c0d-1e2f-4a3b-c4d5-e6f7a8b9c0d1",
    "type": "disconnected",
    "participantName": "João Silva",
    "sessionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
    "timestamp": "2026-08-30T10:35:00.000Z"
  },
  {
    "id": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0",
    "type": "participant_joined",
    "participantName": "Maria Santos",
    "sessionId": "a9b8c7d6-e5f4-4a3b-2c1d-0e9f8a7b6c5d",
    "timestamp": "2026-08-30T10:06:15.000Z"
  },
  {
    "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
    "type": "participant_joined",
    "participantName": "João Silva",
    "sessionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
    "timestamp": "2026-08-30T10:05:02.000Z"
  }
]

Campos do objeto de evento:

Campo	Descrição
`id`	Identificador único do evento
`type`	Tipo do evento (veja a lista abaixo)
`participantName`	Nome do participante relacionado ao evento (quando aplicável)
`sessionId`	ID da sessão do participante (quando aplicável)
`timestamp`	Data e hora em que o evento foi registrado pela API (em reenvios do servidor de sinalização, pode diferir em alguns segundos do momento exato da ocorrência)

Tipos de evento

Tipo	Significado
`call_started`	A mídia (áudio/vídeo) foi conectada e a chamada efetivamente começou — é o sinal de mídia, não a entrada na sala (a entrada é `participant_joined`)
`call_ended`	A chamada foi encerrada
`participant_joined`	Um participante entrou na chamada
`participant_left`	Um participante saiu da chamada
`participant_reconnected`	Um participante reconectou após uma queda
`disconnected`	Um participante foi desconectado inesperadamente
`participant_rejected`	Alguém tentou entrar e foi recusado porque a sala já estava cheia. Este evento é apenas observacional: aparece aqui, mas nunca é enviado a webhooks e a pessoa recusada não conta como participante

Eventos REST vs. eventos de webhook

Os tipos deste endpoint usam underscore (call_started, participant_joined, ...). Já os eventos de ciclo de vida enviados por webhook usam ponto: call.created, call.ended e call.reset. Ao configurar seus webhooks, confira a nomenclatura exata em Configuração de Webhooks.

Erros

Status	Mensagem	Quando ocorre
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

Rastreamento de participação: combine eventos participant_joined e participant_left para calcular o tempo de permanência de cada participante — ou use diretamente o endpoint de participantes, que já entrega isso calculado.
Análise de qualidade: eventos disconnected e participant_reconnected frequentes podem indicar problemas de conexão dos participantes.
Dimensionamento de salas: eventos participant_rejected indicam que a sala atingiu o limite de participantes — sinal de que o limite configurado pode estar baixo para o seu caso de uso.
Auditoria: persista os eventos no seu sistema para investigações e trilhas de auditoria.