Início rápido do Programmable Voice para PHP
Com apenas algumas linhas de código, seu aplicativo da Web PHP pode fazer e receber chamadas telefônicas com o Programmable Voice da Twilio.
Este início rápido do PHP Voice ensina você a fazer isso usando a API REST, a biblioteca auxiliar PHP da Twilio, o servidor Web de desenvolvimento PHP integrado e o ngrok para expor seu servidor local à Twilio.
Usaremos o gerenciador de pacotes do Composer para o gerenciamento de dependências (não quer? Experimente o nosso Início rápido de voz PHP sem Composer).
Neste início rápido, você aprende a:
- Inscrever‐se na Twilio e obter o primeiro número de telefone Twilio habilitado para voz
- Verificar e instalar todos os pré‐requisitos PHP usando o Composer
- Fazer uma chamada telefônica e reproduzir um MP3
- Receber e responder a uma chamada telefônica de entrada para ler uma mensagem para o autor da chamada usando conversão de voz
Prefere começar assistindo a um vídeo? Confira nosso vídeo sobre como fazer e receber chamadas telefônicas com o PHP.
Inscreva‐se na Twilio e obtenha um número de telefone
Já tem uma conta e um número de telefone Twilio habilitado para voz? Faça login e vá para a próxima etapa.
You can sign up for a free Twilio trial account here.
- When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity and also allows you to make calls to your phone from your Twilio account while in trial mode.
- Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
- Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console. This is where you'll be able to access your Account SID, authentication token, find a Twilio phone number, and more.
If you don't currently own a Twilio phone number with Voice functionality, you'll need to purchase one. After navigating to the Buy a Number page, check the "Voice" box and click "Search."
You’ll then see a list of available phone numbers and their capabilities. Find a number that you like and click "Buy" to add it to your account.
Instalar o PHP e a biblioteca auxiliar do Twilio PHP
Se você já tem o PHP e a biblioteca auxiliar Twilio PHP instalada em seu diretório de trabalho, você está pronto para esta etapa. Fique à vontade para pular e passar para o envio de sua primeira mensagem de texto.
Para fazer sua primeira chamada de voz de saída, vamos certificar‐se de que você está configurado com PHP e capaz de instalar a biblioteca auxiliar PHP do Twilio.
Ao fazer o desenvolvimento da Web no PHP, sugerimos enfaticamente o uso do Composer para o gerenciamento de pacotes. Este início rápido depende do Composer para instalar a biblioteca auxiliar do PHP. (Se você prefere não usar o Composer, pode encontrar instruções de instalação manual do Twilio PHP na página da biblioteca auxiliar do PHP).
Instalar o PHP
Se você estiver usando uma máquina Mac ou *nix, provavelmente já tem o PHP instalado. Execute no terminal:
php --version
Se o PHP não estiver instalado, siga as instruções de instalação do PHP.
Se você estiver usando uma máquina Windows, siga o tutorial oficial de instalação do PHP.
Embora muitas versões do PHP 7.x funcionem para este início rápido, preste atenção às versões compatíveis do PHP. Ao fazer o desenvolvimento Web, sempre atualize o PHP para uma versão que receba atualizações de segurança.
Instalar o Composer para gerenciamento de pacotes
O Composer é o gerenciador de pacotes canônico de fato para desenvolvimento Web PHP. Para este tutorial, o Composer é obrigatório. Se você deseja instalar o Composer, experimente o nosso Início rápido sem o Composer PHP Voice.
Instalar a biblioteca auxiliar do Twilio PHP
Agora precisamos instalar a biblioteca auxiliar do Twilio PHP.
Primeiro, navegue até o diretório onde você concluirá este início rápido e escolha um dos seguintes métodos para instalar a biblioteca auxiliar.
Em um terminal, você pode executar o seguinte comando:
composer require twilio/sdk
Ou, você pode criar um arquivo chamado composer.json
em vez disso. Nesse arquivo, adicione:
{
"require": {
"twilio/sdk": "^5.0"
}
}
Em seguida, execute
composer install
O Composer irá pegar a versão 5.x mais recente da biblioteca auxiliar do Twilio PHP.
Para não usar o Composer, experimente este Início rápido do PHP Voice.
Faça uma chamada telefônica com o PHP
Agora que temos o PHP e a biblioteca auxiliar do PHP instalados, podemos fazer uma chamada telefônica em uma única solicitação de API. Crie um novo arquivo chamado make_call.php
e digite ou cole nesta amostra de código.
Ao executar o código, ele iniciará uma chamada telefônica entre os dois números passados como argumentos. Adicionamos duas variáveis para mostrar o número "From" (De) e "To" (Para) e elas serão mapeadas assim:
- (From) /
twilio_number
: O número de telefone Twilio que você adquiriu - (To) /
to_number
: O número a ser chamado (talvez seu telefone celular?)
Dentro do array, o argumento url
aponta para algum TwiML. TwiML é uma linguagem que a Twilio usa internamente para iniciar ou responder a ações, como uma sequência para uma chamada de voz. Este TwiML em particular faz com que a Twilio leia uma mensagem com texto para fala e depois reproduza um MP3 para o número "To" (Para) to_number
.
Antes de executar esse código, você precisa trocar alguns valores específicos da conta.
Substituir as credenciais de espaço reservado por suas próprias
Substitua os valores de espaço reservado para account_sid
e auth_token
com suas credenciais de conta Twilio.
Para encontrá‐los, faça login em https://www.twilio.com/console. Nesta página, você encontrará seu Account SID
(SID da conta) e o Auth Token
(token de autenticação) exclusivos. É possível revelar o Auth Token
ao clicar no ícone de "olho":
Abra make_call.php
e substitua os valores de account_sid
e auth_token
por seus valores exclusivos.
Observação: É mais fácil codificar as credenciais para este início rápido, mas você deve usar variáveis de ambiente para mantê‐las secretas na produção. Confira como definir variáveis de ambiente para obter mais informações e veja os comentários do código para um exemplo de leitura. Este repositório também é uma excelente referência para variáveis de ambiente no PHP.
Substituir o número de telefone twilio_number
Você já comprou ou encontrou um número de telefone habilitado para voz. Cole o número na variável twilio_number
usando a formatação E.164:
[+][código do país][número de telefone incluindo código de área]
Por exemplo, +18005551212
.
Substituir o número de telefone to_number
Novamente usando a formatação E.164, substitua o número de telefone que receberá a chamada efetuada. Use um número de telefone pessoal aqui para receber a chamada e ouvir a magia depois de executar o código.
Se você estiver usando uma conta de avaliação Twilio, só poderá fazer chamadas para números de telefone verificados com a Twilio. Os números de telefone podem ser verificados com os IDs de autor da chamada verificados do console Twilio. Para conhecer as limitações completas da conta de avaliação, consulte nosso guia sobre como trabalhar com a conta de avaliação gratuita da Twilio.
Salve o script e invoque-o para testar uma chamada efetuada. Para OSX e *NIX, isso será semelhante a:
php make_call.php
Se você substituiu tudo corretamente, logo ouvirá uma ótima mensagem e uma música nova! Caso contrário, não desista e siga as instruções do console.
Receber e atender a chamadas de voz inbound com o PHP
Quando alguém liga para o número de telefone Twilio, a Twilio faz uma solicitação HTTP para o servidor para obter instruções sobre como lidar com a chamada. Para este início rápido, atenderemos ao remetente e agradeceremos por sua ligação om os recursos de conversão de voz da Twilio.
Novamente, usaremos a biblioteca PHP da Twilio para esta etapa. Usaremos o servidor de desenvolvimento Web integrado do PHP em combinação com o ngrok para instruir a Twilio sobre como gerenciar a chamada.
Crie um novo arquivo, answer_call.php
, no mesmo diretório que make_call.php
. Em seguida, copie e cole ou digite o código a seguir.
(Observação: se você não usar o mesmo diretório de quando fizemos nossa primeira chamada, siga a etapa de instalação da biblioteca auxiliar do PHP)
Salve answer_call.php
e inicie um servidor de desenvolvimento PHP local com:
php -S localhost:8000
Em uma guia do navegador, abra o URL http://localhost:8000/answer_call.php.
Se tudo correu bem, agora você deve ver o XML no navegador com a mensagem que gostaríamos de ler para as chamadas recebidas. Você só precisa desse código. Há apenas mais algumas etapas antes que tudo esteja conectado.
Em seguida, vamos expor esse endpoint ao Twilio.
Permitir que a Twilio se comunique com o aplicativo PHP
Antes que possamos instruir a Twilio sobre o que fazer em resposta a uma chamada recebida, primeiro você precisa expor seu servidor ao público. Quando você executa seu servidor de desenvolvimento local, as chances são muito altas, ele só é acessível na rede local. Mas não se preocupe, mostraremos uma maneira fácil de testar o servidor.
Muitos produtos e serviços da Twilio usam webhooks para se comunicar com seu aplicativo. Por exemplo, quando a Twilio recebe uma chamada, ela acessa um URL específico fornecido para pesquisar instruções sobre como lidar com a resposta. O pequeno código em answer_call.php
é um exemplo de uma instrução que você pode usar para "retornar" ao autor da chamada. No entanto, ao executar o servidor, ele só será exposto a você localmente, não ao público em geral. Precisamos descobrir uma maneira de corrigir isso.
Embora haja muitas maneiras de tornar esse código público (por exemplo, implantando‐o em um host), recomendamos uma ferramenta chamada ngrok. Ao iniciar o ngrok, ele fornece um URL exclusivo no domínio ngrok.io e encaminha as solicitações recebidas para seu ambiente de desenvolvimento local.
A arquitetura fica assim:
Se você ainda não usa o ngrok, visite a página de download e instale‐o no seu sistema operacional.
Se estiver trabalhando no Mac ou Linux, estará tudo pronto depois de descompactá‐lo. Se você estiver no Windows, siga nosso guia sobre como instalar e configurar o ngrok no Windows. Para mais informações sobre o ngrok (incluindo algumas ótimas dicas e truques), confira nossa esta postagem no blog do ngrok.
Depois de baixar um ngrok de instalação, abra uma nova guia ou janela do terminal (deixando seu servidor de desenvolvimento em execução) e inicie‐o com este comando:
./ngrok http 8000
A saída deve ser semelhante a esta:
Copie o URL público desta saída, cole‐o no navegador e anexe answer_call.php
. Você deve ver o mesmo XML que viu anteriormente, exceto que agora você pode acessá‐lo de qualquer lugar com acesso à Internet.
Agora que você é público, vamos dizer a Twilio onde encontrar o servidor.
Configurar o webhook do URL
Agora que seu servidor está acessível publicamente, você precisa configurar seu número de telefone Twilio para acessar o URL do webhook quando novas chamadas forem recebidas.
- Visite a página Números do console.
- Clique em seu número de telefone habilitado para voz.
- Localize a seção "Voice & Fax" (Voz e fax). Verifique se a seleção "Accept Incoming" (Aceitar entrada) está definida como "Voice Calls" (Chamadas de voz). A seleção padrão "Configure With" (Configurar com) é o que você precisa: "Webhooks/TwiML...".
- Na seção "A Call Comes In" (Uma chamada é recebida), selecione "Webhook" e cole a URL que deseja usar, anexando
/answer_call.php
:
Salve as alterações e você estará pronto para começar!
Teste seu aplicativo
Se o servidor de desenvolvimento local ainda estiver em execução e o ngrok ainda estiver funcionando, você está pronto para a parte divertida: testar!
Faça uma chamada telefônica para o número de telefone Twilio. Você verá e ouvirá várias coisas acontecerem em breve sucessão:
- Você verá uma solicitação HTTP no console do ngrok
- O servidor de desenvolvimento imprimirá algumas mensagens para o console
- Você ouvirá a mensagem assim que a chamada for conectada
Pronto. As chamadas de outbound e inbound com PHP estão funcionando.
Para onde ir em seguida?
Agora você conhece o básico para fazer e responder a chamadas telefônicas com PHP.
Este aplicativo PHP usou apenas o verbo TwiML <Say> para ler uma mensagem para o autor da chamada usando conversão de voz. Com diferentes verbos TwiML, você pode criar outras construções poderosas e fluxos de chamada. Experimente alguns, como <Record>, <Gather> e <Conference>.
Confira estas páginas para saber mais:
- Reunir a entrada do usuário pelo teclado (tons DTMF) no PHP
- Como gravar chamadas telefônicas recebidas e efetuadas do Twilio Voice usando PHP
- Criar chamadas em conferência usando PHP
- Leia a documentação de referência da API Programmable Voice da Twilio
- Saiba como modificar chamadas em andamento com o PHP
- Usar o Twilio Client para integrar chamadas VoIP de alta qualidade a um aplicativo da Web ou para dispositivos móveis.
- Recuperar informações sobre chamadas em andamento e concluídas de sua conta Twilio usando PHP.
- Confira nosso tutorial de aplicativo completo sobre como transferir chamadas entre agentes de suporte com PHP e Laravel
Estamos ansiosos para ver o que você vai criar!
Precisa de ajuda?
Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.