https://a.storyblok.com/f/270183/1368x684/0dc436b804/26oct-text_to_speech_voice_calls_with_php_r3.jpg

Chamadas de voz com conversão de texto em fala usando PHP

Publicado em October 27, 2026

Tempo de leitura: 7 minutos

Introdução

Criar applications baseadas em voz costumava significar lidar com gateways de hardware e protocolos de telefonia de baixo nível. Hoje, a Voice API da Vonage lida com toda essa complexidade com apenas algumas linhas de código. 

Neste tutorial, você criará um pequeno aplicativo em PHP que lida com chamadas telefônicas recebidas e realizadas usando a Voice API da Vonage. Você começará retornando uma mensagem de conversão de texto em fala (TTS) para qualquer pessoa que ligar para o seu número da Vonage e, em seguida, ampliará o aplicativo para iniciar chamadas de saída programaticamente. Por fim, você tornará a mensagem falada dinâmica, buscando uma piada aleatória em uma API pública. 

Resumo: Confira o código de exemplo no repositório GitHub da Comunidade Vonage. 

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte: 

  • PHP 8.3 ou superior instalado. Execute o comando `php -v` para verificar sua versão. 

  • Composer para gerenciamento de dependências 

  • ngrok (ou uma ferramenta de tunelamento semelhante) para expor seu servidor local à internet 

Configurar o CLI da Vonage

O CLI da Vonage permite que você gerencie sua Account, crie Applications e compre Numbers diretamente no terminal. Instale-o globalmente com o npm: 

npm install -g @vonage/cli 

Após a instalação, autentique a CLI com sua chave e seu segredo da API, que você encontrará no Painel da API da Vonage: 

vonage auth set --api-key=YOUR_API_KEY --api-secret=YOUR_API_SECRET

Criar uma aplicação da Vonage

Um aplicativo da Vonage é um contêiner que armazena a configuração e as credenciais necessárias para que seu código interaja com as APIs da Vonage. Crie um novo diretório de trabalho para o seu projeto, acesse-o e execute o seguinte comando: 

mkdir vonage-calls 
cd vonage-calls 

vonage apps create "vonage-calls"  

Você acabou de criar uma Application da Vonage. Anote o ID do aplicativo retornado; você precisará dele em breve. A CLI também salva um private.key arquivo no diretório atual; guarde-o em um local seguro, pois vamos usá-lo junto com o ID do aplicativo para nos autenticarmos na Voice API nas etapas seguintes. 

Em seguida, você precisa adquirir um número virtual com função de Voice para vincular ao seu aplicativo. Procure um número disponível no seu país (substitua “US” pelo código de país de doisletras, se necessário). Os números devem estar no formato E.164: inclua o código do país e omita quaisquer zeros à esquerda (porxemplo, um número do Reino Unido 07700900001 passa a ser 447700900001): 

vonage numbers search US --feature=VOICE 

Selecione um número da lista exibida e, em seguida, compre-o executando: 

vonage numbers buy US SELECTED_NUMBER_FROM_SEARCH 

Por fim, associe o número ao seu aplicativo: 

vonage apps numbers link YOUR_ APPLICATION_ID YOUR_VONAGE_NUMBER  

Você pode verificar se o número foi vinculado corretamente ao seu aplicativo executando: 

Vonage apps numbers list YOUR_ APPLICATION_ID 

Configure seu espaço de trabalho

No diretório do seu projeto, execute o comando `composer init` para começar. Aceite todas as configurações padrão e pule a definição interativa das dependências; faremos isso na próxima etapa. 

Este tutorial noso Slim Framework para lidaras solicitações de webhook recebidas da Vonage. Em seguida, instale o Slim juntamente com sua implementação PSR-7 e a phpdotenv biblioteca para gerenciar variáveis de ambiente: 

composer require slim/slim "^4.0" 
composer require slim/psr7 
composer require vlucas/phpdotenv

Certifique-se de que o private.key arquivo que você recebeu ao criar sua aplicação esteja neste diretório, no mesmo nível que composer.json. 

Crie um .env arquivo na raiz do projeto para armazenar suas credenciais: 

VONAGE_APPLICATION_ID=seu-id-de-aplicativo 
VONAGE_NUMBER=seu-número-vonage 
BASE_URL=https://YOUR_NGROK_URL 

Adicionar .env e private.key ao seu .gitignore arquivo para que as credenciais nunca sejam enviadas para o controle de versão: 

.env 
private.key 

Agora inicie o servidor local de desenvolvimento PHP: 

