O que posso fazer com o MMS?

O que posso fazer com o MMS?

Recentemente, uma pergunta nesse sentido foi postada em um dos nossos canais internos do Slack.

Slack screenshot

O MMS, como canal de comunicação, é provavelmente mais conhecido pelo envio de imagens e, em seus primórdios, costumava ser chamado de “mensagens com imagens”. Nesta postagem do blog, veremos um exemplo de envio de um arquivo de imagem via MMS usando a Messages API do Vonage. Antes de entrarmos nesse assunto, porém, gostaria de fornecer um pouco mais de contexto sobre o MMS e algumas de suas outras funcionalidades.

Embora seja associado principalmente ao envio de imagens, a sigla MMS, na verdade, significa “Multi Media Service”. O MMS não se limita apenas ao envio de arquivos de imagem, mas permite enviar diversos tipos de arquivos pela rede celular.

Atualmente, a Messages API da Vonage oferece suporte a quatro tipos diferentes de mensagens MMS:

• Imagem: Suporta o envio .jpg, .jpeg, .png e .gif arquivos

• Áudio: Suporta o envio de .mp3 arquivos

• Video: Suporta o envio de .mp4 arquivos

• vCard: Suporta o envio de .vcf arquivos

Por que usar o MMS?

Existem muitos casos de uso diferentes para mensagens MMS. Elas são utilizadas para mensagens promocionais, o MMS pode agregar uma dimensão extra em comparação com as mensagens SMS, promovendo um produto com imagens, Videos ou até mesmo clipes de áudio. Há também muitas usos transacionais , como vídeos instrutivos como parte de um fluxo de trabalho de atendimento ao cliente ou o fornecimento de comprovantes de entrega de encomendas.

Envio de uma mensagem MMS com a Messages API do Vonage

Se você já usa o Vonage para enviar mensagens SMS, ou mesmo que ainda não tenha usado, é super fácil começar a enviar mensagens MMS usando o Vonage, especialmente agora que a Messages API foi adicionada aos nossos SDKs de servidor.

A Messages API expõe um único POST ponto de extremidade: https://api.nexmo.com/v1/messages, e espera um Authorization cabeçalho (recomendamos usar a autenticação por Bearer Token neste caso) e uma carga JSON com formato semelhante a este:

{
  "message_type": "image",
  "image": {
    "url": "https://example.com/image.jpg"
  },
  "to": "447700900000",
  "from": "447700900001",
  "channel": "mms"
}

O exemplo acima mostra a estrutura JSON que você usaria para enviar uma mensagem com imagem via MMS.

Há alguns pontos a serem observados aqui: o url propriedade da imagem precisa ser uma URL acessível publicamente, e há certos requisitos relativos à to e from números.

Para o número

Atualmente, a Messages API oferece suporte ao envio de MMS nos EUA para números das seguintes redes:

• AT&T

• T-Mobile

• Verizon

O to número fornecido à Messages API do Vonage precisa ser um número capaz de receber MMS em uma dessas redes.

De Número

O from número precisa ser um USSC (US Short Codes), 10DLC (código longo de 10 dígitos) ou TFN (número gratuito) habilitado para MMS e vinculado a uma campanha registrada. Os diferentes tipos de números oferecem diferentes recursos de MMS:

• USSC: imagens, vCard

• 10DLC: imagens, áudio, Video, vCard

• TFN: imagens, áudio, Video

Saiba mais sobre os diferentes tipos de números de telefone.

Exemplo de aplicação

A melhor maneira de demonstrar como usar a Messages API da Vonage para enviar mensagens MMS é apresentar um exemplo prático de aplicativo.

Não tenho nenhum produto para divulgar por MMS, mas adoro as tirinhas do xkcd, então usei o SDK Ruby da Vonage para criar um pequeno aplicativo em Ruby que envia uma mensagem MMS diária contendo uma história em quadrinhos aleatória do xkcd. Se você não for um programador Ruby, porém, pode usar um dos nossos outros SDKs de servidorou trabalhar diretamente com a Messages API para implementar algo semelhante.

Meu aplicativo em Ruby faz duas coisas:

• Obtém os dados de uma história em quadrinhos aleatória do xkcd a partir da API do xkcd

• Envia a história em quadrinhos como um MMS usando a Messages API da Vonage

Em seguida, configurei uma tarefa Cron que executa o aplicativo uma vez por dia, em um horário definido.

Configurando as dependências

Para a primeira tarefa do aplicativo — obter os dados da API do xkcd —, me deparei com um RubyGem que oferecia essa funcionalidade. Infelizmente, ela não fazia exatamente o que eu queria para meu aplicativo em termos de como retornava os dados, então decidi escrever meu próprio RubyGem, get_xkcd, que atendeu às minhas necessidades. Se você quiser se aprofundar na implementação, pode conferir o código-fonte no GitHub.

O meu Gemfile fica assim:

source "https://rubygems.org"

ruby "3.0"

gem "dotenv"
gem "vonage"
gem "rake"
gem "whenever", require: false
gem "get_xkcd"

A dependência mais importante aqui é o vonage gem, que uso para enviar o MMS por meio da Messages API do Vonage.

Estou usando meu get_xkcd para interagir com a API do xkcd. O dotenv gem serve para gerenciar as variáveis de ambiente do meu aplicativo. O rake gem e whenever gem servem para configurar uma tarefa a ser executada via Cron.

O Dossiê de Inscrição

Criei um app.rb arquivo que contém a lógica para obter os dados das tirinhas do xkcd e, em seguida, enviar uma mensagem MMS usando parte desses dados.

O arquivo principal do meu aplicativo tem a seguinte aparência:

# app.rb

require 'dotenv'
require 'vonage'
require 'get_xkcd'

Dotenv.load

random_issue_data = GetXkcd::Comic.fetch_random_issue_data

client = Vonage::Client.new(
  application_id: ENV['APP_ID'],
  private_key: File.read(ENV['PATH_TO_PRIVATE_KEY_PATH'])
)

message = Vonage::Messaging::Message.mms(
  type: 'image',
  message: {
    url: random_issue_data['img'],
    caption: random_issue_data['title']
  }
)

client.messaging.send(from: ENV['FROM_NUMBER'], to: ENV['TO_NUMBER'], **message)

O aplicativo começa solicitando o dotenv, vonage, e get_xkcd gems.

require 'dotenv'
require 'vonage'
require 'get_xkcd'

Todas as variáveis de ambiente necessárias estão definidas em um .env arquivo no diretório raiz do meu projeto e, em seguida, carregadas em um ENV hash usando o Dotenv.load método.

Dotenv.load

A primeira coisa que meu aplicativo precisa fazer é obter os dados de uma história em quadrinhos aleatória do xkcd. Minha GetXkcd biblioteca define uma Comic classe que oferece vários métodos. Um desses métodos é o fetch_random_issue_data que, como o nome sugere, busca os dados de uma edição aleatória da história em quadrinhos xkcd.

random_issue_data = GetXkcd::Comic.fetch_random_issue_data

O aplicativo armazena o resultado em uma random_issue_data variável. O valor de retorno do método é um Hash em Ruby com dados de uma história em quadrinhos xkcd aleatória, incluindo uma URL para a imagem da história como valor da img chave e o título da história em quadrinhos como o valor da title chave. Esses valores serão usados posteriormente na criação da mensagem MMS.

O restante do app.rb arquivo trata da criação e do envio da mensagem MMS.

Instanciamento do objeto cliente

O primeiro passo para enviar uma mensagem usando a Messages API do Vonage é instanciar um objeto Vonage Client . Aqui, passamos dois argumentos-chave: application_id e private_key.

client = Vonage::Client.new(
  application_id: ENV['APP_ID'],
  private_key: File.read(ENV['PATH_TO_PRIVATE_KEY_PATH'])
)

Talvez você esteja se perguntando o que esses dois argumentos representam.

Para usar a Messages API, você precisa criar um Aplicativo Vonage, seja pelo Painel do Desenvolvedor ou pela API de Applications, e habilite-o para Mensagens.

Screenshot of the Messages toggle in the Dashboard

Depois de criada, a aplicação terá um ID exclusivo. Você também poderá gerar e baixar uma chave privada para essa aplicação.

