Receber e responder mensagens SMS e MMS em Python com o Amazon Lambda

Hoje vamos chegar a "Hello, World!" em um aplicativo da Twilio sem servidor usando o Amazon API Gateway, Amazon Lambda e Python. Ao final deste guia, você terá as raízes do seu próximo aplicativo da Twilio que mudará o mundo. Ao final deste parágrafo, você terá uma promessa: não precisará ativar um único VPS.

Parece emocionante? Sem dúvida. Vamos começar!

Ah, e se você ainda não fez isso, faça login ou crie uma AWS Account (Conta da AWS) e faça login ou crie uma Twilio Account (conta da Twilio). Não se preocupe, estaremos aqui quando estiver pronto.

Requisitos do tutorial

Uma conta da AWS. Se você ainda não tiver uma conta da AWS, sign up for an account (inscreva‐se em uma conta) gratuitamente e desfrute de um generoso subsídio durante o primeiro ano.
Uma conta da Twilio. Se você for novo na Twilio, poderá create a trial account (criar uma conta de avaliação) e começar a desenvolver gratuitamente. (Confira os features and limitations of a free Twilio account (recursos e limitações de uma conta gratuita da Twilio)).

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.

Uso do Amazon Lambda com a Twilio e com o Amazon API Gateway

Embora a peça que será exposta ao mundo venha a pertencer ao API Gateway, é conceitualmente mais fácil começar com o código no Lambda. Como isso pode parecer retrógrado para você, prepare-se para algumas referências avançadas nesta seção. Tudo isso ficará claro quando expusermos tudo ao mundo a partir do API Gateway.

Criar uma função do Amazon Lambda

A partir da sua escolha de região da Amazon, crie uma nova função do Lambda em seu Console do Lambda usando o blueprint "microservice-http-endpoint-python".

Certifique‐se de que o console esteja definido para sua região preferida. Isso é importante porque as funções do Lambda estão disponíveis apenas no contexto da região selecionada. A maioria das pessoas escolhe uma região geograficamente próxima de onde vivem.

Este blueprint "microservice-http-endpoint-python" nos leva a começar a posicionar nossa configuração lambda_function com a assinatura de função adequada para receber informações da API Gateway (eventualmente).

Nomeie sua função como replyMessages
Selecione a função de execução de permissões básicas do Lambda (ou use uma função existente que você já configurou no AWS IAM console (console do AWS IAM))
Remova o acionador “API Gateway” pressionando o botão Remove (Remover). Vamos adicionar nosso próprio acionador quando terminarmos o código.
Clique no botão Create funcion (Criar função) para criar sua função. Vamos editar o código na próxima etapa.

No editor de código, substitua o código do modelo pelas seguintes linhas de código.

Insira este código em sua totalidade no editor embutido:

Loading Code Sample...

Example JSON response

Responding with "Hello, World!" on Amazon Lambda with Python 2.7 in 6 lines of code.

Responding to SMS or MMS Messages in Lambda

Responding with "Hello, World!" on Amazon Lambda with Python 2.7 in 6 lines of code.

Todo o nosso "Hello, World!" ("Olá, mundo!") O aplicativo se encaixa em 6 linhas de código. Simplesmente: vamos importar a impressão do Python 3, imprimir todos os cabeçalhos e parâmetros HTTP que recebemos e retornar o TwiML.

Acessar cabeçalhos de solicitação e parâmetros do corpo

Todos os parâmetros HTTP publicados e qualquer cabeçalho que optemos por incluir estarão dentro do dicionário event.

Embora pareça mágica neste ponto, há um processo de duas etapas no API Gateway para se preparar o event para nosso consumo. O API Gateway espera a entrada JSON, então usaremos um Mapeamento de corpo e divisão em caracteres de "e comercial" para preparar o dicionário para Python. (Isso virá na próxima seção.)

print("Received event: " + str(event))

