Skip to content
MessageBird's REST API for Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

MessageBird's REST API for Ruby

This repository contains the open source Ruby client for MessageBird's REST API. Documentation can be found at:

Build Status


  • Sign up for a free MessageBird account
  • Create a new access_key in the developers sections
  • MessageBird's API client for Ruby requires Ruby >= 1.9


You can either include the following line in your Gemfile:

gem 'messagebird-rest', :require => 'messagebird'

Or you can just manually install it from the command line:

$ gem install messagebird-rest


We have put some self-explanatory examples in the examples directory, but here is a quick breakdown on how it works. First, you need to create an instance of MessageBird::Client. Be sure to replace YOUR_ACCESS_KEY with something real in the bottom example.

require 'pp'              # Only needed for this example
require 'messagebird'

client =

That's easy enough. Now we can query the server for information.


Lets start with out with an overview of our balance.

pp client.balance


Chances are that the most common use you'll have for this API client is the ability to send out text messages. For that purpose we have created the message_create method, which takes the required originator, one or more recipients and a body text for parameters.

Optional parameters can be specified as a hash.

pp client.message_create('FromMe', '31612345678', 'Hello World', :reference => 'MyReference')

 @body="Hello World",
 @created_datetime=2014-07-07 12:20:30 +0200,
      @statusDatetime=2014-07-07 12:20:30 +0200>]},

As a possible follow-up, you can use the message method with the above mentioned batch-id to query the status of the message that you just created. It will return a similar Message object.


To perform HLR lookups we have created the hlr_create method, which takes a number and a reference for parameters.

pp client.hlr_create('31612345678', 'MyReference')

 @created_datetime=2014-07-07 12:20:05 +0200,
 @statusDatetime=2014-07-07 12:20:05 +0200>

Similar to the message_create and message methods, the hlr_create method has an accompanying hlr method to poll the HLR object.

Verify (One-Time Password)

You can send and verify One-Time Passwords through the MessageBird API using the verify_create and verify_token methods.

# verify_create requires a recipient as a required parameter, and other optional paramaters
client.verify_create(31612345678, {:reference => "YourReference"})

 @created_datetime=2015-05-12 16:51:19 +0200,
 @validUntilDatetime=2015-05-12 16:51:49 +0200>

This sends a token to the recipient, which can be verified with the verify_token method.

# verify_token requires the id of the verify request and a token as required parameters.
client.verify_token('080b7f804555213678f14f6o24607735', 123456)
Voice Message

MessageBird also offers the ability to send out a text message as a voice message, or text-to-speech. For that purpose we have created the voice_message_create method, which takes one or more required recipients and a body text for parameters.

Optional parameters can be specified as a hash.

pp client.voice_message_create('31612345678', 'Hello World', :reference => 'MyReference')

 @body="Hello World",
 @created_datetime=2014-07-09 12:17:50 +0200,
      @statusDatetime=2014-07-09 12:17:50 +0200>]},

Similar to regular messaging and HLR lookups, there is a method available to fetch the VoiceMessage object by using an id.

Conversations WhatsApp Sandbox

To use the whatsapp sandbox you need to add MessageBird::Client::ENABLE_CONVERSATIONS_WHATSAPP_SANDBOX to the list of features you want enabled. Don't forget to replace YOUR_ACCESS_KEY with your actual access key.

require 'messagebird'

client =


Complete documentation, instructions, and examples are available at:


The MessageBird REST Client for Ruby is licensed under The BSD 2-Clause License. Copyright (c) 2014, MessageBird

You can’t perform that action at this time.