ReferênciaAPI do servidor RTC
URL base: https://api.rtc.champrep.com
Esta referência abrange as rotas de integração suportadas por APIchaves de projeto do RTC. O login no Console, a configuração da organização, a administração de chaves e as operações de administração da plataforma não são rotas de integração com chaves de servidor. Gerencie-as por meio da interface de usuário apropriada, em vez de copiar tokens de sessão do navegador para scripts.
Enviar Authorization: Bearer YOUR_RTC_API_KEY e, para corpos JSON,
Content-Type: application/json. Os exemplos utilizam placeholders, nunca credenciais funcionais. As chaves permanecem restritas ao acesso do respectivo projeto e do plano atual.
Convenções de solicitação e resposta
Seção intitulada “Convenções de solicitação e resposta”- Os IDs são strings UUID. Utilize os IDs retornados pelo RTC, e não os nomes de exibição.
- Os nomes são truncados e aceitam de 1 a 80 caracteres.
- Os corpos JSON estão limitados a 64 KiB e rejeitam campos desconhecidos.
- Os endpoints de lista retornam matrizes JSON, com os mais recentes em primeiro lugar.
?limit(1-200) define o tamanho da página; quando houver mais itens, oX-Next-CursorO cabeçalho de resposta contém o cursor a ser devolvido como?cursor. - Não confie em campos de resposta não documentados nem construa URLs de mídia/armazenamento.
- As mutações não oferecem um contrato geral de idempotência de chave. Reconcilie os resultados antes de tentar novamente após um tempo limite ou perda de conexão.
Resumo dos métodos
Seção intitulada “Resumo dos métodos”| Método e caminho | Escopo necessário | Resultado |
|---|---|---|
GET /v1/projects | Qualquer chave de projeto válida | Matriz filtrada pelo projeto |
GET /v1/rooms | rooms:read | Matriz de salas |
POST /v1/rooms | rooms:write | 201, sala criada |
POST /v1/rooms/{roomId}/end | rooms:write | { "ended": true } |
POST /v1/rooms/{roomId}/tokens | tokens:write | Conjunto de credenciais dos participantes |
GET /v1/recordings | recordings:read | Matriz de gravações |
POST /v1/recordings | recordings:write | 202, gravação em fila |
POST /v1/recordings/{recordingId}/stop | recordings:write | { "stopping": true } |
POST /v1/recordings/{recordingId}/tracks/{trackId}/download | recordings:read | URL temporária para download |
POST /v1/recordings/{recordingId}/transcript | recordings:write | 202, a transcrição é solicitada (transcrição) |
GET /v1/recordings/{recordingId}/transcript | recordings:read | A transcrição em formato JSON ou um arquivo com ?format=vtt, srt ou txt |
GET /v1/transcripts | recordings:read | Suas transcrições e seus status, sem texto |
GET /v1/usage | Qualquer chave de projeto válida | Uso concluído e cotas |
GET /v1/webhooks/endpoints, GET /v1/webhooks/deliveries | webhooks:read | Endpoints e o registro de entrega (webhooks) |
POST, PATCH /v1/webhooks/endpoints…, reproduções e testes | webhooks:write | Gerencie endpoints (webhooks) |
POST /v1/join | Nenhum (um token de adesão) | Conjunto de credenciais do participante (tokens de adesão) |
GET /v1/error-codes | Nenhum | O catálogo de códigos de erro |
Respostas bem-sucedidas utilizam 200 salvo indicação em contrário. Ambas as rotas de leitura sem escopo nomeado ainda exigem uma chave de projeto válida e não expirada, bem como acesso ao serviço.
Projetos e salas
Seção intitulada “Projetos e salas”GET /v1/projects retorna apenas o projeto associado à chave. A criação do projeto é realizada no console.
Para POST /v1/rooms, envie:
{ "projectId": "00000000-0000-4000-8000-000000000001", "name": "Customer conversation", "maxParticipants": 4}projectId e name são obrigatórios. maxParticipants é opcional, tem como valor padrão 8 e deve ser um número inteiro de pelo menos 2 dentro da franquia do seu plano. Defina explicitamente um valor menor se o seu plano não permitir o padrão. A resposta inclui a nova sala id, projectId, name, maxParticipants, status
(open), e createdAt.
GET /v1/rooms lista as salas do projeto associadas à chave. Encerre uma sala com
POST /v1/rooms/{roomId}/end, sem corpo. O comando de encerramento bloqueia novas entradas e desconecta sessões ativas. Ele também solicita que as tarefas de gravação ativas sejam interrompidas. Repetir a operação em uma sala encerrada retorna 404; não se trata de uma resposta de sucesso idempotente. Atualmente, não há método para renomear, reabrir ou excluir uma sala.
Emitir credenciais dos participantes
Seção intitulada “Emitir credenciais dos participantes”POST /v1/rooms/{roomId}/tokens aceita um objeto JSON opcional:
{ "canPublish": false }canPublish O valor padrão é true. Defina-o como false para um cliente somente de recepção. A sala deve estar aberta e pertencer ao projeto da chave. A resposta contém:
| Campo | Significado |
|---|---|
token | Token de participante confidencial e de curta duração |
participantId | Identificador atribuído a esta participação |
expiresIn | Tempo de validade das credenciais de entrada em segundos, atualmente 300 |
url | URL de sinalização para o cliente |
iceServers | Configuração do ICE, incluindo credenciais temporárias de retransmissão |
Solicite novas credenciais para cada entrada e reconexão. Não deduza que a admissão foi bem-sucedida com base na emissão do token: o estado da sala, a capacidade e a autorização são também verificados no momento da entrada. Consulte o fluxo completo do cliente.
Tarefas de gravação e downloads
Seção intitulada “Tarefas de gravação e downloads”Comece com POST /v1/recordings e { "roomId": "ROOM_UUID" }. O 202
A resposta inclui uma gravação id e status: "queued"; isso não significa que já exista um arquivo disponível para download. Uma gravação ativa duplicada para a mesma sala retorna 409.
GET /v1/recordings retorna tarefas filtradas por projeto, incluindo suas id,
roomId, status, e tracks. Os metadados da faixa incluem id, kind,
source, participantId, e bytes. Utilize os IDs de rastreamento retornados pelo RTC.
Interrompa um trabalho em fila ou em gravação com
POST /v1/recordings/{recordingId}/stop, sem corpo. Consulte a lista ou utilize um
recording.ready webhook para determinar a conclusão. Um trabalho que já esteja em processamento, pronto ou com falha não é um alvo ativo para interrupção e retorna 404.
Para uma faixa pronta, publique em sua /download rota. A resposta é
{ "url": "TEMPORARY_DOWNLOAD_URL", "expiresIn": 300 }. Recupere a URL retornada sem alterações para baixar os bytes do anexo. A própria URL autoriza o acesso até o vencimento; trate-a como uma credencial. Ela é não um link público permanente. Consulte segurança e formatos de gravação.
GET /v1/usage retorna:
| Campo | Significado |
|---|---|
participantSeconds | Soma das durações completas das sessões dos participantes dentro do escopo |
sessions | Número de conexões concluídas no escopo |
period | all-time para esses contadores de atividade |
billingStatus | Indica faturamento gerenciado centralmente |
quotas | Decisões atuais de autorização para os recursos RTC do espaço de trabalho |
Divida os segundos dos participantes por 60 para exibir os minutos dos participantes. Esses contadores de atividade não constituem uma fatura nem uma contagem de participantes em tempo real. Uma chave de projeto filtra a atividade para o respectivo projeto, enquanto as cotas pertencem ao espaço de trabalho proprietário. O uso para fins de cobrança pode ser atualizado de forma assíncrona; utilize o sistema central de cobrança para obter informações sobre assinaturas e faturas.
Os erros retornam um JSON error string e um estável code, também enviado no
X-Error-Code cabeçalho. Envie RTC-Version: 2026-11-01 para o envelope de erro estruturado. Consulte erros para as formas e o catálogo de códigos,
limites de taxa para 429, e controle de versão para o que pode mudar em /v1. Não dependa do texto exato da mensagem.
| Status | Verificação ou ação |
|---|---|
400 | Campos obrigatórios, UUIDs, campos desconhecidos ou intervalos de entrada |
401 | Credenciais ausentes, inválidas, revogadas ou vencidas |
403 | Escopo da chave, acesso ao projeto, direito do plano ou cota |
404 | Recurso ausente, fora do escopo ou que não está no estado exigido |
409 | Operação conflitante, como uma gravação ativa |
413 | O corpo da solicitação excede o limite de tamanho |
429 | Limitação de taxa; recue e respeite Retry-After quando fornecida |
5xx | Falha temporária do serviço; repita as leituras com recuo e reconcilie as gravações |
Nunca verifique os recursos de outro cliente para distinguir entre negação de acesso e ausência. Siga orientações para solução de problemas.