Há mais mágica nesta linha: a impressão é redirecionada automaticamente para o Amazon Cloudwatch. Quando nossa função e nossas políticas são configuradas corretamente, as chamadas dessa função e qualquer saída serão encontradas no CloudWatch.

Gerar TwiML manualmente com Lambda e Python

O TwiML, a linguagem de marcação XML da Twilio, é incrivelmente avançada e permite que você instrua facilmente o Twilio sobre como lidar com ações recebidas. Estamos usando apenas um pequeno subconjunto do TwiML hoje para responder uma mensagem com uma mensagem nossa.

return '<?xml version=\"1.0\" encoding=\"UTF-8\"?>'\
       '<Response><Message><Body>Hello world! -Lambda</Body></Message></Response>'

Com essa string, primeiro informaremos à Twilio que estamos respondendo com XML codificado em UTF-8. Em seguida, configuramos uma tag Message aninhada dentro de uma tag Response; a tag Message informa à Twilio que gostaríamos de responder com o conteúdo da tag <Body> (nesse caso, por SMS).

Responder com mídia (mensagens MMS)

O TwiML tem a flexibilidade de retornar mídia em suas respostas às mensagens recebidas. Adicione um substantivo <Media> dentro da <Message> e você estará apimentando sua mensagem com pngs em pouco tempo (sim, outros formatos de imagem também funcionam).

Sua imagem vale 1.000 palavras, mas você precisa de 5.000? Sem problema, a Twilio permite up to 10 media items (até 10 itens de mídia) por resposta.

Configurações básicas do Lambda

Em Basic settings (Configurações básicas), sinta‐se à vontade para definir a memória (MB) para o mínimo de 128 MB. Usamos pessoalmente um tempo limite de 10 segundos sem problemas.

Na produção, você desejará rever esses limites; observe como os preços do Lambda mudam based upon your selections (com base em suas seleções).

Pressione o botão Save (Salvar) para salvar as alterações feitas.

Teste nossa função do Lambda

Nesse ponto, sinta‐se à vontade para "testar" a função usando o botão azul na parte superior; independentemente da entrada, você verá este resultado (incluindo aspas duplas):

"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><Message>Hello world! -Lambda</Message></Response>"

Configuração do Amazon API Gateway

Agora, a sua função do Lambda tem recursos alocados, políticas e funções definidas e responde com perfeição. Nosso próximo passo é encontrar uma forma de deixar o mundo falar com ele. É aí que o Amazon API Gateway entra em ação. Vamos usar a integração Lambda/API Gateway para configurar um caminho da Twilio para a função do Lambda que acabamos de definir.

No console do AWS API Gateway e na sua escolha de região (não é necessário corresponder à região da função Lambda), selecione o botão Create API (Criar API).
Selecione a opção API REST

(Se você não tiver APIs na região atual, clique no botão Build (Construir) na opção API REST.)

Preencha o nome e a descrição de uma API. Estamos nomeando nossa API “twilio_simple_responses” com uma Descrição de "Responder a mensagens recebidas da Twilio" e o tipo de endpoint "Regional".
Pressione o botão Create API (Criar API).

Criar e configurar seus recursos

Agora que criamos nossa nova API REST twilio_simple_responses, podemos criá‐la e configurá‐la para funcionar bem com a função do Lambda replyMessages que criamos na seção anterior.

No menu suspenso “Actions” (Ações), você poderá selecionar Create Resource (Criar recurso) no menu suspenso:

Nomeie seu recurso como “Message Responder” e use um Caminho de recurso do /message. Em seguida, pressione o botão Create Resoure (Criar recurso).

Na lista suspensa, selecione Create Method (Criar método), selecione POST e pressione a check mark (marca de seleção) (✓) para salvar.
Na tela de configuração, selecione a integração “Lambda Function” (Função do Lambda) sem a integração de Proxy e selecione a região e o nome da função do Lambda (usamos replyMessages.).Observe que o campo “Lambda Function” (Função do Lambda) pesquisará automaticamente à medida que você digitar. É provável que você só precise inserir os primeiros caracteres para encontrar sua função:

