Chamadas

• No navegador, @polymorfa/browser conecta microfones, câmeras e alto-falantes a uma chamada, e @polymorfa/react e @polymorfa/elements renderizam a interface da chamada.
• No código do servidor, @polymorfa/sdk/calls permite que a sua aplicação fale e ouça em uma chamada, por exemplo para executar um agente de voz.
• No seu servidor, @polymorfa/sdk faz, atende e encerra chamadas e gerencia as configurações de chamadas.

​

Como as chamadas funcionam

• A chamada. Ela toca, é atendida ou recusada e termina. Encerrá-la desconecta todos.
• Participantes. Um participante é quem age na chamada. A Polymorfa o deriva da credencial:
  • Um token de cliente age como client:<ephemeralId>, usando o ephemeralId com que foi emitido. Tokens de cliente não podem indicar outro participante.
  • Uma chave de equipe ou um token de projeto age como server:<participant>. Informe o nome opcional participant (de 1 a 128 caracteres entre A-Z, a-z, 0-9, ., _, :, @ e -). O padrão é server:default.
• Conexões. Cada aba do navegador ou cliente de servidor que transporta o áudio e o vídeo de um participante é uma conexão. Um participante pode ter várias conexões. Sair fecha uma conexão e nunca encerra a chamada.

​

Autentique clientes de navegador

​

Chamadas no navegador

import { createBrowserCalls, createClientTokenProvider } from "@polymorfa/browser";
import { CallSurface, DialPad, PolymorfaProvider } from "@polymorfa/react";

const calls = createBrowserCalls({
  session: "support",
  getClientToken: createClientTokenProvider(),
});
await calls.connect();

<PolymorfaProvider>
  <CallSurface controller={calls.controller} exclusive={false} />
  <DialPad controller={calls.controller} />
</PolymorfaProvider>;

​

Chamadas a partir do código do servidor

import { CallsClient } from "@polymorfa/sdk/calls";

const client = new CallsClient({
  token: process.env.POLYMORFA_KEY!,
  session: "support",
  participant: "voice-agent",
});

client.on("incoming", async (call) => {
  await call.answer({ exclusive: true });
  call.audio.on("data", (pcm) => recognizer.push(pcm));
  call.audio.write(synth.speak("Hello, how can I help?"));
  call.on("ended", (reason) => console.log("ended:", reason));
});

await client.connect();

• call.audio transporta o áudio combinado da chamada como PCM mono de 16 bits com sinal, na taxa call.audio.sampleRate, nos dois sentidos. Escreva o áudio em tempo real.
• call.video recebe o vídeo de cada um dos outros participantes como um stream separado de quadros H.264 e envia um stream H.264 seu. call.video.sources indica o participante por trás de cada stream. Envie um keyframe (uma unidade de acesso com uma fatia IDR, com SPS e PPS nela ou antes dela) quando o evento keyframeRequest disparar. Os outros participantes começam a receber o seu vídeo a partir do seu primeiro IDR.
• Quando a conexão cai, o cliente a reconecta e mantém a chamada.

​

Atender, entrar ou recusar

• exclusive: true faz o claim da chamada. Os outros participantes param de tocar, não podem atender nem se conectar, e as conexões abertas deles são fechadas. Use quando uma pessoa cuida da chamada, por exemplo quando o primeiro agente a atender fica com ela.
• exclusive: false (o padrão) mantém a chamada compartilhada. Os outros participantes continuam tocando e podem entrar.

​

Fazer uma chamada

import { MessagingClient } from "@polymorfa/sdk";

const messaging = new MessagingClient({
  credential: { type: "apiKey", value: process.env.POLYMORFA_KEY! },
});

const placed = await messaging.voip.place({
  session: "support",
  to: "+15550100",
  video: false,
  exclusive: true,
  participant: "agent-7",
});

​

Chamadas para pessoas que nunca conversaram com o número

​

Controle de chamadas pelo servidor

​

Convidar mais pessoas

​

Áudio, vídeo e configurações de chamadas

​

Modo conferência

await messaging.voip.updateCallSettings("support", { conferenceMode: false });
const settings = await messaging.voip.retrieveCallSettings("support");

​

Desativar chamadas em um número

await messaging.voip.updateCallSettings("support", { callsEnabled: false });

• fazer uma chamada, atender ou entrar em uma, convidar um participante e conectar mídia falham com 403 calls_disabled. Iniciar ou atender uma chamada pelo endpoint /calls da Graph API falha com um erro de permissão;
• as chamadas recebidas são recusadas. Você ainda recebe call.received, seguido de call.rejected e call.ended; e
• um tronco SIP não pode fazer chamadas pela sessão.

​

Números da Cloud API

await messaging.voip.updateCallSettings("support", { hostCloudApiCalls: true });

• As chamadas são individuais e somente de áudio. As capabilities delas informam video: false e invite: false. Fazer uma chamada de vídeo ou convidar um participante falha com unsupported_for_connection. Atender com vídeo atende apenas com áudio.
• Antes de você fazer uma chamada, o destinatário precisa conceder à sua empresa permissão para ligar para ele. Sem isso, fazer a chamada falha com call_permission_required.
• O WhatsApp permite de 30 a 60 segundos para atender uma chamada recebida da Cloud API. Atenda em até 30 segundos para evitar uma chamada perdida.

