This repository contains the open source Ruby client for MessageBird's REST API. Documentation can be found at: https://developers.messagebird.com/
- Sign up for a free MessageBird account
- Create a new
access_keyin 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-restWe 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 examplerequire'messagebird'client=MessageBird::Client.new(YOUR_ACCESS_KEY)That's easy enough. Now we can query the server for information.
Lets start with out with an overview of our balance.
ppclient.balance#<MessageBird::Balance:0x007f8d5c83f478@amount=9,@payment="prepaid",@type="credits">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.
ppclient.message_create('FromMe','31612345678','Hello World',reference: 'MyReference')#<MessageBird::Message:0x007f8d5b883520@body="Hello World",@created_datetime=2014-07-0712:20:30 +0200,@datacoding="plain",@direction="mt",@gateway=239,@href="https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146",@id="211e6280453ba746e8eeff7b12582146",@mclass=1,@originator="FromMe",@recipient={"total_count"=>1,"totalSentCount"=>1,"totalDeliveredCount"=>0,"totalDeliveryFailedCount"=>0,"items"=>[#<MessageBird::Recipient:0x007f8d5c058c00@recipient=31612345678,@status="sent",@statusDatetime=2014-07-0712:20:30 +0200>]},@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.
client.message('211e6280453ba746e8eeff7b12582146')To perform HLR lookups we have created the hlr_create method, which takes a number and a reference for parameters.
ppclient.hlr_create('31612345678','MyReference')#<MessageBird::HLR:0x007f8d5b8dafc8@created_datetime=2014-07-0712:20:05 +0200,@href="https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",@id="4933bed0453ba7455031712h16830892",@msisdn=31612345678,@network=nil,@reference="MyReference",@status="sent",@statusDatetime=2014-07-0712: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.
client.hlr('4933bed0453ba7455031712h16830892')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 paramatersclient.verify_create(31612345678,reference: "YourReference")#<MessageBird::Verify:0x007fb3c18c8148@id="080b7f804555213678f14f6o24607735",@recipient="31612345678",@reference="YourReference",@status="sent",@href={"message"=>"https://rest.messagebird.com/messages/67d42f004555213679416f0b13254392"},@created_datetime=2015-05-1216:51:19 +0200,@validUntilDatetime=2015-05-1216: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)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.
ppclient.voice_message_create('31612345678','Hello World',reference: 'MyReference')#<MessageBird::VoiceMessage:0x000001030101b8@body="Hello World",@created_datetime=2014-07-0912:17:50 +0200,@href="https://rest.messagebird.com/voicemessages/a08e51a0353bd16cea7f298a37405850",@id="a08e51a0353bd16cea7f298a37405850",@ifMachine="continue",@language="en-gb",@recipients={"total_count"=>1,"totalSentCount"=>1,"totalDeliveredCount"=>0,"totalDeliveryFailedCount"=>0,"items"=>[#<MessageBird::Recipient:0x000001011d3178@recipient=31612345678,@status="calling",@statusDatetime=2014-07-0912:17:50 +0200>]},@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.
client.voice_message('a08e51a0353bd16cea7f298a37405850')There is also a Numbers API that allow you to search for and purchase number subscriptions to use as originator in other services.
ppclient.number_search("NL",limit: 52)#<List:0x00007fa405130618@count=5,@items=[#<MessageBird::Number:0x00007fa405130528@country="NL",@features=["voice"],@locality="Rotterdam",@number="31102005108",@region="",@type="unknown">,#<MessageBird::Number:0x00007fa4051303c0@country="NL",@features=["voice"],@locality="Rotterdam",@number="31102005143",@region="",@type="unknown">,#<MessageBird::Number:0x00007fa405130208@country="NL",@features=["voice"],@locality="Rotterdam",@number="31102005145",@region="",@type="unknown">,#<MessageBird::Number:0x00007fa4051300c8@country="NL",@features=["voice"],@locality="Rotterdam",@number="31102005147",@region="",@type="unknown">,#<MessageBird::Number:0x00007fa405131c48@country="NL",@features=["voice"],@locality="Rotterdam",@number="31102005148",@region="",@type="unknown">],@limit=5,@type=MessageBird::Number>Complete documentation, instructions, and examples are available at: https://developers.messagebird.com/.
The MessageBird REST Client for Ruby is licensed under The BSD 2-Clause License. Copyright (c) 2014, MessageBird