Depois de salvar, clique em “Okay” no pop-up concedendo permissões e você estará pronto para integrar o Lambda!

Vamos dar um passo de cada vez na configuração para integrar adequadamente nossa função ao API Gateway. Observe que precisamos fazer várias alterações de configuração no console do API Gateway, pois ele foi projetado para entrada e saída JSON. Precisamos contornar isso para que a Twilio, que publica um formulário e espera o XML, entenda nossa resposta.

Integração da nossa solicitação com nossa função do Lambda

Embora nossa função seja simples agora, a maioria dos aplicativos eventualmente precisará de alguma lógica com base nas mensagens recebidas. Precisamos mapear um tipo de conteúdo deapplication/x-www-form-urlencoded em JSON para funcionar corretamente com o API Gateway e com o Lambda.

Clique em Integration Request (Solicitação de integração) e expanda as Body Mapping Techniques (Técnicas de mapeamento de corpo).
Clique em Add mapping template (Adicionar modelo de mapeamento) e insira application/x-www-form-urlencoded (sem aspas)
Certifique‐se de que a marca de seleção (✓) foi selecionada para salvar! Haverá uma janela pop-up solicitando que você proteja esse mapeamento; confirme se deseja protegê‐lo.

O API Gateway alterará seu "Request Body Passthrough" (Passagem de corpo da solicitação) para "When there are no templates defined (recommended)" (Quando não houver modelos definidos (recomendado)) (se não houver ou você cancelar a solicitação, mova-o agora)

Insira este código no editor que aparece na caixa Content-Type (Tipo de conteúdo):

#set($httpPost = $input.path('$').split("&"))
{
#foreach( $kvPair in $httpPost )
 #set($kvTokenised = $kvPair.split("="))
 #if( $kvTokenised.size() > 1 )
   "$kvTokenised[0]" : "$kvTokenised[1]"#if( $foreach.hasNext ),#end
 #else
   "$kvTokenised[0]" : ""#if( $foreach.hasNext ),#end
 #end
#end
}

Esse código, que foi sugerido pela primeira vez por avilewin in the AWS Developer Forums (avilewin nos Fóruns de desenvolvedores da AWS), divide nossos parâmetros HTTP em pares de chave/valor JSON.

Por fim, volte para “Method Execution” (Execução de método) seguindo o link na parte superior do quadro. (Talvez seja necessário rolar para cima.)

Integração da nossa resposta do Lambda ao API Gateway

Precisamos fazer algum encanamento a partir da saída da nossa função do Lambda. Em uma API tradicional, você gostaria de usar corretamente os HTTP status codes (códigos de status HTTP), em geral, você só vai querer responder com um 200 e, às vezes, um 401 para a solicitação da Twilio. Além disso, o API Gateway é configurado para responder com um “Content-Type” (Tipo de conteúdo) de application/json, enquanto a Twilio espera application/xml. Vamos corrigir isso agora para o caso de 200.

Clique no link Integration Response (Resposta de integração).
Expanda a resposta 200 e, em seguida, expanda os Body Mapping Templates (Modelos de mapeamento de corpo).
Se houver uma entrada “application/json”, remova‐a agora.
Selecione Add mapping template (Adicionar modelo de mapeamento) e adicione application/xml.
Na caixa de texto, insira este mapeamento:

$input.path('$')

