Receber e responder mensagens SMS e MMS no ESP8266 com C++ e ngrok

Hoje, usaremos o Programmable SMS da Twilio para responder mensagens recebidas diretamente de um aplicativo C++ ou superior sendo executado em um ESP8266. Quando um SMS ou MMS for enviado para seu número da Twilio, usaremos o ngrok para rotear uma conexão segura da Twilio para uma rota em seu ESP8266. Em seguida, aplicaremos alguma lógica na solicitação da Twilio, possivelmente piscaremos alguns LEDs e enviaremos uma resposta usando a linguagem de marcação da Twilio, o TwiML.

Parece difícil? Nem um pouco! Em pouco tempo, você vai ficar viciado nos nossos webhooks.

A Twilio pode enviar ao seu aplicativo da Web uma solicitação HTTP quando certos eventos ocorrem, como uma mensagem de texto recebida para um dos números de telefone da Twilio. Essas solicitações são chamadas de webhooks ou retornos de chamada de status. Para mais informações, consulte o nosso guia Introdução aos webhooks da Twilio. Encontre outras páginas do webhook, como um guia de segurança e perguntas frequentes na seção Webhooks dos documentos.

O que é um Webhook?

Os webhooks são retornos de chamada HTTP definidos pelo usuário. Geralmente, eles são acionados por algum evento, como receber uma mensagem SMS ou uma chamada telefônica. Quando esse evento ocorre, a Twilio faz uma solicitação HTTP (geralmente uma POST ou GET) para o URL configurado para o webhook.

Para lidar com um webhook, você só precisa criar um pequeno aplicativo da Web que possa aceitar as solicitações HTTP. Quase todas as linguagens de programação da parte do servidor oferecem alguma estrutura para você fazer isso. As linguagens incluem ASP.NET MVC para C#, Servlets e Spark para Java, Express para Node.js, Django e Flask para Python, e Rails e Sinatra para Ruby. O PHP tem sua própria estrutura de app Web integrada, embora frameworks como Laravel, Symfony e Yii também sejam populares.

Seja qual for a estrutura e o idioma que você escolher, os webhooks funcionam da mesma forma para cada aplicativo da Twilio. Eles fazem uma solicitação HTTP para um URI que você fornece à Twilio. Seu aplicativo executa qualquer lógica que você ache necessária: leitura/gravação de um banco de dados, integra‐se a outra API ou executa algum cálculo. Em seguida, responde à Twilio com uma resposta TwiML com as instruções que você deseja que a Twilio execute.

O que é TwiML?

TwiML é a Twilio Markup Language, basicamente um documento XML com tags especiais definidas pela Twilio para ajudar você a criar seus aplicativos de SMS e voz. É mais fácil mostrar o TwiML do que explicá‐lo. Aqui está um TwiML que você pode usar para responder a uma chamada telefônica recebida:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Thanks for calling!</Say>
</Response>

E aqui está um TwiML que você pode usar para responder a uma mensagem SMS recebida:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>We got your message, thank you!</Message>
</Response>

Cada documento TwiML tem um elemento raiz <Response> e esse elemento pode conter um ou mais verbos. Verbos são ações que você deseja que a Twilio execute, como <Say> uma saudação para um autor de chamada ou enviar um <Message> SMS em resposta a uma mensagem recebida. Para obter uma referência completa sobre tudo o que você pode fazer com o TwiML, consulte nossa Referência de API do TwiML.

Pré‐requisitos para receber e responder mensagens SMS no ESP8266

Há vários pré‐requisitos que você precisará ter em mente para seguir este guia corretamente. No coração (ou talvez o cérebro) está o Espressif ESP8266, encontrado em módulos tão baratos que chegam a US$ 2,00. Com suporte para TLS 1.2, ele é uma das partes mais econômicas que podem usar as APIs da Twilio com segurança.

No mínimo, para integrar os webhooks da Twilio, você precisará de um ESP8266, um método de programá‐lo e uma maneira de roteá‐lo com segurança para o ESP. Para seguir este artigo em particular, você também precisará garantir que possa programar seu ESP8266 a partir do Arduino IDE.

Seleção da placa ESP8266

Se você ainda não selecionou uma placa de desenvolvimento, sugerimos verificar a tested board list (lista de placas testadas) do Arduino no repositório GitHub ESP8266. Eles não cobrem todas as variações do ESP8266 ou PCBs próprios, mas escolher uma variante testada é a maneira mais rápida de começar. As variantes de ESP-8266 12-E, such as this one (como esta), funcionam bem.

Quando criei isso, usei uma Sparkfun Thing e uma Basic FTDI breakout da Sparkfun para a programação. A Thing sobrecarrega o pino DTR e não funcionará durante a programação e conectado ao monitor serial. Para a maioria das placas, você não precisa tocar nos seriais #define no código.

