Class: Mollie::SMS

Inherits:
Object
  • Object
show all
Defined in:
lib/mollie/sms.rb,
lib/mollie/sms/test_helper.rb

Overview

A class that allows you to send SMS messages through the Mollie.nl SMS webservice.

See the README for examples on how to use this.

Defined Under Namespace

Modules: Exceptions, TestHelper Classes: Response

Constant Summary

GATEWAY_URI =

The SSL URI to which the parameters of a SMS are posted.

Note that the certificate is not verified.

URI.parse("https://api.messagebird.com/xml/sms")
GATEWAYS =

The possible values that indicate which SMS gateway should be used.

{
  'basic'     => '2',
  'business'  => '4',
  'business+' => '1',
  'landline'  => '8'
}
REQUIRED_PARAMS =

A list of paramaters that must to be included in the parameters send to the gateway.

%w{ username md5_password originator gateway charset type recipients message }

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(telephone_number = nil, body = nil, extra_params = {}) ⇒ SMS

Initializes a new Mollie::SMS instance.

You can either specify the recipient’s telephone number and message body here, or later on through the accessors for these attributes.

Parameters:

  • telephone_number (String) (defaults to: nil)

    The recipient’s telephone number.

  • body (String) (defaults to: nil)

    The message body.

  • extra_params (Hash) (defaults to: {})

    Optional parameters that are to be merged with the default parameters.



161
162
163
164
165
# File 'lib/mollie/sms.rb', line 161

def initialize(telephone_number = nil, body = nil, extra_params = {})
  @params = self.class.default_params.merge(extra_params)
  self.telephone_number = telephone_number if telephone_number
  self.body = body if body
end

Class Attribute Details

.charsetString

Returns A character set name, describing the message’s body encoding. Defaults to ‘UTF-8’.

Returns:

  • (String)

    A character set name, describing the message’s body encoding. Defaults to ‘UTF-8’.



96
97
98
# File 'lib/mollie/sms.rb', line 96

def charset
  @charset
end

.gatewayString

The gateway that should be used to send messages. Possible values are:

Defaults to ‘basic’.

Returns:

  • (String)

    The gateway ID.

See Also:



122
123
124
# File 'lib/mollie/sms.rb', line 122

def gateway
  @gateway
end

.originatorString

The number, or display name, that will be used to indicate the originator of a message.

It should be upto either fourteen numerical characters, or eleven alphanumerical characters.

Returns:

  • (String)

    The originator

See Also:



92
93
94
# File 'lib/mollie/sms.rb', line 92

def originator
  @originator
end

.passwordString

Returns A MD5 hashed version of your password for the Mollie.nl SMS webservice.

Returns:

  • (String)

    A MD5 hashed version of your password for the Mollie.nl SMS webservice.



78
79
80
# File 'lib/mollie/sms.rb', line 78

def password
  @password
end

.typeString

The type of messages that will be send. Possible values are:

  • normal

  • wappush

  • vcard

  • flash

  • binary

  • long

Defaults to ‘normal’

Returns:

  • (String)

    The message type.



109
110
111
# File 'lib/mollie/sms.rb', line 109

def type
  @type
end

.usernameString

Returns Your username for the Mollie.nl SMS webservice.

Returns:

  • (String)

    Your username for the Mollie.nl SMS webservice.



74
75
76
# File 'lib/mollie/sms.rb', line 74

def username
  @username
end

Instance Attribute Details

#paramsHash (readonly)

Returns The parameters that will be send to the gateway.

Returns:

  • (Hash)

    The parameters that will be send to the gateway.



148
149
150
# File 'lib/mollie/sms.rb', line 148

def params
  @params
end

Class Method Details

.default_paramsHash

Returns the default parameters that will be we merged with each instance’s params.

This includes username, md5_password, originator, gateway, charset, and type.

Returns:

  • (Hash)


131
132
133
134
135
136
137
138
139
140
# File 'lib/mollie/sms.rb', line 131

def default_params
  {
    'username'     => @username,
    'md5_password' => @password,
    'originator'   => @originator,
    'gateway'      => @gateway,
    'charset'      => @charset,
    'type'         => @type
  }
end

