Início rápido do Programmable Messaging para Java

Quer começar a fazer e receber chamadas telefônicas com o Programmable Voice da Twilio usando Java?

Este Início rápido do Programmable Voice para Java ensina como fazer isso usando a biblioteca auxiliar Twilio Java com a nossa API REST.

Neste início rápido, você aprende a:

Inscrever‐se na Twilio e obter o primeiro número de telefone Twilio habilitado para voz
Configurar o ambiente de desenvolvimento para fazer e receber chamadas telefônicas
Fazer sua primeira chamada telefônica com a Twilio!
Receber e responder a uma chamada telefônica de entrada que leia uma mensagem para o autor da chamada usando conversão de texto em voz

Prefere começar assistindo a um vídeo? Confira nosso vídeo de Início rápido de Voz em Java no Youtube.

Mostre‑me como se faz!

Inscreva-se e obtenha um número de telefone Twilio

Se você já tem uma conta Twilio e um número de telefone Twilio habilitado voz, você tem tudo o que precisamos! Fique à vontade para ir para a próxima etapa.

Antes de fazer uma chamada telefônica em Java, crie uma conta Twilio ou faça login na sua conta já existente para comprar um número de telefone habilitado para voz.

Se atualmente você não possui um número de telefone Twilio com funcionalidade de voz, adquira um. Depois de navegar até a página Buy a Number (Comprar um número), marque a caixa "Voice" (Voz) e clique em "Search" (Pesquisar).

Você verá uma lista de números de telefone disponíveis e seus recursos. Encontre um número que se adapte às suas necessidades e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.

Purchase a voice-enabled phone number from Twilio

Agora que você tem uma conta Twilio e um número de telefone programável, pode começar a criar alguns códigos! Para facilitar ainda mais as coisas, vamos configurar nosso ambiente Java e, em seguida, fazer o download da biblioteca auxiliar oficial da Twilio para aplicativos Java.

Sem problemas! Leve‑me até a configuração.

Configurar o ambiente Java

O ambiente de desenvolvimento Java já está configurado e a biblioteca auxiliar Twilio Java está configurada no classpath? Então pode pular as próximas duas seções e fazer sua primeira chamada telefônica com a Twilio!

Para fazer sua primeira chamada telefônica, é necessária a instalação do Java Standard Edition (SE) Development Kit (JDK). Se você não sabe se o JDK está instalado, execute o comando a seguir para descobrir qual é a sua versão:

javac -version

Você verá algo semelhante ao seguinte:

javac 1.8.0_92

O Twilio SDK requer Java SE 8 ou superior, que aparecerá como número de versão "1.8" ou superior ao executar o comando acima.

Se você tiver uma versão mais antiga do Java ou nenhum JDK, instale o JDK antes de prosseguir. Siga as instruções para instalar o Java SE Development Kit para sua plataforma (Windows, Mac, Linux) na página de download do Java SE.

Faça o download da biblioteca auxiliar autônoma do Twilio Java

O Java está configurado e pronto para o uso? Fantástico!

Em seguida, baixe a biblioteca auxiliar autônoma do Twilio Java. Com essa biblioteca, você terá classes Java que o ajudarão a chamar as APIs do Twilio usando Java, juntamente com todas as outras dependências necessárias para começar. Ao fazer o download do arquivo jar, baixe o arquivo com um nome semelhante a twilio-8.x-jar-with-dependencies.jar.

Prefere usar Maven, Grace ou outra ferramenta de compilação?

Com o Maven, coloque o seguinte na tag <dependencies> no arquivo pom.xml:

<dependency>
  <groupId>com.twilio.sdk</groupId>
  <artifactId>twilio</artifactId>
  <version>8.0.0</version>
</dependency>

Com o Gradle, cole a próxima linha dentro do bloco dependencies do arquivo build.gradle:

compile group: "com.twilio.sdk", name: "twilio", version: "8.0.+"

Se você estiver usando um IDE Java para criar o aplicativo, é possível especificar o ID do grupo, o ID do artefato e o número da versão para suas dependências.

Independentemente do gerenciador de pacotes utilizado, especifique a versão mais recente da biblioteca de ajuda do Twilio Java. Localize o número da versão mais recente na página da biblioteca auxiliar do Twilio Java.

Esta biblioteca auxiliar do Twilio Java não se destina ao uso em aplicativos Android! Use esta biblioteca para servidores, aplicativos de linha de comando e projetos semelhantes. Enviar o Account SID (SID da conta) Twilio e o Auth Token (token de autenticação) para usuários finais é um risco de segurança para a conta Twilio.

Se você quiser fazer ou receber chamadas telefônicas de um aplicativo móvel (Android ou iOS), use o SDK Programmable Voice da Twilio. Confira essa página para obter instruções sobre como começar!

