https://github.com/messagebird/ruby-rest-api
MessageBird's REST API for Ruby
https://github.com/messagebird/ruby-rest-api
Last synced: 12 months ago
JSON representation
MessageBird's REST API for Ruby
- Host: GitHub
- URL: https://github.com/messagebird/ruby-rest-api
- Owner: messagebird
- License: bsd-2-clause
- Created: 2014-07-10T08:12:23.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2025-04-09T10:59:43.000Z (about 1 year ago)
- Last Synced: 2025-06-28T06:51:24.099Z (about 1 year ago)
- Language: Ruby
- Size: 392 KB
- Stars: 37
- Watchers: 10
- Forks: 49
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
MessageBird's REST API for Ruby
===============================
This repository contains the open source Ruby client for MessageBird's REST API. Documentation can be found at: https://developers.messagebird.com/
[](https://github.com/messagebird/ruby-rest-api/actions)
Requirements
------------
- [Sign up](https://dashboard.messagebird.com/app/en/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
Installation
------------
You can either include the following line in your Gemfile:
```ruby
gem 'messagebird-rest', require: 'messagebird'
```
Or you can just manually install it from the command line:
```sh
$ gem install messagebird-rest
```
Examples
--------
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.
```ruby
require 'pp' # Only needed for this example
require 'messagebird'
client = MessageBird::Client.new(YOUR_ACCESS_KEY)
```
That's easy enough. Now we can query the server for information.
##### Balance
Lets start with out with an overview of our balance.
```ruby
pp client.balance
#
```
##### Messages
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.
```ruby
pp client.message_create('FromMe', '31612345678', 'Hello World', reference: 'MyReference')
#1,
"totalSentCount"=>1,
"totalDeliveredCount"=>0,
"totalDeliveryFailedCount"=>0,
"items"=>
[#]},
@reference="MyReference",
@scheduled_datetime=nil,
@type="sms",
@type_details={},
@validity=nil>
```
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.
```ruby
client.message('211e6280453ba746e8eeff7b12582146')
```
##### HLR
To perform HLR lookups we have created the **hlr_create** method, which takes a number and a reference for parameters.
```ruby
pp client.hlr_create('31612345678', 'MyReference')
#
```
Similar to the **message_create** and **message** methods, the **hlr_create** method has an accompanying **hlr** method to poll the HLR object.
```ruby
client.hlr('4933bed0453ba7455031712h16830892')
```
##### Verify (One-Time Password)
You can send and verify One-Time Passwords through the MessageBird API using the **verify_create** and **verify_token** methods.
```ruby
# verify_create requires a recipient as a required parameter, and other optional paramaters
client.verify_create(31612345678, reference: "YourReference")
#"https://rest.messagebird.com/messages/67d42f004555213679416f0b13254392"},
@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.
```ruby
# 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.
```ruby
pp client.voice_message_create('31612345678', 'Hello World', reference: 'MyReference')
#1,
"totalSentCount"=>1,
"totalDeliveredCount"=>0,
"totalDeliveryFailedCount"=>0,
"items"=>
[#]},
@reference="MyReference",
@repeat=1,
@scheduledDatetime=nil,
@voice="female">
```
Similar to regular messaging and HLR lookups, there is a method available to fetch the VoiceMessage object by using an *id*.
```ruby
client.voice_message('a08e51a0353bd16cea7f298a37405850')
```
##### Numbers
There is also a Numbers API that allow you to search for and purchase number subscriptions to use as originator in other services.
```ruby
pp client.number_search("NL", limit: 52)
#,
#,
#,
#,
#],
@limit=5,
@type=MessageBird::Number>
````
Documentation
-------------
Complete documentation, instructions, and examples are available at:
[https://developers.messagebird.com/](https://developers.messagebird.com/).
Releasing this gem
------------------
[RELEASE.md](./RELEASE.md).
License
-------
The MessageBird REST Client for Ruby is licensed under [The BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause). Copyright (c) 2025, MessageBird