Codificar webhooks da Twilio em Java com o Spring Boot

Tempo de leitura: 4 minutos

May 07, 2019

Escrito por

Twilion

Codificar webhooks da Twilio em Java com o Spring Boot

As APIs da Twilio possibilitam a comunicação de várias maneiras: por telefone, WhatsApp, Facebook, SMS, entre outras. Geralmente, quando acontecem eventos como mensagens ou chamadas recebidas, a plataforma Twilio faz uma solicitação HTTP a um servidor especificado pelo usuário para descobrir o que deve fazer; esses eventos são chamados de webhooks. Os servidores HTTP podem ser escritos com qualquer tecnologia para responder a esses webhooks e, no caso dos desenvolvedores Java, a estrutura mais popular é o Spring Boot.

Neste post, vamos criar um app Spring Boot capaz de responder a chamadas telefônicas recebidas reproduzindo uma breve mensagem para os autores das chamadas, seguida pela maravilhosa canção de Rogers e Hammerstein, "It Might As Well Be Spring".

Requisitos

Criar um app Spring Boot

O pessoal do Spring criou o Spring Initializr, que permite criar um projeto rapidamente. Acesse https://start.spring.io e configure um novo projeto da seguinte maneira:

Tela de criação de um novo app Spring Boot

Use o Maven ou o Gradle, escolha nomes para Group e Artifact que sejam adequados e use o campo Search dependencies to add (Procurar dependências a serem adicionadas) para adicionar a dependência Web. Clique no botão Generate Project (Gerar projeto) para fazer download do projeto no formato de arquivo zip, que poderá ser descompactado e importado para um IDE.

Em src/main/java, existem pastas correspondentes ao nome Artifact e uma classe Java chamada PhoneCallWebhookApplication.java. Essa é a classe principal do projeto; ela foi anotada com @SpringBootApplication e tem um método main. A anotação @SpringBootApplication configura muitos padrões úteis para o Spring, como o servidor HTTP incorporado e a verificação de componentes.

Crie uma classe chamada WebhookController no mesmo pacote da classe Application criando um arquivo chamado WebhookController.java no mesmo diretório do arquivo PhoneCallWebhookApplication.java. A classe Controller armazenará o código do webhook. Uma anotação @Controller garantirá que ela seja encontrada pela verificação de componentes do Spring. O Spring registrará automaticamente os endpoints HTTP dos métodos anotados com @GetMapping.

Para a primeira iteração, a classe WebhookController deve ser parecida com o seguinte:

    // The package name may be different depending on
    // what the Group and Artifact of the project are
package lol.gilliard.phonecallwebhook;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
public class WebhookController {

    @GetMapping("/call")
    @ResponseBody
    public String respondToPhoneCall(){
         return "Welcome to Spring Boot";
    }
}

Esse código é suficiente para um servidor Web em funcionamento. Antes de avançarmos, podemos testá-lo. O projeto contém um script wrapper para Maven ou Gradle, por isso você deve criá-lo e executá-lo com um destes dois comandos. Se esta for a primeira vez que ele é executado, poderá haver muitas dependências para download, então dá tempo de você aprimorar seu desempenho ao piano.

./mvnw clean package
java -jar target/phone-call-webhook-0.0.1-SNAPSHOT.jar

./gradlew clean build
java -jar ./build/libs/phone-call-webhook-0.0.1-SNAPSHOT.jar

Enquanto ele estiver em execução, acesse http://localhost:8080/call para ver a mensagem de boas-vindas:

Tela do navegador com a url aberta e mensagem de boas-vindas

Como responder a um webhook da Twilio

A resposta a um webhook da Twilio normalmente deve ser um tipo de XML que chamamos de TwiML. É possível escrever o TwiML manualmente, mas, para qualquer outra coisa além dos casos mais simples, recomendo usar a biblioteca auxiliar Java. Adicione a biblioteca auxiliar ao projeto colocando-a na seção <dependencies> do arquivo pom.xml:

<dependencies>
    ...
    <dependency>
        <groupId>com.twilio.sdk</groupId>
        <artifactId>twilio</artifactId>
        <version>7.37.4</version>
    </dependency>
    ... 
</dependencies>

Faça alterações na classe WebhookController para ficar assim:

    // The package name may be different depending on
    // what the Group and Artifact of the project are