Tudo pronto! Vamos fazer uma chamada telefônica!

Fazer uma chamada telefônica com Java

Agora que temos a configuração do JDK e a biblioteca auxiliar do Twilio Java foi baixada, podemos fazer uma chamada telefônica do número de telefone Twilio que acabamos de adquirir com uma única solicitação de API. Crie e abra um novo arquivo chamado MakePhoneCall.java e digite ou cole este exemplo de código.

Loading Code Sample...

Example JSON response

Make Phone Call using Twilio

É necessário editar este arquivo um pouco mais antes que sua chamada telefônica funcione:

Substitua os valores de credencial do espaço reservado

Troque os valores de espaço reservado para ACCOUNT_SID e AUTH_TOKEN com suas credenciais pessoais do Twilio. Faça login em https://www.twilio.com/console. Nesta página, você encontrará seu Account SID (SID da conta) e o Auth Token (token de autenticação) exclusivos, necessários sempre que fizer chamadas telefônicas com a biblioteca auxiliar Twilio Java. Você pode revelar seu Auth Token (token de autenticação) clicando no ícone de olho:

Abra MakePhoneCall.java e substitua os valores ACCOUNT_SID de e AUTH_TOKEN por seus valores exclusivos.

Observação: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de implantar na produção. Confira como definir variáveis de ambiente para obter mais informações.

Substituir o número de telefone "from" (de)

Lembra daquele número de telefone habilitado para voz que você acabou de comprar? Use‐o para substituir o número from (de) existente, use a formatação E.164:

[+][código do país][número de telefone incluindo código de área]

Substituir o número de telefone "to"

Substitua o número de telefone to (para) pelo número de telefone. Pode ser qualquer número de telefone, mas é recomendável testar com o seu telefone para ver a magia em ação! Como acima, você deve usar a formatação E.164 para esse valor.

Salve as alterações e compile esta classe Java no terminal:

javac -cp twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall.java

Precisamos incluir esse jar da Twilio com as dependências para compilar nossa classe na linha de comando. Se você estiver usando um IDE (Integrated Development Environment, ambiente de desenvolvimento integrado) como IntelliJ IDEA, Netbeans ou Eclipse, pode simplesmente adicionar esse jar da Twilio ao classpath ou às suas bibliotecas de projeto como qualquer outra dependência. Você também pode usar uma ferramenta de compilação como Maven ou Gradle para compilar e executar seu aplicativo Java. Basta especificar a biblioteca auxiliar da Twilio como uma dependência.

Depois de criar a classe Java, execute‐a. Se estiver executando na linha de comando no macOS ou Linux, o comando ficará da seguinte forma:

java -cp .:twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall

No Windows, o comando equivalente é o seguinte:

java -cp .;twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall

A diferença é que no Windows, o separador de classpath Java na linha de comando é um ponto e vírgula, e no macOS ou Linux, é um ponto‐e‐vírgula.

É isso! Em alguns momentos, você deve receber uma chamada telefônica do número Twilio em seu telefone.

Se você estiver em uma conta de avaliação da Twilio, suas chamadas de voz serão limitadas aos números de telefone verificados com a Twilio. Os números de telefone podem ser verificados por meio dos IDs de autor da chamada verificados do console Twilio.

Eu fiz a chamada telefônica! Como recebo chamadas?

Receber e responder a chamadas telefônicas recebidas

Quando o número Twilio recebe uma chamada telefônica, a Twilio envia uma solicitação HTTP para um servidor que você controla. Esse mecanismo de retorno de chamada é conhecido como webhook. Quando a Twilio envia uma solicitação ao seu aplicativo, ela espera uma resposta no formato XML do TwiML informando como responder à mensagem.

Vamos ver como criaríamos isso em Java usando a estrutura de aplicativos da Web Spark. O Spark é uma estrutura de aplicativos da Web leve e é completamente diferente do software de big data chamado Apache Spark.

O Spark requer sua própria biblioteca, separada da biblioteca auxiliar Twilio Java, que você pode instalar seguindo as instruções na página Download Spark Java. Você encontrará instruções para usar o Spark com Maven, Gradle ou como um download independente. O Spark não vem com uma implementação de log, mas funciona com o Simple Logging Facade 4 Java (SLF4J), que você também pode incluir em seu classpath Java.

Você certamente pode configurar todas as suas dependências na linha de comando, como fizemos na seção acima quando fizemos uma chamada telefônica pela Twilio, mas é um pouco mais fácil configurar tudo com um IDE (Integrated Development Environment, ambiente de desenvolvimento integrado) Java. Vamos usar a edição gratuita da comunidade do IntelliJ IDEA, que você pode baixar do JetBrains. Você pode fazer download de arquivos JAR e usá‐los diretamente com o IntelliJ IDEA ou pode usar um gerenciador de dependências como Maven ou Gradle. Usaremos o Gradle com o IntelliJ IDEA para construir nosso aplicativo.

