Enviar mensagens SMS e MMS em Ruby

Neste guia, mostraremos como usar o Programmable SMS para enviar mensagens SMS e MMS em seu aplicativo da web Ruby.

Embora você possa enviar mensagens SMS somente de texto em praticamente qualquer lugar do planeta, o envio de mídia está disponível atualmente apenas nos EUA e no Canadá. Saiba mais neste artigo de suporte.

Os trechos de código neste guia são escritos usando a linguagem Ruby versão 2.0.0 ou superior e usam o SDK Ruby da Twilio. Vamos começar!

Se você tiver uma conta e um número de telefone da Twilio com recursos de SMS, está tudo pronto! Sinta-se à vontade para ir direto para o código.

Antes de receber chamadas telefônicas e enviar mensagens, você precisa se inscrever em uma conta da Twilio e adquirir um número de telefone da Twilio.

Se você é novo na Twilio, pode se inscrever em uma conta de avaliação gratuita para começar. Depois de se conectar, acesse o Console e obtenha o Account SID (SID da conta) e seu Auth Token (Token de autenticação). Você precisará desses valores para os exemplos de código abaixo.

Obter um número de telefone com recursos de SMS (e MMS)

O envio de mensagens requer um número de telefone da Twilio com recursos de SMS. Se você não possui atualmente um número de telefone da Twilio com recursos de SMS, precisará adquirir um. Depois de navegar até a página Buy a Number (Comprar um número), marque a caixa "SMS" e clique em "Search" (Pesquisar):

Se você mora nos EUA ou no Canadá e também deseja enviar mensagens MMS, pode selecionar a caixa "MMS". Ao visualizar os resultados da pesquisa, você pode ver os ícones do recurso na lista de números disponíveis:

Click Buy Button to Purchase an SMS-capable Number

Encontre um número que você goste e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.

Se estiver usando uma conta de avaliação, você precisará verificar seu número de telefone pessoal pelo console para poder testar o envio de SMS para você mesmo.

Saiba mais sobre como trabalhar com sua conta de avaliação gratuita.

Agora que você tem um número de telefone da Twilio, pode começar a enviar mensagens para dispositivos móveis.

Enviar uma mensagem SMS em Ruby pela API REST

Para enviar uma mensagem SMS da sua conta da Twilio, você precisará fazer um HTTP POST para o recurso Message da Twilio.

A biblioteca Ruby da Twilio ajuda a criar uma nova instância do recurso Message, especificando os parâmetros To, From e Body da mensagem.

Se você ainda não tiver a biblioteca auxiliar Ruby instalada, poderá instalá‐la a partir do RubyGems:

gem install twilio-ruby

Você também pode instalar manualmente a biblioteca. As instruções estão aqui.

Agora, crie um arquivo chamado send_sms.rb e inclua o seguinte código:

Loading Code Sample...

Example JSON response

Enviar um SMS usando a API do Programmable SMS

Substitua os valores do espaço reservado account_sid e auth_token por seus valores exclusivos. Você pode encontrá‐los no Console da Twilio.

Observação: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê‐las secretas antes de implantar na produção. Confira como definir variáveis de ambiente para obter mais informações.

Você informará à Twilio qual número de telefone usar para enviar essa mensagem substituindo o número from pelo número de telefone da Twilio que você comprou anteriormente.

Em seguida, especifique-se como o destinatário da mensagem substituindo o número to pelo número de telefone do seu celular. Os parâmetros from e todevem usar a formatação E.164 (+ e um código de país, por exemplo +16175551212)

Também incluímos o parâmetro body, que inclui o conteúdo do SMS que enviaremos.

Depois de atualizar o exemplo de código, você pode testá‐lo executando‐o na linha de comando:

ruby send_sms.rb

Em apenas alguns instantes você deve receber um SMS!

Se estiver usando uma conta de avaliação, você notará que todas as mensagens enviadas sempre começarão com "Sent from a Twilio trial account (Enviado de uma conta de avaliação da Twilio)". Depois de atualizar sua conta, você não verá mais esta mensagem. Saiba mais sobre o envio de mensagens SMS e MMS a partir de uma conta de avaliação.

Vamos ver o que acontece nos bastidores quando você envia esta solicitação para a Twilio.

Resposta da Twilio

Quando a Twilio receber sua solicitação para enviar um SMS pela API REST, ela verificará se você incluiu um número de telefone válido da Twilio no campo from. A Twilio enfileirará o SMS ou retornará esse erro HTTP em resposta à sua solicitação.

Supondo que sua solicitação não tenha gerado um erro, a resposta HTTP da Twilio incluirá o SID da nova mensagem. Esse identificador exclusivo nos ajudará a fazer referência a esta mensagem mais tarde. No código acima, imprimimos esse SID no terminal.

A resposta JSON da Twilio inclui uma quantidade robusta de dados sobre sua mensagem. Um exemplo de resposta pode ser assim:

