Início rápido do Programmable Voice para Node.js
Com apenas algumas linhas de código, seu aplicativo Node.js pode fazer e receber chamadas telefônicas com o Programmable Voice da Twilio.
Este início rápido do Node.js ensina como fazer isso usando nossa API REST e a biblioteca auxiliar Twilio Node.js para facilitar o desenvolvimento.
Neste início rápido, você aprende a:
- Inscrever‐se na Twilio e obter o primeiro número de telefone Twilio habilitado para voz
- Configurar o ambiente de desenvolvimento para fazer e receber chamadas telefônicas
- Fazer uma chamada telefônica de saída que reproduza um MP3
- Receber e responder a uma chamada telefônica de entrada que leia uma mensagem para o autor da chamada usando conversão de texto em voz
Prefere começar assistindo a um vídeo? Confira nosso vídeo sobre como enviar e receber chamadas telefônicas com o Node.js no YouTube.
Inscreva‐se na Twilio e obtenha um número de telefone
Se já tiver uma conta e um número de telefone da Twilio habilitado para voz, tudo está em ordem! Faça login e fique à vontade para ir para a próxima etapa.
Antes de fazer uma chamada do Node.js, crie uma conta Twilio ou faça login em uma conta que já possui.
A próxima coisa que você precisa é um número de telefone da Twilio com capacidade de voz. Se você não possui atualmente um número de telefone da Twilio com funcionalidade de chamada de voz, precisará adquirir um. Após navegar até a página Comprar um número, marque a caixa "Voice" (Voz) e clique em "Search" (Pesquisar).
Você verá uma lista de números de telefone disponíveis e seus recursos. Encontre um número que se adapte às suas necessidades e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.
Com uma conta Twilio e um número de telefone programável, você tem as ferramentas básicas necessárias para fazer uma chamada telefônica.
Você pode usar a API HTTP da Twilio para fazer suas chamadas telefônicas, mas simplificaremos ainda mais simples usando o módulo Twilio para Node.js. Vamos instalar agora.
Instale o Node.js e o módulo Twilio Node.js
Se você já passou por um de nossos guias de início rápido do Node.js e tem o Node.js e o módulo Twilio Node.js instalados, você pode pular esta etapa e ir direto para fazer a primeira chamada telefônica.
Você pode verificar se já tem o Node.js instalado em sua máquina abrindo um terminal e executando o seguinte comando:
$ node --version
Você deve ver algo como:
$ node --version
v8.9.1
Se estiver na versão 2.11 ou anterior, recomendamos que faça a atualização com a versão mais recente.
Se você não tiver o Node.js já instalado, você pode instalá‐lo com o homebrew, outro gerenciador de pacotes, entrando no seu terminal e digitando isso na linha de comando:
brew install node
Se você tiver uma máquina Windows, instale o nvm-windows para instalar tanto o Node.js quanto o npm, o gerenciador de pacotes Node.js. Os usuários do Windows podem seguir este excelente tutorial aqui.
Instalar o módulo Twilio Node.js
A maneira mais fácil de instalar a biblioteca é usando o npm, o gerenciador de pacotes Node.js que permite instalar as bibliotecas necessárias. Basta ativar um terminal ou uma interface de linha de comando em sua máquina que já tenha o Node e o npm instalados e executar o seguinte comando em um novo diretório.
npm install twilio
Fazer uma chamada telefônica com o Node.js
Vamos fazer bom uso da biblioteca Twilio Node.js.
Com uma única solicitação de API, podemos fazer uma chamada outbound do número de telefone Twilio que acabamos de comprar. Abra um novo arquivo chamado "make_call.js" e digite ou cole no código a seguir.
Esse código inicia uma chamada telefônica entre os dois números de telefone que passamos como argumentos. O número "from" (de) é o nosso número Twilio, e o número "to" (para) é o número para o qual desejamos ligar.
O argumento de URL aponta para alguns TwiML, que informam à Twilio o que fazer quando o destinatário atender o telefone. Este TwiML instrui o Twilio a ler uma mensagem usando conversão de voz e depois reproduzir um MP3.
No entanto, antes que esse código funcione, precisamos editá‐lo um pouco para funcionar com sua conta Twilio.
Substitua os valores de credencial do espaço reservado
Troque os valores de espaço reservado para accountSid e authToken com suas credenciais pessoais do Twilio.
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, que serão necessários sempre que enviar mensagens por meio do Twilio Client como essa. Você pode revelar seu Auth Token (token de autenticação) clicando no ícone de olho:
Abra make_call.js e substitua os valores de accountSid e authToken por seus valores exclusivos.
Observe: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de implantar na produção. Confira como definir variáveis de ambiente para obter mais informações.
Substitua os números de telefone to (para) e from (de)
Lembra daquele número de telefone habilitado para voz que você acabou de comprar? Use‐o para substituir o número from (de) existente, use a formatação E.164:
[+][código do país][número de telefone incluindo código de área]
Em seguida, substitua o número de telefone to (para) pelo seu número de telefone celular. Esse número pode ser para qualquer telefone que possa receber chamadas, mas é recomendável testar com seu telefone para ver a magia em ação! Como acima, você deve usar a formatação E.164 para esse valor.
Salve as alterações e execute o código com o seguinte comando no terminal:
node make_call.jsÉ isso! Seu telefone deve tocar com uma chamada do seu número Twilio e você ouvirá uma breve mensagem nossa. 😉
Se você estiver usando uma conta de avaliação da Twilio, as chamadas telefônicas de saída serão limitadas aos números de telefone verificados com o Twilio. Os números de telefone podem ser verificados por meio dos IDs de autor de chamada verificados do console Twilio. Para outras restrições e limitações da conta de avaliação, consulte nosso guia sobre como trabalhar com sua conta de avaliação gratuita da Twilio.
Em seguida, aprenderemos a responder a uma chamada feita para o número de telefone Twilio. Primeiro, precisaremos colocar um servidor Express em funcionamento.
Receba e responda a chamadas de voz inbound com Node.js e Express
Quando o número Twilio recebe uma chamada telefônica, ele envia uma solicitação HTTP para um servidor que você controla. Esse mecanismo de retorno de chamada é conhecido como webhook. Quando a Twilio envia uma solicitação ao seu aplicativo, ela espera uma resposta no formato TwiML XML que informa como responder à chamada.
Para lidar com chamadas telefônicas recebidas, precisaremos de um aplicativo da Web leve para aceitar solicitações HTTP recebidas da Twilio. Embora você possa usar qualquer número de estruturas da Web para fazer e receber chamadas do aplicativo, usaremos Node.js com a estrutura Express neste início rápido.
Na linha de comando, execute
npm install express --save
Agora vamos criar um arquivo chamado "server.js" e usar o código a seguir para criar um servidor que possa gerenciar as mensagens recebidas.
Execute este servidor com o seguinte comando:
node server.jsSe você abrir a porta local em http://127.0.0.1:1337/, verá que o servidor em execução na porta 1337 retorna algum XML ao navegador com a mensagem que gostaríamos de ler para as chamadas recebidas.
Agora, tudo o que precisamos fazer é expor esse endpoint à Twilio.
Permitir que a Twilio se comunique com seu aplicativo
Antes de instruir a Twilio sobre o que fazer em resposta a uma chamada recebida, primeiro é necessário expor o 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 no server.js é um exemplo de uma instrução que você pode usar para "retornar" ao autor da chamada. Temos apenas de encontrar uma forma de expor este servidor ao público.
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, acesse a página de download e pegue o binário apropriado para o seu sistema operacional. Após o download, descompacte o pacote.
Se você estiver trabalhando em um Mac ou Linux, está tudo pronto. Se você estiver no Windows, siga nosso guia sobre como instalar e configurar o ngrok no Windows. Para obter mais informações sobre o ngrok, incluindo ótimas dicas e truques, confira esta postagem detalhada no blog.
Exponha seu servidor local com o ngrok
Após o download, tente executar o arquivo de servidor que criamos anteriormente:
node server.jsO aplicativo local deve ser executado localmente para que o ngrok cumpra seu papel.
Em seguida, abra uma nova guia ou janela de terminal e inicie o ngrok com este comando:
ngrok http 1337Se o seu servidor local for executado em uma porta diferente, substitua 1337 pelo número de porta correto.
A saída deve ser semelhante a esta:
Copie o URL público desta saída e cole‐o no navegador. Você verá a mensagem "Hello from your pals at Twilio!" (Saudações de seus amigos da Twilio!) no aplicativo Express.
Configurar o webhook da Twilio
Agora, você deve pegar esse URL público e configurá‐lo como um webhook para um dos seus números de telefone no console. Volte para o console, selecione seu número de telefone, altere "A CALL COMES IN" (Uma chamada é recebida) para Webhook e insira a URL externa do seu serviço, como "https://069a61b7.ngrok.io/", como mostrado acima.
Clique em "Save" (Salvar) e retorne ao terminal. Verifique se o ngrok ainda está em execução em uma guia e, em outra, execute o node server.js se ainda não estiver em execução.
Faça uma chamada telefônica para o número de telefone Twilio. Em alguns instantes, você verá uma solicitação HTTP no console do ngrok e ouvirá uma mensagem curta assim que a chamada for conectada.
Pronto. Você fez e recebeu uma chamada com o Node.js com sucesso.
Para onde ir em seguida?
Agora você conhece o básico sobre como fazer e responder a chamadas telefônicas com o Node.js.
Este aplicativo usou apenas o verbo <Say> TwiML para ler uma mensagem para o autor da chamada usando a 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:
- Explore a documentação de referência da API Programmable Voice
- Reunir a entrada do usuário pelo teclado (tons DTMF) no Node.js
- Saiba como gravar chamadas telefônicas recebidas e realizadas no Twilio Voice usando Node.js e Express
- Criar chamadas de conferência com Node.js
- Saiba como modificar chamadas em andamento
- Confira nosso tutorial completo do aplicativo de amostra sobre como transferir chamadas entre agentes de suporte usando Node.js e Express
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.
