Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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.


There is also a Numbers API that allow you to search for and purchase number subscriptions to use as originator in other services.

pp client.number_search("NL", {:limit=>5})



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