Listar Participantes de uma Chamada

O endpoint GET /api/calls/{id}/participants lista todos os participantes da chamada — ativos e que já saíram — com o histórico individual de cada um. Para ver apenas quem está conectado agora, use o campo active ou o endpoint de status.

Requisição

GET /api/calls/{id}/participants

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

Exemplos

cURL

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

Python (requests)

import requests

call_id = "9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f"
response = requests.get(
    f"https://api.videochamada.com.br/api/calls/{call_id}/participants",
    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.get(
  `https://api.videochamada.com.br/api/calls/${callId}/participants`,
  { headers: { Authorization: 'Bearer SUA_API_KEY' } },
);
console.log(response.data);

Resposta

A resposta é um array direto de participantes (não um objeto com data). Uma chamada sem participantes retorna [].

Exemplo de resposta:

[
  {
    "sessionId": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
    "username": "João Silva",
    "firstSeen": "2026-08-30T10:05:02.000Z",
    "lastSeen": "2026-08-30T10:20:15.000Z",
    "joinedAt": "2026-08-30T10:05:02.000Z",
    "active": true,
    "events": [
      {
        "type": "participant_joined",
        "timestamp": "2026-08-30T10:05:02.000Z"
      }
    ]
  },
  {
    "sessionId": "a9b8c7d6-e5f4-4a3b-2c1d-0e9f8a7b6c5d",
    "username": "Maria Santos",
    "firstSeen": "2026-08-30T10:06:15.000Z",
    "lastSeen": "2026-08-30T10:15:30.000Z",
    "joinedAt": "2026-08-30T10:06:15.000Z",
    "leftAt": "2026-08-30T10:15:30.000Z",
    "active": false,
    "durationMinutes": 9.25,
    "events": [
      {
        "type": "participant_joined",
        "timestamp": "2026-08-30T10:06:15.000Z"
      },
      {
        "type": "participant_left",
        "timestamp": "2026-08-30T10:15:30.000Z"
      }
    ]
  }
]

Campos do objeto de participante:

Campo	Descrição
sessionId	ID único da sessão do participante
username	Nome informado pelo participante ao entrar na chamada
firstSeen	Data e hora do primeiro evento registrado do participante
lastSeen	Data e hora do último evento registrado do participante
joinedAt	Data e hora em que o participante entrou na chamada
leftAt	Data e hora em que o participante saiu ou foi desconectado (ausente enquanto ele estiver ativo)
active	true se o participante está conectado neste momento
durationMinutes	Tempo de permanência em minutos, calculado entre joinedAt e leftAt (presente apenas depois que o participante sai)
events	Histórico de eventos deste participante
events[].type	Tipo do evento (participant_joined, participant_left, participant_reconnected, disconnected)
events[].timestamp	Data e hora do evento

Participantes recusados por sala cheia não aparecem

Quem tentou entrar e foi recusado porque a sala já estava lotada não é listado aqui — essa pessoa nunca chegou a ser um participante. Essas tentativas ficam registradas apenas como evento participant_rejected no endpoint de eventos.

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

• Filtrar ativos: para saber quem está na chamada agora, filtre por active: true ou use diretamente o endpoint de status.
• Relatórios de participação: os campos joinedAt, leftAt e durationMinutes permitem montar a lista de presença completa de uma chamada encerrada.
• Polling moderado: se precisar consultar periodicamente, respeite intervalos de pelo menos 5 segundos entre requisições.

Diferença entre participantes e eventos

Endpoint	Propósito	Dados retornados
/api/calls/{id}/participants	Visão por participante, com histórico individual	Todos os participantes (ativos e que já saíram), cada um com seus eventos
/api/calls/{id}/events	Timeline da chamada inteira	Todos os eventos, do mais recente para o mais antigo

Dica

Use /participants para responder "quem participou, quando entrou e quando saiu". Use /events para reconstruir a linha do tempo completa da chamada.