Mas, se fizer isso, você pode desativar ou ativar o serial do software alterando o #define USE_SOFTWARE_SERIAL no Twilio_ESP8266_Example.ino.

Arduino IDE

O núcleo ESP8266 para Arduino oferece convenientemente a Xtensa gcc toolchain (cadeia de ferramentas Xtensa gcc), as bibliotecas Arduino são muito úteis e uma forma fácil de começar a programar a ESP8266.

Embora esteja além do escopo do guia, informe‐nos sobre qualquer sucesso obtido ao receber e responder mensagens SMS e MMS no ESP8266 usando outras cadeias de ferramentas. Adoraríamos conhecer sua metodologia!

Geração do TwiML manualmente no ESP8266

Nas nossas bibliotecas auxiliares da Twilio, incluímos código para ajudar na formulação do TwiML correto. Infelizmente, com uma parte que suporta 16 megabytes maximum flash memory (no máximo 16 megabytes de memória flash) com RAM medida em quilobytes, precisamos gerar nosso próprio TwiML do zero.

Mas não se preocupe, a linguagem de marcação da Twilio é muito simples e avançada.

Para este aplicativo de exemplo, um caminho responderá os SMSs e MMSs recebidos com uma mensagem genérica e predefinida. Em outro, demonstramos uma autenticação muito simples (não segura) em relação a um número mestre, permitindo que esse número ligue e desligue o LED onboard em muitas placas de desenvolvimento ESP8266.

Neste código:

Recebemos uma mensagem de texto de entrada e preparamos imediatamente uma resposta começando com <?xml version=\"1.0\" encoding=\"UTF-8\"?>.
Em seguida, decidimos se uma mensagem é de um número "autorizado", que definimos como correspondendo à nossa variável master_number.
Se estivermos autorizados e recebermos um corpo contendo apenas “0” ou “1”, desligamos ou ligamos o LED integrado e usamos as tags <Response> e <Message>. (Observe que algumas placas possuem um LED baixo ativo e terão lógica invertida; deixaremos para você alternar as mensagens!)

Um SMS de entrada autorizado com “?” como o corpo responderá com as instruções e o status atual do LED, novamente nas tags <Response> e <Message>. Solicitações não autorizadas com qualquer um desses três comandos serão avisadas.

Por fim, respondemos com application/xml como o MIME type (tipo MIME) e um código de status 200.

Loading Code Sample...

Example JSON response

Gerando o TwiML manualmente no ESP8266.

Sending and Receiving Messages on the ESP8266

Gerando o TwiML manualmente no ESP8266.

Configuração de uma rota no ESP8266

Na verdade, a configuração de uma rota no servidor da web ESP8266 é muito simples com a biblioteca ESP8266WebServer. No mínimo, você precisará instanciar um objeto ESP8266WebServer, configurar uma única rota e função para lidar com solicitações e iniciar a escuta do servidor. A Twilio espera o TwiML como resposta; então, assim que a rota funcionar corretamente, você desejará retornar o TwiML para orientar a Twilio sobre como responder à mensagem recebida.

No nosso código, esta linha:

twilio_server.on("/message", handle_message);

configura uma rota em /message, e handle_message é um indicador de função para uma função void (nossa implementação está no repositório do Github). Quando uma solicitação é feita para /message, essa função é chamada e o ESP8266 passa pela lógica previamente discutida para escolher uma resposta (e possivelmente piscar o LED!).

Todo o encanamento para fazer esse trabalho é destacado neste exemplo de código.

Loading Code Sample...

Example JSON response

Instanciando um ESP8266WebServer na porta 8000, configurando uma rota com uma função de retorno de chamada, iniciando o servidor ESP8266 e lidando com conexões de entrada.

Configuração de uma rota no ESP8266 para um webhook da Twilio

Instanciando um ESP8266WebServer na porta 8000, configurando uma rota com uma função de retorno de chamada, iniciando o servidor ESP8266 e lidando com conexões de entrada.

Configuração do URL do seu webhook

Se tudo correu bem, agora você tem um servidor da Web rodando no ESP8266 em uma rede amigável! Se você chegou até aqui, o restante do seu encanamento será fora do ESP8266.

Primeiro, no entanto, você vai precisar encontrar o servidor da web. Utilize o que for mais fácil para encontrar o endereço IP do ESP8266 em sua rede local. Se você estiver conectado ao serial na placa, isso pode ser tão fácil quanto procurar o endereço IP atribuído em uma mensagem semelhante a esta execução bem‐sucedida:

.....
Connected to WiFi, IP address:
192.168.1.155
Connecting to host api.twilio.com
Certificate fingerprints match.