php -t public -S localhost:8000 

Seu aplicativo agora está em escuta na porta 8000.  

Em seguida, você precisa expor seu aplicativo à internet para que a Vonage possa acessar seus webhooks. Vamos usar o ngrok para isso: 

ngrok http 8000 

Anote uma URL do ngrok recém-criada; você precisará atualizar seu aplicativo Vonage com ela em seguida. 

Acesse o seu Painel da Vonage e localize o aplicativo “vonage-calls” em a Applications . Clique no Editar , altere a Voice em “ Recursose, em seguida, preencha as URLs dos seus webhooks conforme mostrado abaixo: 

URL da resposta: https://YOUR_NGROK_URL/webhooks/answer 

URL do evento: https://YOUR_NGROK_URL/webhooks/event  

Salve suas alterações e pronto! 

Crie seu NCCO

As chamadas Voice da Vonage são controladas por meio de objetos de controle de chamada em JSON, chamados de NCCOs. Um NCCO é uma matriz JSON de ações que indica à Vonage o que fazer quando uma chamada é iniciada. Algumas das ações disponíveis incluem: 

  • conectar - transferir uma chamada para outro número 

  • gravar - gravar uma chamada 

  • conversa - criar uma teleconferência 

  • talk - gerar uma mensagem de conversão de texto em fala 

Veja oe referência da NCCO para alista completa. 

Aqui está o NCCO com o qual você vai começar: uma mensagem simples de conversão de texto em fala: 

[ 
  { 
    "action": "talk", 
    "text": "The amount of visible light from a lamp is measured in lumens." 
  } 
] 

Observação sobre a personalização da voz: A ação “talk” suporta parâmetros de idioma e estilo para controlar a Voice utilizada na conversão de texto em fala. Consulte a referência de idiomas para conversão de texto em fala para obter a lista completa de vozes disponíveis. 

Crie o webhook de resposta

Crie um arquivo chamado public/index.php. O código abaixo inicializa o aplicativo Slim, carrega suas variáveis de ambiente, registra um manipulador de webhook de resposta e retorna o NCCO como uma resposta JSON sempre que a Vonage fizer uma solicitação GET para /webhooks/answer. 

Ele também registra um webhook de evento em /webhooks/event para o qual a Vonage envia atualizações do status da chamada (como “toque”, “atendida” e “concluída”) ao longo de todo o ciclo de vida da chamada. Por enquanto, o manipulador simplesmente confirma o recebimento com uma 204 No Content resposta; em um aplicativo de produção, você registraria esses eventos em log ou tomaria medidas a respeito deles. 

<?php 
 
use Psr\Http\Message\ServerRequestInterface as Request; 
use Psr\Http\Message\ResponseInterface as Response; 
use Slim\Factory\AppFactory; 
 
require __DIR__ . '/../vendor/autoload.php'; 
 
// Load environment variables from .env 
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../'); 
$dotenv->load(); 
 
$app = AppFactory::create(); 
 
$app->get('/webhooks/answer', function (Request $request, Response $response): Response { 
    $ncco = [ 
        [ 
            'action' => 'talk', 
            'text'   => 'The amount of visible light from a lamp is measured in lumens.', 
        ], 
    ]; 
 
    $response->getBody()->write(json_encode($ncco)); 
    return $response->withHeader('Content-Type', 'application/json'); 
}); 
 
$app->get('/webhooks/event', function (Request $request, Response $response): Response { 
    // Vonage sends call status updates (ringing, answered, completed) here. 
    // Log or handle them as needed. 
    return $response->withStatus(204); 
}); 
 
$app->run(); 

Quando a Vonage envia uma solicitação GET para a sua URL de resposta, o manipulador retorna um NCCO codificado em JSON. Desde que a resposta seja um JSON válido no formato correto, a Vonage sabe como lidar com a chamada. 

Hora de testar! Salve o arquivo e, em seguida, ligue para o número virtual que você comprou para ouvir sua mensagem de conversão de texto em voz. 

Fazer uma chamada

Você já atendeu uma chamada recebida; agora vamos iniciar uma chamada efetuada. Quando você faz uma chamada efetuada, a Vonage continua consultando sua URL de resposta para determinar como lidar com ela; portanto, o webhook que você acabou de criar servirá para ambos os sentidos. 

Para fazer uma chamada de saída, precisaremos do SDK PHP da Vonage: 

composer require vonage/client 

Agora adicione as seguintes instruções `use` no início de public/index.php, após as já existentes: 