{"sid": "SMxxxxxxxxxxxxxxx", 
 "date_created": "Thu, 09 Aug 2018 17:26:08 +0000", 
 "date_updated": "Thu, 09 Aug 2018 17:26:08 +0000", 
 "date_sent": null, 
 "account_sid": "ACxxxxxxxxxxxxxxxx", 
 "to": "+15558675310",
 "from": "+15017122661",
 "messaging_service_sid": null,
 "body": "This is the ship that made the Kessel Run in fourteen parsecs?", 
 "status": "queued", 
 "num_segments": "1", 
 "num_media": "0",
 "direction": "outbound-api",
 "api_version": "2010-04-01",
 "price": null,
 "price_unit": "USD",
 "error_code": null,
 "error_message": null,
 "uri": "/2010-04-01/Accounts/ACxxxxxxxxx/Messages/SMxxxxxxxxxxxx.json",
 "subresource_uris": {
     "media": null
 }
}

Você pode acessar qualquer um desses atributos a partir do seu código Ruby, como fizemos quando imprimimos o message.sid como uma string.

Tente adicionar uma instrução puts como puts message.status. Salve o arquivo e execute o código com ruby send_sms.rb mais uma vez. Você deverá ver o status de sua mensagem, "queued", impresso em seu terminal.

Se você receber um erro em resposta da Twilio ou nunca receber a mensagem, consulte essas dicas de resolução de problemas de mensagens não entregues.

Se desejar rastrear o status de suas mensagens em tempo real, será necessário configurar um URL de StatusCallback. Saiba mais em nosso tutorial sobre como confirmar a entrega de mensagens em Ruby.

Enviar uma mensagem para vários destinatários

Se quiser enviar uma mensagem para vários destinatários, você poderá criar uma matriz de destinatários e percorrer cada número de telefone na matriz:

numbers_to_message = ['+15558675310', '+14158141829', '+15017122661']
numbers_to_message.each do |number|
    message = @client.messages.create(
        body: 'Hello from my Twilio number!',
        from: '+15017122661',
        to: number
    )
    puts message.status
end

Isso criará uma nova instância de mensagem para cada número de telefone na lista.

Uma nota sobre a limitação da taxa de mensagens

À medida que você envia mais mensagens pela API, a Twilio as coloca na fila para entrega no limite de taxa prescrito. As solicitações de API para mensagens que excederem as taxas especificadas serão enfileiradas e executadas conforme a capacidade estiver disponível.

Se o seu aplicativo tentar colocar em fila mais de quatro horas de tráfego de saída (por exemplo, enfileirando mais de 14.400 mensagens para o Canadá em um número de telefone de long code), a API começará a retornar erros 429.

Se você precisar colocar uma grande quantidade de mensagens na fila, talvez seja útil aproveitar os Serviços de mensagens da Twilio. Consulte nosso guia sobre como configurar e enviar mensagens de um serviço de mensagens para obter mais dicas.

Enviar uma mensagem contendo mídia (MMS) em Ruby

Embora você possa enviar mensagens SMS somente de texto em praticamente qualquer lugar do planeta, o envio de mídia está disponível atualmente apenas nos EUA e no Canadá.

Para incluir mídia em sua mensagem de texto com tecnologia Twilio, você precisa adicionar o código que escrevemos acima. Desta vez, precisamos adicionar o parâmetro media_url.

Agora, crie um arquivo chamado send_mms.rb e inclua o seguinte código:

Loading Code Sample...

Example JSON response

Envie uma mensagem com um URL de imagem

Novamente, atualize os parâmetros from e to para usar o número de telefone da Twilio e o telefone celular.

O novo parâmetro media_url neste código informa à Twilio onde obter a mídia que queremos incluir. Este deve ser um URL acessível publicamente: A Twilio não poderá acessar nenhum URL oculto ou que exija autenticação.

Assim como quando você envia um SMS simples, a Twilio envia dados sobre a mensagem em resposta à sua solicitação. A resposta JSON conterá o SID exclusivo e o URI para seu recurso de mídia:

"subrecurso_uris": {"mídia": "/2010-04 01/Contas/ACxxxxxxxx/Mensagens/SMxxxxxxxxxxxxx/Mídia.json"}

Quando a API REST da Twilio criar seu novo recurso Message, ela salvará a imagem encontrada no media_url especificada como um recurso de mídia. Uma vez criado, você pode acessar esse recurso a qualquer momento por meio da API.

Você pode imprimir esse valor a partir do seu código Ruby para ver onde a imagem está armazenada. Adicione a seguinte linha ao final do seu arquivo send_mms.rb para ver seu URI de mídia recém‐provisionado:

puts message.media.instance_variable_get :@uri

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

ruby send_mms.rb

Em alguns segundos, você deve receber uma mensagem de texto com uma imagem!

O que vem a seguir?

Você acaba de enviar com êxito algumas mensagens com a API do Programmable SMS da Twilio e a biblioteca auxiliar Ruby.

Confira esses recursos detalhados para levar sua mensagem programática a um novo patamar:

Saiba como enviar um SMS durante uma chamada em andamento com Ruby e Sinatra.
Monitore o status da mensagem para confirmar a entrega.
Saiba como responder a um SMS enviado para o número de telefone da Twilio.
Saiba como gerenciar o estado da mensagem para transformar mensagens individuais em uma verdadeira conversa por SMS.
Aprofunde‐se nos detalhes com nossa documentação de referência de API para mensagens.
Enviando mensagens de alto volume? Confira nossos serviços de mensagens.

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.

Enviar um SMS usando a API do Programmable SMS

Envie uma mensagem com um URL de imagem

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!