Skip to content

Commit 8d19e94

Browse files
prepprep
committed
first commit
0 parents  commit 8d19e94

20 files changed

+778
-0
lines changed

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Copyright (c) 2014, MessageBird
2+
All rights reserved.
3+
4+
Redistribution and use in source and binary forms, with or without
5+
modification, are permitted provided that the following conditions are met:
6+
7+
1. Redistributions of source code must retain the above copyright notice, this
8+
list of conditions and the following disclaimer.
9+
2. Redistributions in binary form must reproduce the above copyright notice,
10+
this list of conditions and the following disclaimer in the documentation
11+
and/or other materials provided with the distribution.
12+
13+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
14+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
15+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
16+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
17+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
18+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
19+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
20+
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
22+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
MessageBird's REST API for Ruby
2+
===============================
3+
This repository contains the open source Ruby client for MessageBird's REST API. Documentation can be found at: https://www.messagebird.com/developers/ruby.
4+
5+
Requirements
6+
------------
7+
- [Sign up](https://www.messagebird.com/en/signup) for a free MessageBird account
8+
- Create a new access_key in the developers sections
9+
- MessageBird's API client for Ruby requires Ruby >= 1.9
10+
11+
Installation
12+
------------
13+
You can either include the following line in your Gemfile:
14+
15+
```ruby
16+
gem 'messagebird-rest', :require => 'messagebird'
17+
```
18+
19+
Or you can just manually install it from the command line:
20+
```sh
21+
$ gem install messagebird-rest
22+
```
23+
24+
Examples
25+
--------
26+
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.
27+
28+
```ruby
29+
require 'pp' # Only needed for this example
30+
require 'messagebird'
31+
32+
client = MessageBird::Client.new(YOUR_ACCESS_KEY)
33+
```
34+
35+
That's easy enough. Now we can query the server for information.
36+
37+
##### Balance
38+
Lets start with out with an overview of our balance.
39+
40+
```ruby
41+
pp client.balance
42+
43+
#<MessageBird::Balance:0x007f8d5c83f478
44+
@amount=9,
45+
@payment="prepaid",
46+
@type="credits">
47+
```
48+
49+
##### Messages
50+
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.
51+
52+
Optional parameters can be specified as a hash.
53+
54+
```ruby
55+
pp client.message_create('FromMe', '31612345678', 'Hello World', :reference => 'MyReference')
56+
57+
#<MessageBird::Message:0x007f8d5b883520
58+
@body="Hello World",
59+
@createdDatetime=2014-07-07 12:20:30 +0200,
60+
@datacoding="plain",
61+
@direction="mt",
62+
@gateway=239,
63+
@href=
64+
"https://rest.messagebird.com/messages/211e6280453ba746e8eeff7b12582146",
65+
@id="211e6280453ba746e8eeff7b12582146",
66+
@mclass=1,
67+
@originator="FromMe",
68+
@recipient=
69+
{"totalCount"=>1,
70+
"totalSentCount"=>1,
71+
"totalDeliveredCount"=>0,
72+
"totalDeliveryFailedCount"=>0,
73+
"items"=>
74+
[#<MessageBird::Recipient:0x007f8d5c058c00
75+
@recipient=31612345678,
76+
@status="sent",
77+
@statusDatetime=2014-07-07 12:20:30 +0200>]},
78+
@reference="MyReference",
79+
@scheduledDatetime=nil,
80+
@type="sms",
81+
@typeDetails={},
82+
@validity=nil>
83+
```
84+
85+
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.
86+
87+
```ruby
88+
client.message('211e6280453ba746e8eeff7b12582146')
89+
```
90+
91+
##### HLR
92+
To perform HLR lookups we have created the **hlr_create** method, which takes a number and a reference for parameters.
93+
94+
```ruby
95+
pp client.hlr_create('31612345678', 'MyReference')
96+
97+
#<MessageBird::HLR:0x007f8d5b8dafc8
98+
@createdDatetime=2014-07-07 12:20:05 +0200,
99+
@href="https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
100+
@id="4933bed0453ba7455031712h16830892",
101+
@msisdn=31612345678,
102+
@network=nil,
103+
@reference="MyReference",
104+
@status="sent",
105+
@statusDatetime=2014-07-07 12:20:05 +0200>
106+
```
107+
108+
Similar to the **message_create** and **message** methods, the **hlr_create** method has an accompanying **hlr** method to poll the HLR object.
109+
110+
```ruby
111+
client.hlr('4933bed0453ba7455031712h16830892')
112+
```
113+
114+
##### Voice Message
115+
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.
116+
117+
Optional parameters can be specified as a hash.
118+
119+
```ruby
120+
pp client.voice_message_create('31612345678', 'Hello World', :reference => 'MyReference')
121+
122+
#<MessageBird::VoiceMessage:0x000001030101b8
123+
@body="Hello World",
124+
@createdDatetime=2014-07-09 12:17:50 +0200,
125+
@href=
126+
"https://rest.messagebird.com/voicemessages/a08e51a0353bd16cea7f298a37405850",
127+
@id="a08e51a0353bd16cea7f298a37405850",
128+
@ifMachine="continue",
129+
@language="en-gb",
130+
@recipients=
131+
{"totalCount"=>1,
132+
"totalSentCount"=>1,
133+
"totalDeliveredCount"=>0,
134+
"totalDeliveryFailedCount"=>0,
135+
"items"=>
136+
[#<MessageBird::Recipient:0x000001011d3178
137+
@recipient=31612345678,
138+
@status="calling",
139+
@statusDatetime=2014-07-09 12:17:50 +0200>]},
140+
@reference="MyReference",
141+
@repeat=1,
142+
@scheduledDatetime=nil,
143+
@voice="female">
144+
```
145+
146+
Similar to regular messaging and HLR lookups, there is a method available to fetch the VoiceMessage object by using an *id*.
147+
148+
```ruby
149+
client.voice_message('a08e51a0353bd16cea7f298a37405850')
150+
```
151+
152+
Documentation
153+
-------------
154+
Complete documentation, instructions, and examples are available at:
155+
[https://www.messagebird.com/developers/ruby](https://www.messagebird.com/developers/ruby).
156+
157+
License
158+
-------
159+
The MessageBird REST Client for Ruby is licensed under [The BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause). Copyright (c) 2014, MessageBird

‎Rakefile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
require 'rake/testtask'
2+
3+
namespace :gem do
4+
desc 'Build the messagebird API gem'
5+
task :build do
6+
sh 'gem build messagebird-rest.gemspec'
7+
end
8+
9+
desc 'Upload the gem to rubygems.org'
10+
task :upload do
11+
sh 'gem push messagebird-rest-*.gem'
12+
end
13+
end

‎examples/balance.rb‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
#!/usr/bin/env ruby
2+
3+
$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
4+
require 'messagebird'
5+
6+
ACCESS_KEY = 'test_gshuPaZoeEG6ovbc8M79w0QyM'
7+
8+
begin
9+
# Create a MessageBird client with the specified ACCESS_KEY.
10+
client = MessageBird::Client.new(ACCESS_KEY)
11+
12+
# Fetch the Balance object.
13+
balance = client.balance
14+
15+
# Print the object information.
16+
puts
17+
puts "The following information was returned as a Balance object:"
18+
puts
19+
puts " payment : #{balance.payment}"
20+
puts " type : #{balance.type}"
21+
puts " amount : #{balance.amount}"
22+
puts
23+
24+
rescue MessageBird::ErrorException => ex
25+
puts
26+
puts 'An error occured while requesting a Balance object:'
27+
puts
28+
29+
ex.errors.each do |error|
30+
puts " code : #{error.code}"
31+
puts " description : #{error.description}"
32+
puts " parameter : #{error.parameter}"
33+
puts
34+
end
35+
end

‎examples/hlr.rb‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#!/usr/bin/env ruby
2+
3+
$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
4+
require 'messagebird'
5+
6+
# ACCESS_KEY = ''
7+
# HLR_ID = ''
8+
9+
unless defined?(ACCESS_KEY)
10+
puts 'You need to set an ACCESS_KEY constant in this file'
11+
exit 1
12+
end
13+
14+
unless defined?(HLR_ID)
15+
puts 'You need to set an HLR_ID constant in this file'
16+
end
17+
18+
begin
19+
# Create a MessageBird client with the specified ACCESS_KEY.
20+
client = MessageBird::Client.new(ACCESS_KEY)
21+
22+
# Fetch the HLR object for the specified HLR_ID.
23+
hlr = client.hlr(HLR_ID)
24+
25+
# Print the object information.
26+
puts
27+
puts "The following information was returned as an HLR object:"
28+
puts
29+
puts " id : #{hlr.id}"
30+
puts " href : #{hlr.href}"
31+
puts " msisdn : #{hlr.msisdn}"
32+
puts " reference : #{hlr.reference}"
33+
puts " status : #{hlr.status}"
34+
puts " createdDatetime : #{hlr.createdDatetime}"
35+
puts " statusDatetime : #{hlr.statusDatetime}"
36+
puts
37+
38+
rescue MessageBird::ErrorException => ex
39+
puts
40+
puts 'An error occured while requesting an HLR object:'
41+
puts
42+
43+
ex.errors.each do |error|
44+
puts " code : #{error.code}"
45+
puts " description : #{error.description}"
46+
puts " parameter : #{error.parameter}"
47+
puts
48+
end
49+
end

‎examples/hlr_create.rb‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#!/usr/bin/env ruby
2+
3+
$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
4+
require 'messagebird'
5+
6+
ACCESS_KEY = 'test_gshuPaZoeEG6ovbc8M79w0QyM'
7+
8+
begin
9+
# Create a MessageBird client with the specified ACCESS_KEY.
10+
client = MessageBird::Client.new(ACCESS_KEY)
11+
12+
# Create a new HLR object.
13+
hlr = client.hlr_create('31612345678', 'MyReference')
14+
15+
# Print the object information.
16+
puts
17+
puts "The following information was returned as an HLR object:"
18+
puts
19+
puts " id : #{hlr.id}"
20+
puts " href : #{hlr.href}"
21+
puts " msisdn : #{hlr.msisdn}"
22+
puts " reference : #{hlr.reference}"
23+
puts " status : #{hlr.status}"
24+
puts " createdDatetime : #{hlr.createdDatetime}"
25+
puts " statusDatetime : #{hlr.statusDatetime}"
26+
puts
27+
28+
rescue MessageBird::ErrorException => ex
29+
puts
30+
puts 'An error occured while requesting an HLR object:'
31+
puts
32+
33+
ex.errors.each do |error|
34+
puts " code : #{error.code}"
35+
puts " description : #{error.description}"
36+
puts " parameter : #{error.parameter}"
37+
puts
38+
end
39+
end

‎examples/message.rb‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
#!/usr/bin/env ruby
2+
3+
$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
4+
require 'messagebird'
5+
6+
# ACCESS_KEY = ''
7+
# MESSAGE_ID = ''
8+
9+
unless defined?(ACCESS_KEY)
10+
puts 'You need to set an ACCESS_KEY constant in this file'
11+
exit 1
12+
end
13+
14+
unless defined?(MESSAGE_ID)
15+
puts 'You need to set an MESSAGE_ID constant in this file'
16+
end
17+
18+
begin
19+
# Create a MessageBird client with the specified ACCESS_KEY.
20+
client = MessageBird::Client.new(ACCESS_KEY)
21+
22+
# Fetch the Message object for the specified MESSAGE_ID.
23+
msg = client.message(MESSAGE_ID)
24+
25+
# Print the object information.
26+
puts
27+
puts "The following information was returned as a Message object:"
28+
puts
29+
puts " id : #{msg.id}"
30+
puts " href : #{msg.href}"
31+
puts " direction : #{msg.direction}"
32+
puts " type : #{msg.type}"
33+
puts " originator : #{msg.originator}"
34+
puts " body : #{msg.body}"
35+
puts " reference : #{msg.reference}"
36+
puts " validity : #{msg.validity}"
37+
puts " gateway : #{msg.gateway}"
38+
puts " typeDetails : #{msg.typeDetails}"
39+
puts " datacoding : #{msg.datacoding}"
40+
puts " mclass : #{msg.mclass}"
41+
puts " scheduledDatetime : #{msg.scheduledDatetime}"
42+
puts " createdDatetime : #{msg.createdDatetime}"
43+
puts " recipients : #{msg.recipients}"
44+
puts
45+
46+
rescue MessageBird::ErrorException => ex
47+
puts
48+
puts 'An error occured while requesting an Message object:'
49+
puts
50+
51+
ex.errors.each do |error|
52+
puts " code : #{error.code}"
53+
puts " description : #{error.description}"
54+
puts " parameter : #{error.parameter}"
55+
puts
56+
end
57+
end

0 commit comments

Comments
 (0)