Class: Messagemedia::SOAP::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/messagemedia/soap/client.rb

Overview

This class is a light-weight wrapper around the MessageMedia SOAP API.

Instance Method Summary collapse

Constructor Details

#initialize(username, password, debug = false) ⇒ Client

Initialize the SOAP client.

Your MessageMedia username and password must be provided.

These credentials will not be authenticated until an actual request is made using one of the other methods available in this class.



23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/messagemedia/soap/client.rb', line 23

def initialize(username, password, debug = false)
  # Store the credentials for use with other methods
  @credentials = {
      :'api:userId' => username,
      :'api:password' => password
  }

  # Create a new Savon-based SOAP client
  @client = Savon.client(wsdl: SOAP_ENDPOINT, log: debug)

end

Instance Method Details

#check_replies(max_replies = nil) ⇒ Object

Check for, and return, the replies that are available.

A maximum number of replies (max_replies) may be specified, in order to limit the size of the response.

Note that the same replies will be returned by subsequent calls to this method, unless you also call confirm_replies to confirm that the replies have been received.



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/messagemedia/soap/client.rb', line 136

def check_replies(max_replies = nil)
  body = {
      :'api:authentication' => @credentials,
      :'api:requestBody' => {}
  }

  unless max_replies.nil?
    body[:'api:requestBody'][:'api:maxReplies'] = max_replies
  end

  response = @client.call(:check_replies, message: body).body[:check_replies_response][:result]
  if response[:replies]
    response[:replies] = response[:replies][:reply]
  else
    response[:replies] = []
  end

  response
end

#check_reports(max_reports = nil) ⇒ Object

Check for, and return, the Delivery Reports that are available.

A maximum number of reports (max_reports) may be specified, in order to limit the size of the response.

Note that the same delivery reports will be returned by subsequent calls to this method, unless you also call confirm_replies to confirm that the replies have been received.

Note also that Delivery Reports are often called Delivery Receipts, and the terms can be used interchangeably.



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/messagemedia/soap/client.rb', line 193

def check_reports(max_reports = nil)
  body = {
      :'api:authentication' => @credentials,
      :'api:requestBody' => {}
  }

  unless max_reports.nil?
    body[:'api:requestBody'][:'api:maxReports'] = max_reports
  end

  response = @client.call(:check_reports, message: body).body[:check_reports_response][:result]
  if response[:reports]
    response[:reports] = response[:reports][:report]
  else
    response[:reports] = []
  end

  response
end

#confirm_replies(reply_ids) ⇒ Object

Confirm that replies have been received.

An array of reply IDs (reply_ids) must be provided. Each of the IDs in this array should correspond to a reply that was received using the check_replies method.



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/messagemedia/soap/client.rb', line 163

def confirm_replies(reply_ids)
  body = {
      :'api:authentication' => @credentials,
      :'api:requestBody' => {
          :'api:replies' => {
              :'api:reply' => reply_ids.map do |reply_id|
                {:'@receiptId' => reply_id}
              end
          }
      }
  }

  response = @client.call(:confirm_replies, message: body)

  response.body[:confirm_replies_response][:result][:'@confirmed']
end

#confirm_reports(report_ids) ⇒ Object

Confirm that Delivery Reports have been received.

An array of delivery report IDs (report_ids) must be provided. Each of the IDs in this array should correspond to a Delivery Report that was received using the check_reports method.



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/messagemedia/soap/client.rb', line 220

def confirm_reports(report_ids)
  body = {
      :'api:authentication' => @credentials,
      :'api:requestBody' => {
          :'api:reports' => {
              :'api:report' => report_ids.map do |report_id|
                {:'@receiptId' => report_id}
              end
          }
      }
  }

  response = @client.call(:confirm_reports, message: body)

  response.body[:confirm_reports_response][:result][:'@confirmed']
end

#get_user_info ⇒ Object

Retrieve the credit info and other metadata that is available for a MessageMedia account.



116
117
118
119
120
121
122
123
124
 
# File 'lib/messagemedia/soap/client.rb', line 116

def 
  body = {
      :'api:authentication' => @credentials
  }

  response = @client.call(:check_user, message: body)

  response.body[:check_user_response][:result]
end

#send_message(destination_number, content, message_id, source_number = nil) ⇒ Object

Send a message to a recipient.

A destination number (destination_number) is required.

The source number (source_number), message content (content), and message identifier (messageId) are optional. Optional arguments may be omitted by providing nil as an argument.

If a message identifier is provided, then it will be returned as part of any replies or delivery reports produced as a result of this message.

If a source number is not provided, the message will be sent using the MessageMedia rotary.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/messagemedia/soap/client.rb', line 51

def send_message(destination_number, content, message_id, source_number = nil)

  # Construct a Message object to represent the message
  message = Message.new
  message.content = content
  message.delivery_report = true
  message.format = FORMAT_SMS
  message.validity_period = 1
  message.origin = source_number
  message.add_recipient(message_id, destination_number)

  messages = {
      :'@sendMode' => "normal",
      :'api:message' => [message.to_api_hash]
  }

  body = {
      :'api:authentication' => @credentials,
      :'api:requestBody' => {:'api:messages' => messages}
  }

  # Make a request to the MessageMedia SOAP service. Note that the
  # message parameter below refers to the body of the SOAP request,
  # not the message object that we constructed above.
  response = @client.call(:send_messages, message: body)

  response.body[:send_messages_response][:result]
end

#send_messages(messages) ⇒ Object

Send multiple messages using a single request.

An array of Message objects must be provided. Unlike the send_message method, this method requires the Message objects to be constructed manually.

Constructing an instance of Message is straight-forward:

message = Message.new
message.content = <message content>
message.delivery_report = <true|false>
message.format = <FORMAT_SMS|FORMAT_VOICE>
message.validity_period = 1
message.origin = <source_number>
message.add_recipient(<message ID>, <destination number>)



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/messagemedia/soap/client.rb', line 96

def send_messages(messages)
  messages = {
      :'@sendMode' => 'normal',
      :'api:message' => messages.map { |m| m.to_api_hash }
  }

  body = {
      :'api:authentication' => @credentials,
      :'api:requestBody' => {:'api:messages' => messages}
  }

  response = @client.call(:send_messages, message: body)

  response.body[:send_messages_response][:result]
end