Envie e receba mensagens de mídia com o WhatsApp no Ruby

Neste tutorial, vamos configurar um aplicativo Ruby que usa o Canal do WhatsApp para:

• Enviar mensagens de mídia
• Responder mensagens recebidas com mídia

Os exemplos de código neste tutorial usam a biblioteca auxiliar Ruby da Twilio e o Sinatra.

Envie mensagens de saída de mídia pelo WhatsApp

Assim como ao enviar um MMS, o envio de uma mensagem pelo WhatsApp usa o recurso de mensagem da Twilio. Esta seção orienta você na configuração e no envio de mídia em uma mensagem do WhatsApp. A mídia pode consistir de imagens, arquivos de áudio e PDFs.

Inscreva‐se (ou faça login) em sua conta da Twilio e ative o Sandbox

Reúna as informações da sua conta da Twilio

Antes de enviar qualquer mensagem, você precisará reunir as credenciais da sua conta da Twilio. Você pode encontrá‐las no Twilio Console.

• Account SID (SID da conta) – Usado para você se identificar em solicitações de API
• Auth Token (Token de autenticação) – Usado para autenticar solicitações da API REST

Para todos os nossos trechos de código e exemplos de Ruby, você precisará autenticar com o Account SID (SID da conta) e o Auth Token (Token de autenticação).

Envie uma mensagem de mídia pelo WhatsApp no Ruby por meio da API REST

Para enviar uma mensagem de mídia por meio do WhatsApp a partir da sua conta da Twilio, você precisará fazer um HTTP POST para o recurso de mensagem da Twilio.

Enviar uma mensagem de mídia pelo WhatsApp é semelhante a enviar uma mensagem baseada em texto pelo WhatsApp com uma adição importante: o parâmetro media_url. O parâmetro media_url neste código informa à Twilio onde recuperar a mídia que queremos incluir na mensagem do WhatsApp. (Você pode impedir o acesso não autorizado à sua mídia ativando a autenticação básica HTTP para URLs de mídia no Console da Twilio.)

A biblioteca auxiliar Ruby da Twilio ajuda você a criar uma nova instância do recurso Mensagem. Ao fazer isso, você especificará os parâmetros to, from e media_url da sua mensagem.

Se você ainda não tiver a biblioteca auxiliar Ruby instalada, poderá instalá‐la usando o gem:

gem install twilio-ruby

Se desejar instalar a biblioteca auxiliar manualmente, encontre as instruções aqui.

Agora, crie um arquivo chamado send_whatsapp_media.rb e inclua o seguinte código:

Substitua os valores do espaço reservado account_sid e auth_tokenpor seus valores exclusivos. Você pode encontrá‐las no Console da Twilio.

O número para deve ser o número de telefone da conta do WhatsApp de destino no formato E.164. Se você estiver usando o WhatsApp Sandbox, só poderá enviar mensagens para números que ingressaram no Sandbox.

Você informará ao Twilio qual número de telefone usar para enviar essa mensagem substituindo o número from pelo identificador do canal do whatsapp: seguido pelo número do Sandbox no formato E.164 .

Salve o arquivo e execute-o a partir da linha de comando:

ruby enviar_mpidia_do_whatsapp.rb

Em alguns momentos, você deve receber uma mensagem do WhatsApp com uma imagem!

Observe que o WhatsApp não oferece suporte para a inclusão de um corpo de texto na mesma mensagem que um vídeo, arquivo de áudio, documento, contato (vCard) ou localização. Se você passar o parâmetro Body em uma mensagem com um desses tipos de mídia, o corpo será ignorado e não será entregue ao dispositivo.

Compreensão da resposta da Twilio

Quando você envia uma mensagem de saída de mídia do WhatsApp, a Twilio envia dados sobre a mensagem em resposta à sua solicitação. A resposta JSON contém o SID exclusivo e o URI para seu recurso de mídia:

"subrecurso_uris": {"mídia": "/2010-04 01/Contas/ACxxxxxxxx/Mensagens/SMxxxxxxxxxxxxx/Mídia.json"}

Quando a API REST da Twilio cria seu novo recurso Message, ela salva a imagem encontrada no media_url especificado como um recurso Media. Uma vez criado, você pode acessar esse recurso a qualquer momento por meio da API.

Responda com a mídia no WhatsApp

Para responder usando mídia para mensagens recebidas do WhatsApp, você precisará fornecer à Twilio um URL do webhook que aponta para um servidor que executa código para inspecionar e salvar os arquivos de mídia.

O que são webhooks?

Webhooks são retornos de chamada HTTP definidos pelo usuário. Geralmente, eles são acionados por algum evento, como receber uma mensagem SMS ou uma chamada telefônica. Quando esse evento ocorre, a Twilio faz uma solicitação HTTP (geralmente uma POST ou GET) para o URL configurado para o webhook.

Para lidar com um webhook, você só precisa criar um pequeno aplicativo da Web que possa aceitar as solicitações HTTP. Quase todas as linguagens de programação da parte do servidor oferecem alguma estrutura para você fazer isso. Ruby on Rails e Sinatra são duas estruturas de desenvolvimento Ruby populares da Web. Neste tutorial, iremos configurar nosso aplicativo da Web com o Sinatra.

