Como receber e responder SMS com Java e Twilio

Tempo de leitura: 4 minutos

March 23, 2021

Escrito por

Matthew Gilliard

Twilion

Revisado por

Matthew Setter

Twilion

Valeriane Venance

Twilion

Como receber e responder SMS com Java e Twilio

Se você está se perguntando como enviar SMS a partir do código Java, nós já temos o que você precisa. No entanto, as pessoas esperam cada vez mais poder conversar com empresas e serviços, em vez de apenas obter um fluxo interminável de notificações. Para criar apps realmente envolventes e interativos, você também poderá responder às mensagens recebidas.

Para isso, você precisará configurar um URL no console da Twilio. As mensagens recebidas vão acionar as solicitações HTTP para esse URL, e a resposta a essas solicitações webhook vai determinar o que acontecerá em seguida, incluindo o envio de respostas. As respostas devem ser escritas em um código XML chamado Twilio Markup Language ou TwiML.

Nesta postagem, vou orientar você a configurar um servidor da Web usando o Spring Boot para fazer exatamente isso.

Como configurar

Antes de começarmos, você precisará de:

Uma instalação do Java 8 ou mais recente Eu recomendo o SDKMAN! para instalar e gerenciar versões do Java.
Um IDE Java. Eu gosto do IntelliJ IDEA, mas você pode usar um de sua preferência.
Uma conta da Twilio (caso você não tenha uma, cadastre-se aqui gratuitamente e receba US$ 10 de crédito ao mudar de conta)
Um número de telefone da Twilio que possa enviar e receber mensagens SMS
Ou o ngrok ou a Twilio CLI, para que você possa responder a webhooks em seu ambiente de desenvolvimento

A melhor maneira de acelerar um novo projeto Spring Boot é usando o Spring Initializr. Este link levará você a uma configuração inicial com a dependência da Web selecionada e alguns nomes pré-configurados. Carregue essa página, clique em "Gerar" e descompacte o projeto baixado em um diretório vazio. Em seguida, abra o projeto no IDE de sua escolha. Vamos colocar a mão na massa.

Como criar o aplicativo

Ao abrir a base de código, você verá o nível superior do projeto. Abra as pastas aninhadas src/main/java e localize o pacote chamado com.example.twilio.sms, com uma única classe, chamada RespondToSmsWithTwilioAndJavaApplication. Você não precisará editar essa classe, mas ela tem main um método que será útil mais tarde.

Como criar um endpoint HTTP

Por enquanto, crie outra classe no mesmo pacote com a seguinte definição e a chame SmsWebhookHandler:

@RestController
public class SmsWebhookHandler {
    @PostMapping("/")
    @ResponseBody
    public String handleSmsWebhook(){
      return "Hello from Twilio";
    }
}

[código completo incluindo importações no GitHub]

Agora você pode inicializar o aplicativo, executando o main método RespondToSmsWithTwilioAndJavaApplication no IDE ou ./mvnw spring-boot:run em uma janela de terminal na raiz do projeto.

Depois de executar, teste-o usando o comando abaixo.

curl -XPOST http://localhost:8080

Deverá aparecer a mensagem "Olá da Twilio" como resposta.

Como retornar TwiML via HTTP

Até agora fizemos um bom trabalho. Em seguida, precisamos retornar o TwiML para que a Twilio possa entender a resposta.

É possível escrever TwiML manualmente, porém é mais fácil de fazer usando a biblioteca auxiliar Twilio Java. Adicione o código abaixo da seção <dependencies> de pom.xml na raiz do seu projeto.

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

[este código no GitHub]

Recomendamos sempre o uso da versão mais recente da biblioteca auxiliar da Twilio. No momento da redação, a versão atual é a 8.8.0. Você sempre pode verificar a versão mais recente em mvnreporistory.com.

Agora, faremos algumas alterações no código em SmsWebhookHandler. Altere a classe para obter esta definição:

@RestController
public class SmsWebhookHandler {

    private final Map<String, Integer> messageCounts = new ConcurrentHashMap<>();