Criação um aplicativo da Web com IntelliJ IDEA e Gradle

Se você ainda não baixou e instalou o IntelliJ IDEA Community Edition, vá em frente e faça isso agora! Depois de executar o IDEA pela primeira vez, você verá uma tela semelhante a esta:

Escolha "Create New Project" (Criar novo projeto) e o novo assistente New Project (Novo projeto) será iniciado:

No lado esquerdo dessa caixa de diálogo, escolha Gradle (em vez de Java), para que o IntelliJ IDEA configure o projeto para usar Gradle para gerenciamento de dependências. Você também pode optar por usar o Maven aqui. O processo é quase o mesmo.

Após escolher o Gradle, verifique se o IntelliJ IDEA tem um SDK de projeto (é necessário o Java 8 ou superior, portanto, versão 1.8 ou superior) e clique em Next (Avançar).

Voice Quickstart Project Naming with IntelliJ IDEA

Na próxima tela do assistente, será solicitado um group id, um artifact id e um version number. Para o ID do grupo, é possível usar um nome de domínio reverso, como com.suaempresa.voice, e para o ID do artefato, use o nome do seu projeto, como voice-iniciorapido-app. É possível deixar a versão como 1.0-SNAPSHOT. Depois de preencher esses campos, clique em Next (Avançar).

Nesta tela de configurações do Gradle, você pode deixar os padrões e clicar em Next (Avançar).

Por último, você pode confirmar o nome do projeto e o diretório do projeto a ser usado para seu aplicativo Início rápido da Web. Os padrões provavelmente também estão bem aqui. Clicar em Finish (Concluir) levará você ao seu novo projeto IntelliJ. Se você acabou de instalar o IntelliJ IDEA, o IDE fará o download o Gradle e fará algumas configurações e instalações.

Gradle Sync during Java Voice Quickstart Setup

Agora que temos o nosso projeto configurado, temos apenas mais alguns passos! Precisaremos da biblioteca auxiliar do Twilio Java e da estrutura de aplicativos Web do Spark Java como dependências, juntamente com a implementação de log para que possamos ver mensagens de status do Spark. Com o Gradle, podemos adicioná‐los ao arquivo build.gradle que o IntelliJ criou. Vá em frente e encontre build.gradle na barra lateral e clique nele para abri‐lo.

Loading Code Sample...

Example JSON response

Voice Quickstart for Java build.gradle file

Adicione dependências em build.gradle

Você precisará adicionar três linhas ao seu arquivo build.gradle, no grupo de dependências:

compile group: "com.twilio.sdk", name: "twilio", version: "8.0.+"
compile group: "com.sparkjava", name: "spark-core", version: "2.7.1"
compile group: "org.slf4j", name: "slf4j-simple", version: "1.7.21"

Com essas três dependências, o Gradle fará o download das bibliotecas apropriadas para você e as adicionará ao classpath para criar e executar seu aplicativo Java.

Agora que temos tudo isso fora do caminho, é hora de escrever algum código!

Responder a uma chamada telefônica recebida

Precisamos começar criando uma classe Java em nosso projeto. No IntelliJ IDEA, selecione a pasta java em src e main. Em seguida, abra o menu File (Arquivo) na parte superior da tela. Escolha o submenu New (Novo) e, em seguida, Java Class (Classe Java).

Uma pequena janela pop‐up será exibida e você poderá criar uma nova classe. Nomeie sua classe como VoiceApp: a capitalização é importante porque deve corresponder ao exemplo de código.

Você deve ter um arquivo de código‐fonte VoiceApp.java agora. Copie e cole o código do exemplo de código nesse arquivo de código‐fonte.

Este código Java escutará solicitações HTTP GET de entrada para '/hello', responderá com "Hello Web" e escutará solicitações HTTP POST de entrada para '/' e responderá com marcação TwiML!.

Loading Code Sample...

Example JSON response

Generate TwiML to Say a message

Depois de inserir seu código no lugar, você pode clicar com o botão direito do mouse na classe VoiceApp no esboço do projeto no lado esquerdo e, em seguida, escolher o item de menu Run (Executar) 'VoiceApp.main()'.

O servidor de aplicativos da Web Java Spark começa a escutar na porta 4567.

Tente ir para http://localhost:4567/hello para verificar se o seu servidor está funcionando. Você deve ver "Hello Web" no seu navegador.