​

Webhooks

​

Histórico de chamadas

​

Análises e registros de chamadas

• answered: a mídia se conectou. Chamadas atendidas ainda em andamento contam aqui.
• declined: um participante ou a outra parte recusou, ou a linha estava ocupada.
• missed: ninguém atendeu antes de a chamada parar de tocar, ou quem ligou desligou primeiro.
• failed: a chamada terminou antes de se conectar por qualquer outro motivo, como uma falha de conexão ou de capacidade.
• in_progress: a chamada ainda está tocando.

​

Estatísticas

curl "https://api.polymorfa.com/platform/calls/stats?since=2026-09-01T00:00:00Z&until=2026-09-08T00:00:00Z&groupBy=day&timezone=America/Sao_Paulo" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"

• day (o padrão) e hour retornam um grupo por dia ou por hora em timezone, incluindo os vazios. Um intervalo com day cobre no máximo 366 dias, e um intervalo com hour, no máximo 31 dias.
• session retorna um grupo por número, começando pelos que têm mais chamadas, até 500 números. groupsTruncated é true quando mais números tiveram chamadas.
• outcome retorna um grupo por resultado.

​

Registros detalhados de chamadas

cursor=""
while :; do
  curl -sS -D headers.txt "https://api.polymorfa.com/platform/calls/export?format=ndjson&since=2026-09-01T00:00:00Z${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $POLYMORFA_API_KEY" >> calls.ndjson
  cursor=$(grep -i '^polymorfa-next-cursor:' headers.txt | cut -d' ' -f2 | tr -d '\r')
  [ -n "$cursor" ] || break
done

​

Retenção de dados de chamadas

• registros de chamadas: o histórico de chamadas que o Console e a API listam;
• eventos de chamadas: o histórico de participantes e conexões de cada chamada;
• os diagnósticos que os seus apps informam sobre as conexões deles nas chamadas.

curl https://api.polymorfa.com/platform/call-retention \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY"

{
  "success": true,
  "data": {
    "policy": "extended",
    "retentionDays": 90,
    "appliesTo": ["call_records", "call_events", "client_reports"],
    "revision": 0,
    "updatedAt": null
  }
}

curl -X PUT https://api.polymorfa.com/platform/call-retention \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy": "custom", "retentionDays": 180, "expectedRevision": 0 }'

• Tokens de projeto podem ler a configuração, mas não alterá-la; uma alteração falha com 403. Tokens de cliente não podem fazer nenhuma das duas coisas.
• Uma equipe sem configuração salva retorna revision: 0 e updatedAt: null. revision aumenta a cada alteração. Envie a revision que você leu como expectedRevision para recusar a atualização com 409 state_conflict se alguém tiver alterado a configuração depois da sua leitura.
• Uma política nomeada com um retentionDays diferente, ou custom sem um, falha com 400 invalid_parameter.
• appliesTo lista os tipos de dados de chamadas que o período cobre. Quando a Polymorfa passar a armazenar um novo tipo de dado de chamada, ele será adicionado a essa lista e seguirá o mesmo período.

​

Informar diagnósticos de chamadas pelo seu app

curl -X POST "https://api.polymorfa.com/messaging/voip/calls/CALL_ID/reports" \
  -H "Authorization: Bearer $POLYMORFA_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "quality",
    "connectionId": "conn_0123456789",
    "client": { "sdk": "my-call-app", "version": "2.3.0", "platform": "browser" },
    "quality": {
      "rttMs": 84,
      "jitterMs": 6,
      "packetsLost": 12,
      "packetsReceived": 4810,
      "audioCodec": "audio/opus",
      "candidateType": "relay",
      "reconnects": 0
    }
  }'

• Cada conexão pode enviar um relatório de qualidade a cada 5 segundos e 20 relatórios de erro por minuto. Os excedentes falham com 429. Os relatórios também contam para a regra rateLimit de um token de cliente.
• A Polymorfa aceita relatórios enquanto a chamada está ao vivo e por 10 minutos depois que ela termina. Relatórios posteriores falham com 409, ou com 410 quando a chamada terminou porque o host de mídia dela foi perdido.
• A Polymorfa mantém até 200 relatórios por chamada. Nesse limite, um relatório de qualidade substitui o relatório de qualidade mais antigo da mesma conexão. Um relatório de qualidade de uma conexão sem nenhum relatório de qualidade armazenado, e todo relatório de erro, retornam 202, mas não são mantidos.
• A Polymorfa autoriza a chamada, não a conexão: qualquer participante como o qual a sua credencial pode agir pode enviar relatórios de qualquer connectionId em uma chamada que essa credencial alcança.

​

Limites de acesso

• maxSetupsPerMinute limita os estabelecimentos de chamada por usuário de token de cliente (padrão 10). Cada chamada feita e cada convite contam como um estabelecimento. Em uma chamada existente, o primeiro atendimento ou a primeira conexão bem-sucedida conta como um estabelecimento; os seguintes na mesma chamada não contam.
• allowedNumber é uma lista separada por vírgulas de números E.164 para os quais um token de cliente pode ligar ou que ele pode convidar.
• maxConcurrency limita as chamadas que um usuário de token de cliente mantém ao mesmo tempo. Uma chamada ocupa a vaga dela até terminar.

​

Erros

​

Controles da tabela no Console