A funcionalidade Webhook é a mesma para cada aplicativo Twilio. Primeiro, um webhook faz uma solicitação HTTP para um URI que você fornece à Twilio. Quando recebe essa solicitação, seu aplicativo executa uma lógica predefinida. Isso pode ser algo como leitura/gravação de banco de dados ou chamar outra API. Por fim, seu aplicativo envia uma resposta TwiML à Twilio, na qual especifica as instruções que devem ser seguidas pela Twilio.

O que é TwiML?

TwiML é a linguagem de markup da Twilio, basicamente um documento XML com tags especiais definidas pela Twilio para ajudar você a criar seus aplicativos de mensagens e voz.

É mais fácil mostrar o TwiML do que explicá-lo:

<?xml versão="1.0" codificação="UTF-8"?>
<Resposta>
   <Mensagem>Obrigado pela mensagem!</Mensagem>
</Resposta>

Cada documento TwiML tem o elemento<Resposta>, que pode conter um ou mais verbos. Verbos são ações que você deseja que a Twilio execute, como <Say (Dizer)> uma saudação para um autor de chamada ou enviar uma <Mensagem> SMS em resposta a uma mensagem recebida. Para obter uma referência completa sobre tudo o que você pode fazer com o TwiML, consulte nossa Referência de API do TwiML.

Para enviar de volta uma mídia em sua resposta do WhatsApp, você precisa incluir o elemento TwiML de mídia com o URL para o arquivo de mídia. Um anexo de mídia é suportado por mensagem, com um limite de tamanho de 5 MB.

Gere o TwiML em seu aplicativo

Para responder a uma mensagem recebida do WhatsApp, você pode escrever TwiML bruto ou usar uma biblioteca auxiliar. Ao usar a biblioteca auxiliar, você não precisa se preocupar em gerar o XML bruto por conta própria.

Você tem o código, agora precisa de um URL que possa fornecer à Twilio.

A Twilio só pode acessar servidores públicos na Internet. Isso significa que você precisa publicar seu aplicativo em um provedor de hospedagem na Web ou na nuvem (do qual há muitos), você pode hospedá‐lo em seu próprio servidor ou pode usar um serviço como o ngrok para expor sua máquina de desenvolvimento local à Internet. (Só recomendamos este último para fins de desenvolvimento e teste e não para implantações de produção.)

Para enviar mídia em resposta a uma mensagem recebida do WhatsApp, basta adicionar um URL de imagem. Se necessário, reinicie o servidor e envie uma mensagem para o número do WhatsApp novamente. Você deve receber uma mensagem do WhatsApp que inclua uma imagem. Consulte a Referência de API para obter mais detalhes.

Configure o URL do seu webhook

Agora que você tem um URL para a rotina de geração de respostas TwiML do seu aplicativo da Web, é possível configurar seu número de telefone da Twilio para chamar o URL do seu webhook sempre que uma nova mensagem do WhatsApp chegar para você.

Você pode definir o URL do webhook para mensagens recebidas no servidor no Sandbox.

Certifique‐se de escolher HTTP POST ou HTTP GET para corresponder ao que seu aplicativo da Web está esperando. Geralmente, o padrão POST funciona.

Examine a mídia nas mensagens recebidas do WhatsApp

Exibir, salvar ou manipular os arquivos de mídia em mensagens recebidas do WhatsApp também envolve a configuração de um URL do Webhook. O URL aponta para um servidor que gera instruções TwiML, incluindo a mídia que você deseja enviar.

Obtenha detalhes da mensagem recebida

Quando a Twilio chama seu webhook, ele envia vários parâmetros sobre a mensagem que você acabou de receber. A maioria deles, como o número de telefone To, o número de telefone From e o Body da mensagem estão disponíveis como propriedades do parâmetro de solicitação para nosso método de ação.

Obtenha URLs para a mídia

A Twilio envia variáveis de formulário chamadas MediaUrlX, em que X é um índice baseado em zero. As mensagens do WhatsApp conterão apenas um arquivo de mídia por mensagem recebida para que você possa acessar o arquivo em MediaUrl0 na solicitação recebida da Twilio para o URL do seu webhook.

Determine o tipo de conteúdo da mídia

Os anexos das mensagens do WhatsApp podem ser de vários tipos de arquivos diferentes, incluindo JPG, MP3 e PDF. (Veja mais sobre os tipos de arquivo compatíveis nas Perguntas frequentes.) A Twilio lida com a determinação do tipo de arquivo para você, que pode obter o tipo mime padrão do parâmetro MediaContentTypeX. Se você estiver esperando fotos e imagens, provavelmente verá muitos anexos com a imagem do tipo mime/jpeg.

E isso é tudo. Receber e responder é exatamente o mesmo que você faria em qualquer aplicativo de SMS com nossa API de mensagens. Legal, não é?

O que vem a seguir?

Todo o código, em um projeto de trabalho completo, está disponível no GitHub. Para se aprofundar, vá para a Referência da API de mensagens e saiba mais sobre a solicitação de webhook da Twilio e o recurso Media da API REST. Além disso, você deve estar ciente do preço de armazenamento de todos os arquivos de mídia que mantém nos servidores da Twilio.

Adoraríamos saber o que você cria com isso!