    @PostMapping(value = "/", produces = "application/xml")
    @ResponseBody
    public String handleSmsWebhook(
        @RequestParam("From") String from,
        @RequestParam("Body") String body){

        int thisMessageCount = messageCounts.compute(from, (k,v) -> (v == null) ? 1 : v+1);

        String plural = (thisMessageCount > 1) ? "messages" : "message";
        String message = String.format(
            "☎️ Hello from Twilio. You've sent %d %s, and this one said '%s'",
            thisMessageCount, plural, body);

        return new MessagingResponse.Builder()
            .message(new Message.Builder(message).build())
            .build().toXml();
    }
}

[código completo incluindo importações no GitHub]

Algumas coisas estão acontecendo aqui, então passaremos por elas:

Linha 4: cria um novo mapa de string a integer para contar quantas mensagens tivemos de cada número de telefone exclusivo. Como a Spring criará apenas uma instância dessa classe, o Mapa será compartilhado entre todas as chamadas.
Linha 6: observe que o endpoint agora tem um tipo de conteúdo de application/xml.
Linhas 9 a 10: podemos extrair dados da solicitação de entrada usando @RequestParam. Aqui estou usando apenas o número From e a mensagem Body, mas há muito mais itens que você poderia acessar.
Linha 12: atualize o mapa messageCounts para considerar essa nova mensagem.
Linhas 14 a 17: crie a String a ser usada como resposta da mensagem.
Linhas 19 a 21: finalmente, crie a resposta TwiML e a retorne como uma string XML.

Para testar o código, execute o projeto como antes. Em seguida, quando estiver em execução, rode o comando abaixo.

curl http://localhost:8080/ -F From=+1234567890 -F Body=Hello

Você deverá receber a seguinte resposta:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Message>☎️ Hello from Twilio. You've sent 1 message, and this one said 'Hello'</Message>
</Response>

(observe que adicionei quebras de linha a esta saída)

Como configurar um número de telefone da Twilio

A última parte do quebra-cabeça é como configurar a Twilio para usar este app quando uma mensagem aparecer. Como eu disse na introdução, você precisa configurar seu número de telefone com um URL para o aplicativo. Como você está executando o aplicativo localmente, só terá um URL localhost, que a Twilio não poderá acessar. Há várias opções para hospedagem pública com Java, mas uma ferramenta que eu gosto de usar para desenvolvimento é ngrok, que poderá criar URLs públicos que encaminham para seus localhost apps da Web.

Depois que você tiver instalado ngrok e reiniciado seu app usando seu IDE ou o comando acima, o seguinte comando criará um URL público para seu servidor local:

ngrok http 8080

Assim que o túnel estiver conectado, o ngrok exibirá um URL com um subdomínio aleatório que agora aponta para seu aplicativo. Ele deve ser parecido com o https://RANDOM_STRING.ngrok.io. Abra seu console da Twilio para seus números recebidos e escolha o número que deseja usar para este app ou compre um novo. Edite o número e adicione seu URL ngrok como o webhook para quando uma mensagem entrar (deixando o método como POST).

Se você tiver o CLI da Twilio instalado, poderá fazer isso na linha de comando usando o comando abaixo.

twilio phone-numbers:update PHONE_NUMBER --sms-url http://localhost:3000/messages

O CLI detectará que esta é um URL do localhost e definirá o ngrok para você.

Envie um texto para o seu número algumas vezes e veja as respostas aparecerem.

Captura de tela do app SMS no meu telefone. Enviei 2 mensagens e tive 2 respostas que ecoam o que enviei e são numeradas.

🎉🎉🎉 Bom trabalho 🎉🎉🎉

Para finalizar

Você aprendeu a responder ao SMS usando Twilio e Java e pode aprender a iniciar o SMS de saída. Além disso, viu que pode personalizar respostas com base em quem está enviando mensagens e o que eles dizem. Agora sua imaginação é o limite. Você poderá criar um recomendador de livros (para uma livraria), um sistema de saúde para a comunidade, um chatbot ou que tal algo novo?

Este artigo foi traduzido do original "Receiving and Responding to SMS with Java and Twilio". 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.