Embora seu ESP8266 quase certamente não seja encontrado em 192.168.1.155, quando você encontrar o IP, poderá testá‐lo visitando‐o (em um navegador) em:

<YOUR ESP8266'S IP ADDRESS>:8000/message

e verificando se você obtém uma resposta xml.

Se funcionar, você está pronto para compartilhá‐lo com o mundo e informar à Twilio onde encontrar seu ESP. Mas, primeiro, precisamos encontrar uma maneira de expô‐lo.

Uso do ngrok para expor o ESP8266

Uma forma simples de testar nosso novo servidor ESP8266 é com o ngrok. O ngrok facilita muito o encapsulamento de solicitações seguras para sua rede local, garantindo que a criptografia não seja quebrada até que esteja dentro da sua rede interna (esperamos) mais controlável.

Em uma máquina que possa ver o ESP8266 e tenha o ngrok instalado, basta executar o seguinte comando no terminal de sua escolha (substituindo 192.168.1.155 pelo endereço IP do seu ESP8266):

ngrok http 192.168.1.155:8000

... e isso é realmente tudo que você precisa. Você deve ver o ngrok assumir seu terminal com um bom resumo:

Using ngrok to Route Requests to an Espressif ESP8266

Configuração de um webhook de mensagens com a Twilio

Agora que nosso ESP8266 está exposto ao mundo com o ngrok, há apenas mais um passo antes de podermos enviar uma mensagem de texto para nosso pedaço de silício de US$ 2,00 para diversão e lucro.

Faça login no console da Twilio e navegue até um número (de preferência, o número definido na variável from_number) que você gostaria de conectar à sua placa.

Role para baixo e você verá uma seção para configurar URLs de webhook para mensagens. Basta colar no URL seguro do ngrok seguido por /message e já está pronto:

Depois disso, você estará nadando de braçadas com a Twilio. Tente enviar mensagens de texto “0”, “1”, “?” e o que mais você desejar do master_number e de outros números e veja o que acontece. Isso é tudo de que você precisa para conectar seu dispositivo ESP8266 com a Twilio!

URL do webhook de backup

Você notará que há um campo opcional “Primary Handler Fails” (Falhas do manipulador primário). Em seu aplicativo final, você provavelmente desejará adicionar um endpoint secundário para a Twilio recorrer se o ESP8266 estiver inacessível, para que você possa lidar com a lógica para quando ele voltar a ficar online.

Basta adicionar um URL a esse campo e a Twilio fará failover automaticamente em um código de erro ou se o webhook primário não responder em 15 segundos. Consulte nosso Availability and Reliability guide (guia de Disponibilidade e confiabilidade) para obter mais detalhes sobre o URL de fallback.

Proteja seus webhooks

A Twilio é compatível com HTTP básico e Autenticação Digest. A autenticação permite proteger com senha seus URLs TwiML no servidor da Web para que somente você e a Twilio possam acessá‐los.

Saiba mais sobre a autenticação HTTP here (aqui).

Responder com mídia (mensagem MMS)

Enviar um MMS é tão simples quanto adicionar uma nova tag ao TwiML com uma tag <Media>. Você pode incluir até 10 individual media tags (10 tags de mídia individuais) em uma resposta.

Embora esteja além do escopo desta parte, isso significa que você pode enviar de volta imagens hospedadas (ou geradas dinamicamente) no ESP8266 em resposta às mensagens recebidas. Bacana!

Aprimorar mensagens com Add-ons

Precisa de mais informações sobre o número de telefone que enviou a mensagem? Precisa analisar a própria mensagem quanto ao sentimento ou outros dados? Os Add-ons estão disponíveis no Add-ons Marketplace (Marketplace de Add-ons) para realizar essas tarefas e muito mais.

Para saber como habilitar Add-ons for your incoming SMS messages (Add-ons para suas mensagens SMS recebidas), consulte nosso Add-ons quickstart (Início rápido de Add-ons).

Quem precisa de mais de 64 kB de RAM, imagina então 640 kB?

Entre este artigo e nosso artigo sobre how to send SMS and MMS messages from an ESP8266 (como enviar mensagens SMS e MMS de um ESP8266), abordamos como lidar com mensagens recebidas e enviadas com o Espressif ESP8266 e a API da Twilio. Agora, você pode implantar seus aplicativos da web em ambientes que os servidores não conseguiam anteriormente.

O próximo passo é com você. Use a Twilio e sua imaginação para configurar um app de segurança, automação doméstica ou monitoramento remoto. Adoraríamos saber o que você criou! Entre em contato conosco no Twitter com um link para sua próxima grande novidade.

Contribuidores:

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.

Sending and Receiving Messages on the ESP8266

Configuração de uma rota no ESP8266 para um webhook da Twilio

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!