Class: Clockwork::API

Inherits:

Object

• Object
• Clockwork::API

show all

Defined in:

lib/clockwork/api.rb

Overview

Constant Summary

SMS_URL =

URL of the SMS API send action

"api.clockworksms.com/xml/send"

CREDIT_URL =

URL of the SMS API check credit action

"api.clockworksms.com/xml/credit"

Instance Attribute Summary (collapse)

• - (string) api_key readonly

  API key provided in Clockwork::API#initialize.

• - (string) from

  The from address displayed on a phone when the SMS is received.

• - (symbol) invalid_char_action

  What to do with any invalid characters in the message content.

• - (boolean) long

  Set to true to enable long SMS.

• - (Clockwork::MessageCollection) messages

  Returns a Clockwork::MessageCollection containing all built SMS messages.

• - (symbol) messages_to_concat

  If Clockwork::API#long is set to true, this is the number of messages to concatenate (join together).

• - (string) password readonly deprecated Deprecated.

  Use api_key instead.

• - (boolean) truncate

  Set to true to trim the message content to the maximum length if it is too long.

• - (boolean) use_ssl

  Whether to use SSL when connecting to the API.

• - (string) username readonly deprecated Deprecated.

  Use api_key instead.

Instance Method Summary (collapse)

• - (Object) concat deprecated Deprecated.

  Use Clockwork::API#messages_to_concat instead. Support for Clockwork::API#concat will be removed in a future version of this wrapper.

• - (Object) concat=(val) deprecated Deprecated.

  Use Clockwork::API#messages_to_concat= instead. Support for Clockwork::API#concat= will be removed in a future version of this wrapper.

• - (integer) credit

  Check the remaining credit for this account.

• - (array) deliver_messages

  Deliver multiple messages created using Clockwork::API#messages.build.

• - (Object) get_credit deprecated Deprecated.

  Use Clockwork::API#credit. Support for Clockwork::API#get_credit will be removed in a future version of this wrapper.

• - (API) initialize(*args) constructor

  Clockwork::API is initialized with an API key, available from www.mediaburst.co.uk/api.

• - (hash) send_message(*args) deprecated Deprecated.

  Use Clockwork::SMS#deliver. Support for Clockwork::API#send_message will be removed in a future version of this wrapper. Besides, you get a MUCH more useful return value using #deliver: a Clockwork::SMS::Response.

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

# File 'lib/clockwork/api.rb', line 107

def initialize *args
  if args.size == 1 || ( args.size == 2 && args[1].kind_of?(Hash) ) 
    raise Clockwork::Error::InvalidAPIKey unless args[0][/^[A-Fa-f0-9]{40}$/]
    @api_key = args[0]
  elsif args.size == 2 || ( args.size == 3 && args[2].kind_of?(Hash) ) 
    raise ArgumentError, "You must pass both a username and password." if args[0].empty? || args[1].empty?
    @username = args[0]
    @password = args[1]
  else
    raise ArgumentError, "You must pass either an API key OR a username and password."
  end
  
  args.last.each { |k, v| instance_variable_set "@#{k}", v } if args.last.kind_of?(Hash)
  
  @use_ssl = true if @use_ssl.nil?
  @concat = 3 if @concat.nil? && @long
  @messages ||= Clockwork::MessageCollection.new( :api => self )
end

18
19
20

# File 'lib/clockwork/api.rb', line 18

def api_key
  @api_key
end

24
25
26

# File 'lib/clockwork/api.rb', line 24

def from
  @from
end

30
31
32

# File 'lib/clockwork/api.rb', line 30

def invalid_char_action
  @invalid_char_action
end

36
37
38

# File 'lib/clockwork/api.rb', line 36

def long
  @long
end

41
42
43

# File 'lib/clockwork/api.rb', line 41

def messages
  @messages
end

47
48
49

# File 'lib/clockwork/api.rb', line 47

def messages_to_concat
  @messages_to_concat
end

52
53
54

# File 'lib/clockwork/api.rb', line 52

def password
  @password
end

58
59
60

# File 'lib/clockwork/api.rb', line 58

def truncate
  @truncate
end

63
64
65

# File 'lib/clockwork/api.rb', line 63

def use_ssl
  @use_ssl
end

68
69
70

# File 'lib/clockwork/api.rb', line 68

def username
  @username
end

72
73
74

# File 'lib/clockwork/api.rb', line 72

def concat
  messages_to_concat
end

78
79
80

# File 'lib/clockwork/api.rb', line 78

def concat= val
  messages_to_concat val
end

129
130
131
132
133

# File 'lib/clockwork/api.rb', line 129

def credit
  xml = Clockwork::XML::Credit.build( self )
  response = Clockwork::HTTP.post( Clockwork::API::CREDIT_URL, xml, @use_ssl )
  credit = Clockwork::XML::Credit.parse( response )
end

185
186
187
188
189

# File 'lib/clockwork/api.rb', line 185

def deliver_messages
  xml = Clockwork::XML::SMS.build_multiple( self.messages )
  http_response = Clockwork::HTTP.post( Clockwork::API::SMS_URL, xml, @use_ssl )
  responses = Clockwork::XML::SMS.parse_multiple( self.messages, http_response )
end

84
85
86

# File 'lib/clockwork/api.rb', line 84

def get_credit
  credit
end

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

# File 'lib/clockwork/api.rb', line 146

def send_message *args
  result = {}
  
  options = {}
  options = args[2] if args[2].kind_of?(Hash)
  
  # TODO: Make this do a transactional send if we're sending multiple messages
  if args[0].kind_of?(Array)
    args[0].each do |number|        
      sms = self.messages.build( options )
      sms.to = number
      sms.content = args[1]
    end
    responses = self.deliver_messages
    responses.each do |response|
      if response.success
        result["#{response.message.to}"] = true
      else
        result["#{response.message.to}"] = response.error_code
      end
    end
    
  elsif args[0].kind_of?(String)        
    sms = self.messages.build( options )
    sms.to = args[0]
    sms.content = args[1]        
    response = sms.deliver
    if response.success
      result["#{sms.to}"] = true
    else
      result["#{sms.to}"] = response.error_code
    end
  end
  
  result      
end