use Vonage\Client\Credentials\Keypair; 
use Vonage\Voice\OutboundCall; 
use Vonage\Voice\Endpoint\Phone; 
use Vonage\Voice\Webhook; 

Em seguida, adicione a rota antes de $app->run(): 

$app->get('/makeCall/{number}', function (Request $request, Response $response, array $args): Response { 
    $keypair = new Keypair( 
        file_get_contents(__DIR__ . '/../private.key'), 
        $_ENV['VONAGE_APPLICATION_ID'] 
    ); 
 
    $client = new \Vonage\Client($keypair); 
 
    $outboundCall = new OutboundCall( 
        new Phone($args['number']), 
        new Phone($_ENV['VONAGE_NUMBER']) 
    ); 
 
    $outboundCall->setAnswerWebhook( 
        new Webhook($_ENV['BASE_URL'] . '/webhooks/answer', Webhook::METHOD_GET) 
    ); 
 
    $client->voice()->createOutboundCall($outboundCall); 
 
    $response->getBody()->write(json_encode(['status' => 'call initiated'])); 
    return $response 
        ->withHeader('Content-Type', 'application/json') 
        ->withStatus(200); 
}); 

Para iniciar uma chamada de saída, acesse a seguinte URL no seu navegador, substituindo DESTINATION_NUMBER pelo número para o qual deseja ligar no formato E.164 (por exemplo, 14155550100 para um número nos EUA): 

https://YOUR_NGROK_URL/makeCall/DESTINATION_NUMBER 

Adicionar NCCOs dinâmicos

Você conseguiu o que se propôs a fazer, mas fica um pouco repetitivo ouvir a mesma mensagem todas as vezes. Vamos tornar isso mais dinâmico, exibindo uma piada aleatóriado JokeAPI elê-la durante a chamada. 

Para fazer solicitações HTTP, instale o Guzzle: 

composer require guzzlehttp/guzzle 

Adicione a instrução de uso do Guzzle no início do arquivo index.php: 

use GuzzleHttp\Client as GuzzleClient; 

Agora atualize o /webhooks/answer manipulador para buscar uma piada e usá-la como texto falado: 

$app->get('/webhooks/answer', function (Request $request, Response $response): Response { 
    $guzzle = new GuzzleClient(); 
    $apiResponse = json_decode( 
        $guzzle->get('https://v2.jokeapi.dev/joke/Programming?type=twopart&safe-mode')->getBody() 
    ); 
 
    // JokeAPI returns a two-part joke with a 'setup' and 'delivery' field. 
    $joke = $apiResponse->setup . ' ' . $apiResponse->delivery; 
 
    $ncco = [ 
        [ 
            'action' => 'talk', 
            'text'   => $joke, 
        ], 
    ]; 
 
    $response->getBody()->write(json_encode($ncco)); 
    return $response->withHeader('Content-Type', 'application/json'); 
}); 

JokeAPI é uma API gratuita e mantida ativamente. O type=twopart parâmetro retorna piadas com setup e delivery campos, e safe-mode filtra conteúdo explícito. O manipulador as concatena em uma única sequência de caracteres para que a ação “talk” as leia em voz alta. 

Agora, sempre que a Vonage solicitar sua URL de resposta — seja para uma chamada recebida ou para uma chamada efetuada por você —, ela buscará uma piada nova sobre programação e a lerá em voz alta. Teste isso ligando para o seu número da Vonage ou clicando no /makeCall ponto de extremidade. 

E agora?

Você desenvolveu um sistema de chamadas de voz com conversão de texto em fala que lida tanto com chamadas recebidas quanto com chamadas efetuadas e fornece conteúdo dinâmico.

A partir daqui, você poderia: 

  • Crie um sistema de alerta por Voice — percorra uma lista de contatos, faça chamadas em massa e peça aos destinatários que pressionem uma tecla para confirmar o recebimento 

  • Personalize a mensagem de acordo com quem está ligando, a hora do dia ou os dados do seu próprio banco de dados 

Tem alguma dúvida ou quer compartilhar o que está criando?

Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.

Compartilhar:

https://a.storyblok.com/f/270183/372x373/36054b72d0/julia-biro.png
Julia BiroRepresentante de Desenvolvedores

Julia está empenhada em capacitar outros desenvolvedores por meio da criação de tutoriais, guias e recursos práticos. Com experiência em divulgação e educação, ela busca tornar a tecnologia mais acessível e aprimorar a experiência geral dos desenvolvedores. É comum encontrá-la em eventos da comunidade local.