You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

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

A Twilio está lançando um novo Console. Algumas capturas de tela nesta página podem mostrar o Console legado e, portanto, podem não ser mais precisas. Estamos trabalhando para atualizar todas as capturas de tela para refletir a nova experiência do Console. Saiba mais sobre o novo Console.

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

Antes de enviar uma mensagem pelo WhatsApp, você precisará cadastrar uma conta da Twilio ou fazer login em sua conta já existente e ativar o Twilio Sandbox para WhatsApp. O Sandbox permite criar protótipos com o WhatsApp imediatamente por meio de um número de telefone compartilhado, sem ter que esperar que um número da Twilio seja aprovado pelo WhatsApp.

Para começar, selecione um número entre os disponíveis no Sandbox para ativá‐lo.

WA_Sandbox.png

Anote o número de telefone escolhido no Sandbox. Você precisará disso mais tarde quando for o momento de enviar algumas mensagens.

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

Account Credentials

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).

Este tutorial usa credenciais codificadas na parte superior do código; você deve seguir as melhores práticas relacionadas à proteção de credenciais na produçã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.)

Se você entrou no seu Sandbox > há 24 horas, será necessário enviar uma nova mensagem de entrada para seu número do WhatsApp para enviar uma mensagem de mídia. No momento, o WhatsApp não é compatível com mídia em mensagens "modelo" que ocorrem fora de uma "sessão" de 24 horas.

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:

Loading Code Sample...
        
        

        Envie uma mensagem com o WhatsApp

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

        Observação: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de implantar na produção. Veja como manter suas credenciais da Twilio seguras.

        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 conteúdo de mídia do WhatsApp atualmente só é compatível com mensagens da sessão. Se a sessão do WhatsApp com um usuário expirar, você deverá aguardar uma mensagem de entrada para criar uma nova sessão antes de enviar uma mensagem de mídia a ele.

        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.

        Loading Code Sample...
              
              

              Responda a mensagens recebidas do WhatsApp com mídia

              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.

              Proteja seus webhooks

              A Twilio é compatível com HTTP básico e Autenticação Digest. A autenticação permite proteger com senha seus URLs TwiML no servidor da Web para que somente você e a Twilio possam acessá‐los.

              Saiba mais aqui e confira nosso guia para proteger seu aplicativo Sinatra validando as solicitações recebidas da Twilio.

              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!

              Maylon Pedroso Alberto Mucarsel Daniel Erazo Cristhian Motoche
              Classifique esta página:

              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.

              Loading Code Sample...
                    
                    
                    

                    Obrigado pelo seu feedback!

                    Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

                    Enviando seu feedback...
                    🎉 Obrigado pelo seu feedback!
                    Algo deu errado. Tente novamente.

                    Obrigado pelo seu feedback!

                    thanks-feedback-gif