Instance Method Details

#==(other) ⇒ Boolean

Compares whether or not this and the other Mollie::SMS instance are equal in recipient, body, and other parameters.

Parameters:

  • other (SMS)

    The Mollie::SMS instance to compare against.

Returns:

  • (Boolean)


198
199
200
# File 'lib/mollie/sms.rb', line 198

def ==(other)
  other.is_a?(SMS) && other.params == params
end

#bodyString

Returns The message body.

Returns:

  • (String)

    The message body.



181
182
183
# File 'lib/mollie/sms.rb', line 181

def body
  @params['message']
end

#body=(body) ⇒ String

Assigns the message’s body.

Parameters:

  • body (String)

    The message’s body.

Returns:

  • (String)

    The message’s body.



189
190
191
# File 'lib/mollie/sms.rb', line 189

def body=(body)
  @params['message'] = body
end

#deliverResponse

Posts the parameters to the gateway, through SSL.

The params are validated before attempting to post them.

Returns:

  • (Response)

    A response object which encapsulates the result of the request.

See Also:



219
220
221
222
223
224
225
226
227
228
229
230
231
# File 'lib/mollie/sms.rb', line 219

def deliver
  validate_params!

  post = Net::HTTP::Post.new(GATEWAY_URI.path)
  post.form_data = params
  request = Net::HTTP.new(GATEWAY_URI.host, GATEWAY_URI.port)
  request.use_ssl = true
  request.verify_mode = OpenSSL::SSL::VERIFY_NONE
  request.start do |http|
    response = http.request(post)
    Response.new(response)
  end
end

#deliver!Response

Posts the parameters through #deliver, but raises a DeliveryFailure in case the request fails.

This happens if an HTTP error occurs, or the gateway didn’t accept the parameters.

Returns:

  • (Response)

    Upon success, a response object which encapsulates the result of the request.

Raises:

  • (DeliveryFailure)

    An exception which encapsulates this SMS instance and the Response object.



244
245
246
247
248
# File 'lib/mollie/sms.rb', line 244

def deliver!
  response = deliver
  raise Exceptions::DeliveryFailure.new(self, response) unless response.success?
  response
end

#inspectString

Returns A `inspect' string representation of this instance.

Returns:

  • (String)

    A `inspect' string representation of this instance.



208
209
210
# File 'lib/mollie/sms.rb', line 208

def inspect
  %{#<#{self.class.name} #{to_s}>}
end

#telephone_numberString

Returns The recipient’s telephone number.

Returns:

  • (String)

    The recipient’s telephone number.



168
169
170
# File 'lib/mollie/sms.rb', line 168

def telephone_number
  @params['recipients']
end

#telephone_number=(telephone_number) ⇒ String

Assigns the recipient’s telephone number.

Parameters:

  • telephone_number (String)

    The recipient’s telephone number.

Returns:

  • (String)

    The recipient’s telephone number.



176
177
178
# File 'lib/mollie/sms.rb', line 176

def telephone_number=(telephone_number)
  @params['recipients'] = telephone_number
end

#to_sString

Returns A string representation of this instance.

Returns:

  • (String)

    A string representation of this instance.



203
204
205
# File 'lib/mollie/sms.rb', line 203

def to_s
  %{from: <#{params['originator']}> to: <#{telephone_number}> body: "#{body}"}
end

#validate_params!nil

Checks if all required parameters are present and if the originator is of the right size.

Returns:

  • (nil)

Raises:

  • (ValidationError)

    If any of the validations fail.

See Also:



258
259
260
261
262
263
264
265
266
267
268
269
270
271
# File 'lib/mollie/sms.rb', line 258

def validate_params!
  params.slice(*REQUIRED_PARAMS).each do |key, value|
    raise Exceptions::ValidationError, "The required parameter `#{key}' is missing." if value.blank?
  end

  originator = params['originator']
  if originator =~ /^\d+$/
    if originator.size > 14
      raise Exceptions::ValidationError, "Originator may have a maximimun of 14 numerical characters."
    end
  elsif originator.size > 11
    raise Exceptions::ValidationError, "Originator may have a maximimun of 11 alphanumerical characters."
  end
end