Recuperação após interrupções no serviço com a Video API da Vonage

Introdução

Espera-se que as aplicações de vídeo em tempo real estejam sempre ativas. Seja em uma consulta de telessaúde, uma sessão de consultoria financeira ou um evento virtual em grande escala, seus usuários finais não toleram nenhuma interrupção inexplicável. Quando algo dá errado no lado da plataforma, a diferença entre uma recuperação sem problemas e um usuário frustrado geralmente se resume a uma coisa: se o seu aplicativo está atento.

Nos últimos dois anos, a plataforma Vonage Video API lançou um conjunto significativo de recursos de resiliência: chamadas de retorno em caso de interrupção do serviço, migração automática de sessões e infraestrutura com autocorreção. Grande parte desses recursos foi anunciada nas notas de lançamento do SDK e webinars sobre o roteiro de desenvolvimento, mas ainda não havia sido reunido em um único lugar. Esta publicação faz exatamente isso.

Se você desenvolveu sua aplicação antes de 2023, é bem provável que não esteja aproveitando nenhum dos recursos mais recentes que lançamos. Neste artigo, vamos abordar esses recursos para garantir que você esteja aproveitando ao máximo tudo o que a Vonage tem a oferecer. 

Como a plataforma lida com interrupções

Antes de nos aprofundarmos no que seu aplicativo deve fazer, é importante entender o que a plataforma faz automaticamente.

A Video API da Vonage opera em mais de 11 data centers regionais com infraestrutura redundante e verificações contínuas de integridade. Quando um servidor precisa ser substituído ou apresenta uma falha inesperada, o sistema de monitoramento da plataforma detecta o problema e aciona a recuperação. Na maioria das interrupções, a plataforma se recupera automaticamente, sem que seja necessária qualquer ação sua ou dos usuários.

Mas “a maioria” não significa “todos”. Nos casos em que uma sessão, transmissão, arquivo ou chamada SIP seja afetada, a plataforma agora envia um callback ao seu servidor de aplicativos — imediatamente, sem esperar pela atualização da página de status. Sua função é monitorar esse callback e agir de acordo com ele.

Passo 1: Registre suas URLs de retorno de chamada

As chamadas de retorno relacionadas a interrupções no serviço só são enviadas se você tiver URLs de retorno configuradas no seu projeto. Sem elas, nenhum dos eventos descritos abaixo chegará ao seu servidor de aplicativos.

Painel de controle do Vonage Video

1. Faça login no seu Painel da API da Vonage.

2. Acesse Applications e selecione seu aplicativo com suporte a Video (ou crie um novo).

3. Clique “Editar”, role até Recursos → Video.

4. Em Monitoramento de sessão, insira sua URL de retorno de chamada para eventos de sessão.

5. Configure URLs de retorno de chamada separadas para Arquivamento, Monitoramento de chamadas SIPe Experience Composer conforme necessário.

6. Clique Salvar.

Ambiente OpenTok (Portal da conta TokBox)

1. Faça login na sua Account da Video API da Vonage.

2. Selecione o projeto que você deseja configurar.

3. Role até Configurações do projeto.

4. Em cada serviço (Monitoramento de Sessões, Arquivamento, Monitoramento de Chamadas SIP), clique em Configurar e insira sua URL de retorno de chamada.

Entrega de callbacks e novas tentativas: A plataforma utiliza uma política de repetição de tentativas com recuo exponencial. Se o seu servidor estiver temporariamente indisponível, as chamadas de retorno serão repetidas a partir de 5 segundos, dobrando o intervalo até um máximo de 15 minutos, por até 24 horas. Após 24 horas, o evento específico é descartado. Certifique-se de que seu endpoint de chamada de retorno retorne um 200 para confirmar o recebimento.

Regras do firewall: Se o seu servidor de retorno de chamada restringir o tráfego de entrada por IP, permita o intervalo de IPs do serviço de retorno de chamada da Vonage: 216.147.0.0/18.

Etapa 2: Gerenciar chamadas de retorno em caso de interrupção do serviço

Os callbacks de interrupção de serviço são webhooks padrão POST enviadas às suas URLs registradas. Elas utilizam formatos de eventos existentes com novos códigos de motivo que indicam uma falha inesperada do lado da plataforma — e não uma desconexão normal do cliente.

Veja a seguir o que esperar de cada serviço e o que fazer ao recebê-lo.

Sessão de Video

Quando um servidor de mídia da Video API for desligado inesperadamente, você receberá um sessionDestroyed evento na URL de retorno de chamada de monitoramento da sua sessão:

{
  "sessionId": "YOUR_SESSION_ID",
  "projectId": "YOUR_PROJECT_ID",
  "event": "sessionDestroyed",
  "reason": "forceDisconnected",
  "timestamp": 1700000000000
}

O sinal principal aqui é "reason": "forceDisconnected" - isso indica um desligamento por parte da plataforma, e não uma desconexão normal do cliente.

Ação de recuperação: Crie um nova sessão e reconecte seus terminais. Não reutilize o ID da sessão encerrada. Uma sessão é encerrada um minuto após o último participante se desconectar, e tentar se reconectar a uma sessão encerrada pode fazer com que as conexões sejam direcionadas a servidores que não estão mais aptos a atender ao tráfego. A criação de uma sessão leva milissegundos; portanto, não há motivo prático para armazenar em cache e reutilizar IDs de sessão em chamadas diferentes.

Interconexão SIP

Caso ocorra uma interrupção inesperada no serviço SIP, você receberá uma callDestroyed chamada de retorno na sua URL de monitoramento SIP:

{
  "sessionId": "YOUR_SESSION_ID",
  "projectId": "YOUR_PROJECT_ID",
  "event": "callDestroyed",
  "reason_code": "703",
  "reason_message": "Unexpected Clearing",
  "timestamp": 1700000000000
}

reason_code: 703 é o sinal de uma liberação inesperada por parte da plataforma, em contraste com o encerramento normal de uma chamada 700).

Ação de recuperação: Rediscar o terminal SIP usando a API de discagem para restabelecer a chamada SIP.

Transmissão

Existem dois tipos possíveis de notificações de interrupção de transmissão, ambas enviadas para a URL de monitoramento da sua transmissão:

Erro na URL RTMP/HLS (no started status):

• Para RTMP: você receberá "status": "error" para cada URL de endpoint RTMP afetado.

• Para HLS: você receberá "hlsStatus": "error" no endpoint do HLS.

Falha interna do servidor:

{
  "status": "failed",
  "reason": "Internal server failure",
  "event": "broadcast"
}

Ação de recuperação: Reenviar uma nova transmissão na mesma sessão usando a API de transmissãoe, em seguida, atualize a URL da transmissão para todos os endpoints de clientes que estavam consumindo o stream.

Arquivo (Gravação)

{
  "id": "ARCHIVE_ID",
  "sessionId": "YOUR_SESSION_ID",
  "status": "failed",
  "reason": "Internal server failure"
}

Ação de recuperação: Reemitir um novo arquivo na mesma sessão usando a API de arquivamento. Observe que o conteúdo gravado até o momento da falha pode estar parcialmente disponível — verifique o status do arquivo após a interrupção.

Experiência com o Composer

{
  "id": "RENDER_ID",
  "sessionId": "YOUR_SESSION_ID",
  "status": "failed",
  "reason": "Internal server failure",
  "event": "render"
}

Ação de recuperação: Inicie uma nova renderização do Experience Composer na sessão usando a API de renderização.

Etapa 3: Ativar a migração de sessão

As notificações de interrupção do serviço avisam quando algo dá errado, para que você possa agir. A migração de sessão vai um passo além: ela mantém sua sessão ativa conectada automaticamente quando o servidor subjacente é alternado, de modo que os participantes nunca precisam se reconectar manualmente.

A migração de sessão foi disponível para uso geral no Client SDK 2.31 (agosto de 2025).

O que está coberto

A Migração de Sessão gerencia a camada de sessões ativas:

• Sessões de vídeo ao vivo (todos os participantes se reconectam automaticamente)

• Chamadas SIP por meio da API Dial

• Conexão de áudio via WebSockets usando a API Connect

Importante: A migração de sessão abrange apenas a sessão ao vivo. Arquivos, transmissões e renderizações do Experience Composer em execução no momento de uma rotação não são são migrados automaticamente — use os callbacks de interrupção descritos acima para lidar com esses serviços.

Ativação da migração de sessão para os SDKs da Web e nativos

Passar sessionMigration: true ao inicializar a sessão:

// JavaScript SDK

const session = OT.initSession(apiKey, sessionId, {
  sessionMigration: true
});

Essa mesma opção está disponível nos SDKs para iOS, Android, Windows, Linux e macOS — consulte o guia de rotação de servidores para obter a sintaxe específica de cada plataforma.

Ativação da migração de sessão para SIP (API de discagem)

Inclua sessionMigration: true no corpo da solicitação da API Dial:

{
  "sessionId": "YOUR_SESSION_ID",
  "token": "YOUR_TOKEN",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Ativação da migração de sessão para o Audio Connector (Connect API)

O mesmo sessionMigration: true sinalizador se aplica ao corpo da solicitação da API Connect.

Observação: sessionMigration o valor padrão é false e deve ser definido explicitamente. Recomendamos ativá-lo para todas as sessões de produção, especialmente para sessões de longa duração ou aquelas nas áreas de saúde, finanças ou outros contextos de alto risco, nos quais uma reconexão manual causaria interrupções.

Melhores práticas

Lembre-se do seguinte:

Trate os callbacks de forma idempotente. Seu manipulador de callbacks pode receber o mesmo evento mais de uma vez em casos extremos. Certifique-se de que sua lógica de recuperação (rediscagem SIP, reinício de um arquivo, etc.) seja segura para ser chamada várias vezes sem criar recursos duplicados.

Responda rapidamente com um 200. A plataforma considera que um callback foi entregue somente quando recebe uma 200 resposta HTTP. Se o seu manipulador demorar muito para responder, a plataforma poderá tentar novamente. Confirme o recebimento imediatamente e processe a lógica de recuperação de forma assíncrona, se necessário.

Teste seus caminhos de recuperação antes de entrar em produção. O Vonage Video Playground e o Session Inspector são ferramentas úteis para observar eventos de sessão e verificar se seu manipulador de callback está recebendo e processando os eventos corretamente.

Não reutilize IDs de sessão desativadas. Vale a pena repetir isso. Uma sessão é encerrada um minuto após o último participante se desconectar. Reconectar-se a um ID de sessão desativado pode fazer com que as conexões sejam direcionadas para servidores que estão sendo desligados. Sempre crie uma nova sessão.

Conclusão

A plataforma da Video API da Vonage foi projetada para se autocorrigir, mas seu aplicativo precisa colaborar nesse processo. Aqui está uma versão resumida:

Leituras complementares

• Guia de rotação de servidores e migração de sessões

• Guia de monitoramento de sessões

• Referência da API REST de vídeo

• Como configurar callbacks de monitoramento de sessão