With the Twilio API for WhatsApp we can send messages to WhatsApp numbers. Those messages can be plain text or include files like images, audio and even PDFs up to 5MB. Let's see how to do so using Ruby.

Things you'll need

If you want to code along with this post, you'll need a few things:

• A Twilio account (sign up for a free account now)
• Ruby and Bundler installed
• The WhatsApp Sandbox Channel installed (learn how to activate your WhatsApp sandbox)

Got all that? Let's get coding then!

Create a new directory for your project and use Bundler to initialise a new Gemfile:

mkdir whatsapp-messages
cd whatsapp-messages
bundle init

Open up the new Gemfile and add the twilio-ruby gem:

# frozen_string_literal: true

source "https://rubygems.org"

gem "twilio-ruby"

Install the gem by running bundle install on the command line.

Sending your first WhatsApp message

Create a file in your project directory called app.rb and open it up. We're going to require the twilio-ruby gem and initialise an API client with our Account Sid and Auth Token (which you can find on your Twilio console). We will use the API client to send a message from the WhatsApp Sandbox number to our own WhatsApp account.

# app.rb
require 'twilio-ruby'

client = Twilio::REST::Client.new('YOUR_ACCOUNT_SID', 'YOUR_AUTH_TOKEN')
message = client.messages.create(
  to: 'whatsapp:YOUR_WHATSAPP_NUMBER',
  from: 'whatsapp:WHATSAPP_SANDBOX_NUMBER',
  body: 'Ahoy from Twilio!'
)
puts "Message sent.\nMessage SID: #{message.sid}."

Make sure to replace all the placeholders with your own details. WhatsApp numbers take the format "whatsapp:E.164-phone-number". An E.164 formatted phone number starts with the country code followed by the rest of the number with no other punctuation, for example "+15551231234".

Run the code with:

bundle exec ruby app.rb

You should receive your message in the WhatsApp app.

Note: there are some differences between WhatsApp and regular SMS via the Twilio API. You can only send free-form messages if you have an active session established with a user. Sessions are created when users respond to a template message or the user initiates the conversation by sending a message to your WhatsApp number. A session lasts 24 hours from the last message the user sent to you. If you didn't receive a message, try sending a message to the WhatsApp sandbox first and then running the script again.

Sending media messages

We can do better than just a text message. This time let's send an image. The Twilio API for WhatsApp supports sending JPG, JPEG or PNG images.

To send a media message, we need to add one more thing to the call to create a message, a media_url. The media_url needs to point to an image file that is available online and the content type header should match the extension.

Add the media_url to your existing code. You can use the URL below or pick your own image.

# app.rb
require 'twilio-ruby'

client = Twilio::REST::Client.new('YOUR_ACCOUNT_SID', 'YOUR_AUTH_TOKEN')
message = client.messages.create(
  to: 'whatsapp:+447719532208',
  from: 'whatsapp:+14155238886',
  body: 'Ahoy from Twilio!',
  media_url: 'https://tinyurl.com/ahoy-whatsapp'
)
puts "Message sent. Message SID: #{message.sid}."

Run the code again and you will receive a text message and the image alongside.

What's next?

Now you've sent WhatsApp messages with text and images using Ruby. Next, you could try sending an audio file (in the MP3, OGG, and AMR formats) or a PDF file, as long as they are under 5MB in size.

Want to get a bit more involved with WhatsApp messages and Ruby? Check out how to combine WhatsApp, Spotify and Rails to create a collaborative playlist or how to take images from WhatsApp and use AWS Rekognition to check for celebrities in your pictures.

I'd love to see what you can build sending and receiving media over WhatsApp with the Twilio API. Hit me up in the comments, over email at philnash@twilio.com or on Twitter at @philnash with your projects or questions.