Uma coisa importante a ser observada: se você fizer uma alteração em seu código e quiser executar o servidor novamente, será necessário interromper o aplicativo em execução com o botão de parada vermelho. Somente um aplicativo pode usar a porta 4567 por vez, portanto, se você executar seu aplicativo Java enquanto uma versão mais antiga ainda estiver em execução, o novo aplicativo será encerrado imediatamente.

Você precisa tornar seu aplicativo acessível pela Internet. Embora você possa fazer isso de várias maneiras, recomendamos uma ferramenta que forneça uma URL acessível externamente chamada ngrok. Mostraremos como configurar isso a seguir para que seu aplicativo possa receber chamadas telefônicas.

Vamos configurar meu aplicativo para receber chamadas telefônicas.

Permitir que a Twilio fale com seu aplicativo Java com o ngrok

Acabamos de criar um pequeno aplicativo da Web Java para receber chamadas telefônicas. Antes de funcionar, precisamos ter certeza de que a Twilio pode acessar nosso aplicativo.

A maioria dos serviços Twilio usa webhooks para se comunicar com seu aplicativo. Quando a Twilio recebe uma chamada telefônica, por exemplo, ele acessa uma URL em seu aplicativo para obter instruções sobre como lidar com a mensagem.

Quando você está trabalhando em seu aplicativo da Web Java em seu ambiente de desenvolvimento, seu aplicativo só pode ser acessado por outros programas em seu computador, portanto, a Twilio não poderá se comunicar com ele. Precisamos resolver esse problema tornando seu aplicativo acessível pela Internet.

Embora existam muitas maneiras de fazer isso, como implantar seu aplicativo no Heroku ou AWS, você provavelmente desejará uma maneira menos trabalhosa de testar seu aplicativo Twilio. Para uma maneira leve de disponibilizar seu aplicativo na Internet, recomendamos uma ferramenta chamada ngrok. O ngrok escuta na mesma porta em que seu servidor Web local está sendo executado e fornece um URL exclusivo no domínio ngrok.io, encaminhando as solicitações recebidas para seu ambiente de desenvolvimento local. Funciona mais ou menos assim:

How ngrok helps Twilio reach your local server

Se ainda não tiver feito isso, instale o ngrok. Verifique se é a versão do ngrok apropriada para o seu sistema operacional e tome cuidado para que o comando "ngrok" esteja no caminho do seu sistema. Se você estiver trabalhando em um Mac ou Linux, está tudo pronto. Se você estiver no Windows, siga nosso guia sobre como instalar e configurar o ngrok no Windows. Para obter mais informações sobre o ngrok, incluindo ótimas dicas e truques, confira esta postagem detalhada no blog.

O comando a seguir usaria o ngrok para expor a porta 4567 à Internet pública. Digite o seguinte comando na linha de comando:

ngrok http 4567

E você verá uma saída semelhante a esta:

Agora temos um novo URL externo.

Configurar o webhook do URL

Agora, você deve pegar esse URL público e configurá‐lo como um webhook para um dos seus números de telefone no console. Volte para o console, selecione seu número de telefone, altere "A CALL COMES IN" (Uma chamada é recebida) para Webhook e insira a URL externa do seu serviço, como "https://069a61b7.ngrok.io/", como mostrado acima.

Salve suas alterações. Está tudo pronto!

Testar o aplicativo

Verifique se você está executando o comando "ngrok" na linha de comando e executando seu aplicativo da Web a partir do IntelliJ IDEA. Se você reiniciou o ngrok, atualize o webhook no console para usar o URL correto.

Com ambos os servidores em execução, estamos prontos para a parte divertida: testar nosso novo aplicativo da Web Java!

Ligue para o número de telefone Twilio que você configurou com este webhook. Você deve ver uma solicitação HTTP POST com um retorno 200 OK no seu console ngrok. O aplicativo da Web Java responderá a Twilio com sua resposta TwiML, e você ouvirá sua mensagem sendo lida por você!

Funcionou! Tudo pronto. O que vem a seguir?

Para onde ir em seguida?

Agora você conhece os fundamentos de fazer e responder a chamadas telefônicas com Java.

Este aplicativo usou apenas o verbo <Say> TwiML para ler uma mensagem para o autor da chamada usando a conversão de voz. Com diferentes verbos TwiML, você pode criar outras construções poderosas e fluxos de chamada. Experimente alguns, como <Record>, <Gather> e <Conference>.

Confira estas páginas para saber mais:

Explore a documentação de referência da API Programmable Voice
Documentos de referência TwiML
Tutoriais com aplicativos de amostra completos em Java
Como discar e atender chamadas telefônicas com Spark e Java 8 no IntelliJ

Aproveite as dicas!

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.

Make Phone Call using Twilio

Voice Quickstart for Java build.gradle file

Generate TwiML to Say a message

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!