package lol.gilliard.phonecallwebhook;
    
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Play;
import com.twilio.twiml.voice.Say;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.concurrent.atomic.AtomicInteger;

@Controller
public class WebhookController {

   private AtomicInteger callerNumber = new AtomicInteger();

   @GetMapping(path="/call", produces="application/xml")
   @ResponseBody
   public String respondToPhoneCall() {

       VoiceResponse.Builder voiceBuilder = new VoiceResponse.Builder();

       Say greeting = new Say.Builder("Hello caller number " + callerNumber.incrementAndGet()).build();
       Play music = new Play.Builder("https://static.gilliard.lol/Might_As_Well_Be_Spring.mp3").build();

       return voiceBuilder.say(greeting).play(music).build().toXml();
   }
}

Compile e execute novamente usando o Maven ou o Gradle, como antes. Agora, quando você acessar http://localhost:8080/call, verá o TwiML gerado pela biblioteca auxiliar:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello caller number 1</Say>
    <Play>https://static.gilliard.lol/Might_As_Well_Be_Spring.mp3</Play>
</Response>

Git Start Wars dizendo 'está funcionando' em inglês

Usar o ngrok para desenvolver webhooks

Para a Twilio acessar o webhook, localhost não será suficiente. O serviço precisa estar em um URL que possa ser acessado pela Internet. O ngrok é uma ótima ferramenta para desenvolver webhooks. Ele fornece um URL temporário que pode ser acessado pela Internet para seu ambiente de desenvolvimento. Instale-o e execute o seguinte em uma nova janela de terminal:

ngrok http 8080

O ngrok criará URLs http e https públicos que redirecionam para localhost:

Tela parcial do Ngrok com as URLs para teste

Sempre recomendo usar https, por isso utilize o URL https em vez de "localhost" no endereço do webhook. Os nomes de host do ngrok sempre serão diferentes; você pode verificar o nome do seu em um navegador antes de prosseguir.

Configurar um número de telefone da Twilio

Depois de fazer login em sua conta da Twilio, vá para a página de números de telefone e compre um novo número em seu país, não se esquecendo de marcar a caixa do recurso Voice:

Tela parcial do console da Twilio com a opção de compra de número de telefone

Depois de escolher um número, você deverá ir à página de gerenciamento de números de telefone para configurar o que a plataforma Twilio deve fazer em resposta às chamadas e mensagens recebidas. Aqui, coloque o URL do ngrok como o webhook para chamadas recebidas e, por causa da anotação @GetMapping, escolha também HTTP GET:

Tela parcial do console da Twilio com as configurações de webhook de um número de telefone

Salve essa configuração e pronto! Ligue para seu número de telefone da Twilio e ouça essa música sensacional.

Para recapitular: Quando o número é chamado, a Twilio faz uma solicitação ao URL do ngrok encapsulado para o app Spring Boot. O app responde com o TwiML criado na classe controller e a Twilio reproduz a saudação e a música para o autor da chamada. Tudo isso em dez linhas de código. Muito bom, né?

Gif de um homem com um hoodie amarelo balançando a cabeça confirmando

Um lugar permanente na nuvem

Desenvolver webhooks usando o ngrok é bom, mas não será possível acessar o URL quando o computador estiver desligado ou se o comando ngrok for cancelado. Para uma solução mais confiável, a documentação do Spring lista várias recomendações de lugares para implementar aplicativos de modo permanente; só não se esqueça de atualizar o URL na página de configuração de número de telefone.

O que vem a seguir?

Acabamos de mostrar apenas superficialmente o que podemos fazer com o Spring Boot; existem vários outros projetos do Spring para criar apps mais complexos, usar datastores SQL ou NoSQL, implementar na nuvem e muito mais. E, é claro, a Twilio tem muito mais a oferecer do que só ficar reproduzindo músicas ao telefone! Consulte todos os documentos da Twilio, confira os outros inícios rápidos de Java ou divirta-se aprendendo enquanto joga o Twilio Quest.

Este artigo foi traduzido do original "Coding Twilio Webhooks in Java with Spring Boot". Enquanto melhoramos nossos processos de tradução, adoraríamos receber seus comentários em help@twilio.com - contribuições valiosas podem render brindes da Twilio.