Pular para conteúdo

Visão Geral da API

A API da Videochamada permite criar e gerenciar chamadas de vídeo de forma programática: você cria uma chamada, compartilha o link com os participantes e acompanha tudo o que acontece — status, eventos, participantes, gravações e transcrições — por meio de endpoints REST ou de webhooks.

URL base

Todas as requisições devem ser feitas para:

https://api.videochamada.com.br

Autenticação

A API usa API Keys por projeto. Cada chave é criada no painel de gerenciamento, pertence a um único projeto e só enxerga os recursos desse projeto. A chave é enviada no cabeçalho de autorização de todas as requisições:

Authorization: Bearer SUA_API_KEY
Content-Type: application/json

Consulte Autenticação e Token de API para saber como criar, restringir por IP e revogar suas chaves.

Convenções

  • JSON: todas as requisições e respostas usam application/json.
  • Datas: todos os campos de data são strings no formato ISO 8601 (exemplo: "2026-08-30T14:22:01.000Z").
  • Minutos faturáveis: o campo totalBillableMinutes é serializado como string decimal (exemplo: "12.50"), para preservar a precisão.

  • Paginação: endpoints paginados aceitam page e limit e respondem no envelope:

    {
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

  • Idempotência: a criação de chamadas aceita o cabeçalho opcional Idempotency-Key. Reenviar a mesma requisição com a mesma chave retorna a mesma chamada, sem criar duplicatas. Veja os detalhes em Criar Chamada.

  • Link da chamada: toda chamada tem uma URL no formato https://{sua-organizacao}.videochamada.com.br/chamada/{callId}. Se a sua organização tiver um domínio personalizado ativo, ele substitui o subdomínio.

Índice de endpoints

Método Endpoint Descrição
POST /api/calls Criar uma nova chamada
GET /api/calls Listar chamadas do projeto por período
GET /api/calls/{id}/status Obter status detalhado de uma chamada
GET /api/calls/{id}/events Listar eventos de uma chamada
GET /api/calls/{id}/participants Listar participantes de uma chamada
POST /api/calls/{id}/end Encerrar uma chamada
POST /api/calls/{id}/recordings Ativar gravação para uma chamada
DELETE /api/calls/{id}/recordings Desativar gravação de uma chamada
GET /api/calls/{id}/recordings Listar gravações de uma chamada
GET /api/calls/{id}/transcriptions Listar transcrições de uma chamada
GET /api/calls/{id}/transcriptions/dialogue Obter o diálogo transcrito da chamada
POST /api/calls/{id}/access Emitir token de acesso por papel
GET /api/me Validar a API Key (descrito abaixo)
GET /api/surveys/responses Listar respostas de pesquisas NPS
GET /api/surveys/analytics Obter métricas agregadas das pesquisas
GET /recordings/files/{fileId}/download-url Obter URL de download de um arquivo de gravação

Além dos endpoints REST, você pode receber notificações automáticas de eventos das chamadas configurando webhooks no painel — veja Configuração de Webhooks.

Fluxo típico de integração

  1. Crie uma chamada com POST /api/calls.
  2. Compartilhe a URL retornada (https://{sua-organizacao}.videochamada.com.br/chamada/{callId}) com os participantes.
  3. Acompanhe a chamada consultando GET /api/calls/{id}/status e GET /api/calls/{id}/events, ou receba as notificações por webhooks.
  4. Busque gravações e transcrições depois do encerramento, se a gravação estiver habilitada.

Validando sua chave: GET /api/me

Endpoint simples que valida a API Key. É uma boa primeira chamada para confirmar que a sua integração está autenticando corretamente antes de partir para os demais endpoints.

Requisição

GET /api/me

Cabeçalhos:

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

Este endpoint não recebe parâmetros.

Exemplos

cURL

curl -X GET "https://api.videochamada.com.br/api/me" \
  -H "Authorization: Bearer SUA_API_KEY"

Python (requests)

import requests

response = requests.get(
    "https://api.videochamada.com.br/api/me",
    headers={"Authorization": "Bearer SUA_API_KEY"},
)
print(response.json())

Node.js (axios)

const axios = require('axios');

const response = await axios.get('https://api.videochamada.com.br/api/me', {
  headers: { Authorization: 'Bearer SUA_API_KEY' },
});
console.log(response.data);

Resposta

{
  "status": "ok"
}
Campo Descrição
status Sempre "ok" quando a chave é válida

Erros

Status Mensagem Quando ocorre
401 API key is missing O cabeçalho Authorization não foi enviado
401 Invalid API key A chave é inválida, foi revogada, ou a requisição partiu de um IP fora da lista de IPs permitidos da chave

Primeira chamada

Use GET /api/me como health check da sua integração: se ele retornar {"status": "ok"}, sua chave e seus cabeçalhos estão corretos.