Criar uma teleconferência com PHP e a Voice API da Vonage

Introdução

Neste tutorial, você aprenderá a criar um aplicativo de teleconferência usando PHP e a Voice API da Vonage. Ao final, você terá um número de telefone para o qual vários participantes poderão ligar para participar da mesma conversa ao vivo.

Vamos configurar uma aplicação da Vonage, processar chamadas recebidas com um Objeto de Controle de Chamadas (NCCO) e retornar respostas dinâmicas a partir de um endpoint simples em PHP. Este projeto é um ponto de partida prático para a criação de linhas para reuniões de equipe, linhas diretas para eventos ou experiências de voz colaborativas.

O código-fonte completo deste tutorial está disponível no repositório GitHub da Comunidade Vonage, para que você possa acompanhar ou adaptá-lo ao seu próprio caso de uso.

Pré-requisitos

• PHP 8.3 ou superior

• Um Account da API da Vonage

Atendendo a uma chamada recebida com PHP

Neste exemplo, os usuários ligarão para um número virtual da Vonage, e o código do seu aplicativo responderá a essa chamada recebida. A Vonage faz isso utilizando um Objeto de Controle de Chamada, ou NCCO. 

Primeiro, teremos uma saudação gerada por conversão de texto em fala (TTS); em seguida, o usuário entrará na teleconferência.

Para isso, vamos adicionar um answer.php arquivo ao public/ diretório (nossa raiz da web) e faremos com que ele retorne o NCCO. Como o NCCO está no formato JSON, o PHP também precisa incluir um Content-Type :

<?php

$ncco = [
    [
        "action" => "talk",
        "text" => "Thank you for joining the call today. You will now be added to the conference.",
        "language" => "en-GB",
        "style" => 0,
        "premium" => true
    ],
    [
        "action" => "conversation",
        "name" => "weekly-team-meeting"
    ]
];

header("Content-Type: application/json");
echo json_encode($ncco);

A $ncco variável contém o NCCO que você enviará ao servidor da Vonage para instruí-lo sobre como lidar com uma chamada recebida. Este exemplo inclui uma ação “talk” que cumprimenta o usuário, seguida por uma ação “conversation” que adiciona o usuário à teleconferência. Este código utiliza header() para fazer com que o PHP envie o Content-Type cabeçalho, seguido pelo próprio JSON.

Se você estiver curioso para saber o que mais pode fazer com uma certificação NCCO, pode consultar a documentação de referência do NCCO em nosso Portal do Desenvolvedor.

Enviar a resposta

Nesse ponto, você pode começar a testar os componentes ativos do aplicativo. Inicie o servidor web PHP a partir do public/ diretório:

cd public/
php -S localhost:8080

Verifique se sua aplicação retorna o NCCO corretamente ao fazer uma solicitação para http://localhost:8080/answer.php usando seu cliente HTTP preferido (cURL, Postman ou até mesmo seu navegador são boas opções para isso).

Disponibilize o código ao público

Para que a Vonage notifique seu aplicativo sobre uma chamada recebida, ela precisa conseguir acessá-lo; portanto, esse código deve estar disponível publicamente. Uma opção é implantá-lo em um servidor, mas, para fins de desenvolvimento, prefiro usar o ngrok para expor meu ambiente de desenvolvimento local. Assim que o servidor web estiver em execução (o meu está na porta 8080), execute o ngrok da seguinte maneira:

ngrok http 8080

Isso exibirá um painel com um link para a interface web (muito útil, clique nele), a URL https do seu túnel (copie-a, vamos precisar dela daqui a pouco) e uma seção que mostrará as solicitações que chegam quando você as enviar.

Teste seu novo túnel fazendo uma chamada para seu aplicativo por meio dele — você pode substituir http://localhost:8080 pela sua URL https do ngrok e tente a solicitação para /answer.php novamente.

Configurar um número para ligar

Adquira um número da Vonage

Criar uma aplicação da Vonage com recursos de voz

