Criar Chamada

O endpoint POST /api/calls cria uma nova chamada no seu projeto e retorna o link que os participantes usarão para entrar. Este é normalmente o primeiro passo de qualquer integração: crie a chamada, compartilhe a URL retornada e acompanhe o andamento pelos endpoints de status e eventos ou por webhooks.

Requisição

POST /api/calls

Cabeçalhos:

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer SUA_API_KEY`
`Content-Type`	Sim	`application/json`
`Idempotency-Key`	Não	Chave de idempotência (1 a 200 caracteres imprimíveis). Veja Idempotência abaixo.

Parâmetros do corpo:

Parâmetro	Tipo	Obrigatório	Descrição
`expiresAt`	string (ISO 8601)	Não	Data e hora de expiração do link. Deve ser futura. Após esse horário a chamada é encerrada automaticamente (verificação a cada ~5 minutos) e o link deixa de admitir participantes. Em projetos com modo de link reutilizável, a expiração reinicia a sala (webhook `call.reset`) em vez de invalidá-la permanentemente.
`recording`	boolean ou null	Não	Controla a gravação desta chamada: `true` grava independentemente da configuração do projeto; `false` não grava independentemente da configuração do projeto; ausente ou `null` herda a configuração de gravação do projeto.

Idempotência

Envie o cabeçalho opcional Idempotency-Key para tornar a criação segura contra reenvios (timeouts, retries automáticos, duplo clique):

Mesma chave + mesmo corpo no mesmo projeto: a API retorna a mesma chamada já criada, sem duplicar.
Mesma chave + corpo diferente: a API retorna 409 Conflict.

Recomendado para retries

Gere um identificador único por operação (por exemplo, um UUID) e reutilize-o em todas as tentativas daquela operação. Assim, um retry após timeout nunca cria uma chamada duplicada.

Exemplos

cURL

curl -X POST "https://api.videochamada.com.br/api/calls" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8721-videochamada" \
  -d '{
    "expiresAt": "2026-09-01T12:00:00.000Z",
    "recording": true
  }'

Python (requests)

import requests

response = requests.post(
    "https://api.videochamada.com.br/api/calls",
    headers={
        "Authorization": "Bearer SUA_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "pedido-8721-videochamada",
    },
    json={
        "expiresAt": "2026-09-01T12:00:00.000Z",
        "recording": True,
    },
)
print(response.json())

Node.js (axios)

const axios = require('axios');

const response = await axios.post(
  'https://api.videochamada.com.br/api/calls',
  {
    expiresAt: '2026-09-01T12:00:00.000Z',
    recording: true,
  },
  {
    headers: {
      Authorization: 'Bearer SUA_API_KEY',
      'Idempotency-Key': 'pedido-8721-videochamada',
    },
  },
);
console.log(response.data);

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_API_KEY");
        client.DefaultRequestHeaders.Add("Idempotency-Key", "pedido-8721-videochamada");

        var json = "{\"expiresAt\":\"2026-09-01T12:00:00.000Z\",\"recording\":true}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            "https://api.videochamada.com.br/api/calls", content);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Resposta

Exemplo de resposta (201):

{
  "id": "9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f",
  "created": "2026-08-30T14:22:01.000Z",
  "updated": "2026-08-30T14:22:01.000Z",
  "deleted": null,
  "started": null,
  "ended": null,
  "expiresAt": "2026-09-01T12:00:00.000Z",
  "status": "created",
  "totalBillableMinutes": "0.00",
  "projectId": "c4a1e9d2-3b5f-4a6c-8d7e-9f0a1b2c3d4e",
  "recording": true,
  "url": "https://sua-organizacao.videochamada.com.br/chamada/9f3b2a1c-7d4e-4c8a-b5f6-2e1d0c9b8a7f"
}

Campos:

Campo	Descrição
`id`	Identificador único da chamada (UUID)
`created`	Data e hora de criação da chamada
`updated`	Data e hora da última atualização
`deleted`	Data de exclusão, se aplicável (`null` normalmente)
`started`	Data e hora de início (preenchido quando o primeiro participante entra)
`ended`	Data e hora de encerramento (preenchido quando a chamada termina)
`expiresAt`	Data e hora de expiração do link, se informada
`status`	Status atual: `created`, `active` ou `ended`
`totalBillableMinutes`	Total de minutos faturáveis, como string decimal (ex.: `"0.00"`)
`projectId`	Identificador do projeto ao qual a chamada pertence
`recording`	Valor resolvido da gravação para esta chamada (já considera a configuração do projeto quando você não envia o parâmetro)
`url`	Link da chamada: `https://{sua-organizacao}.videochamada.com.br/chamada/{callId}`. Se a organização tiver um domínio personalizado ativo, ele substitui o subdomínio.

Comportamento do link

O link é a credencial de acesso

Qualquer pessoa com a URL entra diretamente na chamada — não há senha adicional. Compartilhe o link somente com os participantes. O link deixa de funcionar quando a chamada é encerrada ou expira (a verificação de expiração roda a cada ~5 minutos). Em projetos com modo de link reutilizável, a expiração reinicia a sala (call.reset) em vez de marcá-la como encerrada.

Você pode pré-preencher o nome do participante adicionando ?username= à URL — veja os detalhes em Integração Mobile.

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	`Expiration date must be in the future`	O `expiresAt` enviado está no passado ou é inválido
401	`Organization subscription is suspended. Please update your payment information.`	A assinatura da organização está suspensa
403	`Maximum spending limit reached for this month`	O limite de gastos mensal configurado para a organização foi atingido
404	`Organization not found`	A organização vinculada ao projeto não foi encontrada
404	`Subscription not found`	A organização não possui assinatura ativa
409	`Idempotency-Key was already used with a different request`	O mesmo `Idempotency-Key` foi reutilizado com um corpo diferente

Boas práticas

Defina sempre expiresAt: evita que links fiquem válidos indefinidamente.
Use Idempotency-Key em toda criação disparada por sistemas: reenvios e retries passam a ser seguros.
Trate o link como um segredo: entregue-o apenas aos participantes, por um canal privado.
Não decida a gravação no cliente: se todas as chamadas do projeto devem ser gravadas, configure a gravação no projeto e omita o parâmetro recording.