Screenshot of the Generate Private Key button in the Dashboard

Minha chave privada está armazenada no diretório raiz do arquivo do meu projeto. O ID do meu aplicativo e o caminho para a minha chave privada estão definidos no meu .env arquivo.

Um dos detalhes de que nossos SDKs de servidor se encarregam para você é lidar com a autenticação e gerar cabeçalhos de solicitações HTTP. O application_id e private_key dados passados ao instanciar o Client objeto são posteriormente usados para gerar um JWT (JSON Web Token), que é então definido como o valor do Authorization cabeçalho enviado com a solicitação HTTP para a Messages API.

Instanciando o objeto de mensagem MMS

O SDK Ruby da Vonage define um Messaging::Message objeto que fornece métodos para criar objetos de mensagem específicos para cada canal. Aqui, a chamada ao mms método retorna um MMS objeto com propriedades baseadas nos argumentos passados.

message = Vonage::Messaging::Message.mms(
  type: 'image',
  message: {
    url: random_issue_data['img'],
    caption: random_issue_data['title']
  }
)

Aqui definimos o type para image (outras opções para MMS type são audio, video, ou vcard). No message hash, definimos o url como a URL do img dos dados do xkcd e um caption para o title desses dados.

Envio da mensagem MMS

E agora, a parte importante do aplicativo: enviar a mensagem MMS!

client.messaging.send(from: ENV['FROM_NUMBER'], to: ENV['TO_NUMBER'], **message)

Ao chamar o messaging método no Client objeto que criamos anteriormente retorna um Messaging objeto. Em seguida, encadeamos uma send chamada de método a esse objeto retornado, o que combina o from e to número com o message objeto passado como parâmetro, converte-o para JSON e o envia como corpo de uma solicitação HTTP para o endpoint da Messages API POST .

Lembre-se das restrições relativas a from e to números explicadas anteriormente neste artigo.

Configurando a tarefa Cron

A tarefa final é configurar a tarefa Cron. Eu poderia editar o arquivo crontab manualmente, mas existe um Rubygem muito útil chamado whenever que simplifica o processo. O whenever gem oferece algumas opções diferentes para executar tarefas, como chamar um bash comando ou executar uma rake tarefa.

Rake é um executor de tarefas para Ruby. Ele permite que você defina determinadas tarefas usando a sintaxe do Ruby, que podem então ser executadas ao serem passadas para o rake comando. As tarefas são definidas em um Rakefile, portanto, precisamos adicionar um ao diretório do nosso projeto.

# Rakefile

desc "Send a random XKCD comic via MMS"
task :send_xkcd_mms do
  ruby 'app.rb'
end

Aqui, defino uma única tarefa com uma descrição (desc), um nome para a tarefa send_xkcd_mmse a própria tarefa (definida dentro de um do..end bloco) que consiste simplesmente em executar meu app.rb arquivo.

Para agendar a tarefa com o whenever gem preciso criar um schedule.rb arquivo dentro de um config diretório e definir a programação nele.

# schedule.rb

job_type :rake, "cd :path && bundle exec rake :task"

every 1.day, at: '9:00 am' do
  rake "send_xkcd_mms"
end

A job_type :rake, "cd :path && bundle exec rake :task" linha define alguns valores padrão para a execução da tarefa. A própria tarefa usa a sintaxe do Ruby para definir um intervalo (every 1.day), um horário específico (at: '9:00 am') e, em seguida, a tarefa que queremos agendar dentro de um do..end bloco (rake "send_xkcd_mms").

Para atualizar a programação do meu sistema crontab com essa programação, preciso então executar whenever --update-crontab a partir da linha de comando.

E pronto! As tirinhas diárias do xkcd por MMS.

Screenshot of xkcd comic in an MMS

Conclusão e próximos passos

Nesta postagem do blog, aprendemos um pouco mais sobre MMS, o que é possível fazer com ele e como usar a Messages API do Vonage para enviar uma mensagem MMS.

Sempre incentivamos a participação da comunidade. Fique à vontade para se juntar a nós no Slack da Comunidade Vonage ou nos enviar uma mensagem no Twitter.