
Compartilhar:
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.
Chamadas de voz com conversão de texto em fala usando PHP
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
Node.js e npm para instalar o CLI da Vonage
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/phpdotenvCertifique-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
Adicione a gravação de chamadas usando a ação “Gravar” do NCCO e o guia de gravação da Voice API
Explore a referência da NCCO para adicionar menus de IVR, teleconferências e muito mais
Tem alguma dúvida ou quer compartilhar o que está criando?
Inscreva-se no Boletim Informativo para Desenvolvedores
Siga-nos no X (antigo Twitter) para ficar por dentro das novidades
Assista aos tutoriais no nosso canal do YouTube
Conecte-se conosco na página de desenvolvedores da Vonage no LinkedIn
Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.
Compartilhar:
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.