Essencialmente, estamos apenas ecoando o valor de retorno da função do Lambda. Isso também cuidará das aspas duplas ao redor (") da string de retorno.

Salve o mapeamento e retorne à página execução de método com o link na parte superior da tela.

Configuração da nossa resposta do API Gateway

Em seguida, atualizaremos a resposta que nossa API twilio_simple_responses envia de volta para a Twilio. Em vez de JSON (o padrão), queremos enviar de volta o XML.

Clique no link Method Response (Resposta ao método).
Em Response Body for 200 (Corpo de resposta para 200), se application/json estiver definido, remova‐o agora.
Em seguida, adicione application/xml com um modelo “Empty” (Vazio).
Não se esqueça de clicar na marca de seleção (✓) para salvar suas alterações.

Retorne à página execução de método com o link na parte superior da tela.

Implantação da nossa API e escolha de um estágio

Estamos quase terminando. A última coisa que queremos fazer com nossa API Gateway é implementá‐la.

No menu Actions (Ações), selecione Deploy API (Implantar API):

Em seguida, será solicitado em qual estágio você deseja implantar. Se nenhum ainda tiver sido criado, você poderá criar um novo estágio no menu.

Nomeie seu estágio como “prod”:

Expanda o estágio “prod” que aparece (ou navegue até Stages (Estágios) na barra lateral) e clique em “POST” em “/” e “/message”.
Na parte superior, você verá um Invoke URL (URL de invocação).
Copie esse URL.

Com uma área de transferência completa, estamos em 2/3 do caminho para um aplicativo da Twilio sem servidor! Vamos continuar.

Configurar o webhook do URL

No lado da Twilio, precisamos dizer à Twilio onde fazer uma solicitação quando ela receber um SMS em seu número de telefone da Twilio.

No Twilio Console (Console da Twilio), navegue até a seção Numbers (Números) na barra lateral (#).
Selecione o número que deseja encaminhar para nossa nova função do Lambda.
Em Messaging (Mensagens) e em A Message Comes In (Uma mensagem chega), selecione a opção Webhook e cole o URL do API Gateway na caixa de texto (destacada abaixo). Verifique se HTTP POST está selecionado.

URL do webhook de backup

Você também notará a caixa “Primary Handler Fails” (Falhas do manipulador primário). Na produção, você pode querer ter um manipulador secundário para mensagens de entrada. A Twilio fará failover automaticamente para o manipulador secundário se ele não conseguir alcançar o manipulador primário em 15 segundos ou se houver outro problema. Consulte nosso Availability and Reliability guide (guia de Disponibilidade e confiabilidade) para obter mais detalhes.

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 e a validação de pedidos recebidos here (aqui). Você também pode conferir nosso guide on securing your Python Amazon Lambda app (guia completo sobre como proteger seu app do Python Amazon Lambda).

Enviar uma mensagem de texto para seu número da Twilio

E, com isso, todo o encanamento está completo! Agora você tem a Twilio observando as mensagens recebidas, o API Gateway escutando as solicitações da Twilio e a lógica Python no Lambda escutando o API Gateway. Tente enviar uma mensagem de texto para seu número Twilio para verificar se o mundo ainda quer dizer olá para você.

O que vem a seguir? Fazer um grande Delta com a Twilio e Lambda

Sugerimos que você visite nosso guia sobre validating incoming Twilio requests with Python on Lambda (validação de solicitações da Twilio recebidas com Python em Lambda). Nesse artigo, vamos explorar alguns recursos mais avançados do Lambda, como carregar nossa Python Helper library (Biblioteca auxiliar Python) e definir variáveis ambientais, além de demonstrar algumas verificações simples de números de telefone e validar solicitações da Twilio.

Se você estiver pronto para continuar, os Add-ons muitas vezes simplificam suas próximas etapas. Os Add-ons tornam a plataforma Twilio ainda mais poderosa, permitindo que você integre algumas ferramentas e serviços incríveis dos nossos parceiros em seu aplicativo.

Seja qual for sua construção, estamos aqui para ajudar e para comemorar quando você implantar. Informe‐nos quando você pressionar o botão implantar messaging us on Twitter (nos enviando mensagens no Twitter)!

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.

Responding to SMS or MMS Messages in Lambda

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!