Outro item necessário é um aplicativo da Vonage: ele armazena a configuração da chamada e pode ser vinculado ao(s) número(s) que você deseja usar. Essa separação é muito útil caso você queira que números de diferentes regiões geográficas participem da mesma teleconferência.

Os aplicativos da Vonage utilizam chaves públicas e privadas. Neste exemplo, você está simplesmente recebendo uma chamada, portanto, não precisará da chave privada por enquanto. No entanto, é recomendável salvar seu private.key arquivo no seu diretório de trabalho, caso decida desenvolver mais funcionalidades com base neste exemplo.

Para criar o aplicativo, é necessário atribuir um nome a ele e configurar alguns pontos de conexão importantes para webhooks:

• A URL de resposta será o answer.php ponto de extremidade que você já criou.

• Defina a URL do evento como event.php. Criaremos esse arquivo na próxima seção.

Vincule a aplicação ao seu número da Vonage

Agora que seu aplicativo da Vonage já foi criado, os números virtuais disponíveis aparecerão na parte inferior da tela — incluindo aquele que você acabou de adquirir na etapa anterior.

Selecione o número que você gostaria de usar para este tutorial e, em seguida, clique no botão “Vincular” ao lado dele para vincular seu número virtual ao aplicativo da Vonage.

Consequentemente, quando você ligar agora para o seu número virtual, a Vonage buscará as instruções de roteamento de chamadas na URL que você especificou como URL de respostae enviará webhooks de evento para o seu URL de evento.

A seguir, vamos verificar se tudo o que fizemos até agora está funcionando. Ligue para o número e veja se você ouve a saudação; se sim, peça a outra pessoa para ligar e aproveitem para bater um papo.

Se não funcionar na primeira vez, não se preocupe. O próximo passo é criar o tratamento de eventos para que você possa ver o que está acontecendo — e, se houver erros, é assim que você os identificará.

Tratar eventos de chamada

Para simplificar, o aplicativo espera que a URL do evento seja/event.php—e, se você já testou isso, deve ter visto algumas solicitações com falha chegando lá.

Para criar um manipulador de eventos simples, crie um arquivo public/event.php e adicione o seguinte código:

<?php

$post_params = json_decode(file_get_contents("php://input"), true);
$input_params = $_GET;

if (is_array($post_params)) {
    $input_params = array_merge($input_params, $post_params);
}

if (isset($input_params['status'])) {
    error_log("Status: " . $input_params['status']);
}
error_log("Event data: " . json_encode($input_params));

É possível configurar a URL do evento para usar GET ou POST solicitações, portanto, esse código vai funcionar com qualquer uma delas! É muito simples e grava os dados no error_log, portanto, se você estiver usando o servidor web PHP local, como fiz neste exemplo, verá os eventos na saída do processo do servidor web. Em uma aplicação real, você pode vincular sua URL de evento a algo mais formal.

Comece a teleconferência do partido

Se você ainda não experimentou, ligue para o seu número da Vonage. Depois, convide seus amigos, familiares e colegas a fazerem o mesmo. Você verá os eventos ocorridos durante as chamadas aparecerem em event.php, e as diversas chamadas sendo atendidas, com solicitações feitas para answer.php.

Qual será o seu próximo passo?

Existem algumas coisas que você talvez queira fazer a seguir:

• Consulte a documentação do NCCO para saber como registrar essas chamadas, reproduzir música de espera ou designar um moderador específico para a chamada.

• Veja o código deste projeto no GitHub.

• Confira nossos outros trechos de código para trabalhar com a Voice API da Vonage.

Conclusão

Neste tutorial, criamos uma teleconferência baseada em PHP usando a Voice API da Vonage. Você configurou um aplicativo de voz, processou webhooks de chamadas recebidas e retornou um NCCO para incluir vários participantes na mesma conversa.

A partir daqui, você pode ampliar este projeto adicionando gravação de chamadas, designando moderadores, reproduzindo música de espera ou gerando dinamicamente nomes de salas de conferência. Você também pode combinar esse fluxo de trabalho com a Messages API para enviar lembretes ou integrar autenticação para controlar quem pode participar.