Class: Clickatell::API

Inherits:
Object
  • Object
show all
Defined in:
lib/exetel/api.rb

Overview

This module provides the core implementation of the Clickatell HTTP service.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(auth_options = {}) ⇒ API

Creates a new API instance using the specified auth options. auth_options is a hash containing either a :session_id or :username, :password and :api_key.

Some API calls (authenticate, ping etc.) do not require any auth_options. auth_options can be updated using the accessor methods.



93
94
95
 
# File 'lib/exetel/api.rb', line 93

def initialize(auth_options={})
  @auth_options = auth_options
end

Class Attribute Details

.api_service_host ⇒ Object

Allow customizing URL



76
77
78
 
# File 'lib/exetel/api.rb', line 76

def api_service_host
  @api_service_host
end

.debug_mode ⇒ Object

Set to true to enable debugging (off by default)



70
71
72
 
# File 'lib/exetel/api.rb', line 70

def debug_mode
  @debug_mode
end

.secure_mode ⇒ Object

Enable secure mode (SSL)



73
74
75
 
# File 'lib/exetel/api.rb', line 73

def secure_mode
  @secure_mode
end

.test_mode ⇒ Object

Set to true to test message sending; this will not actually send messages but will collect sent messages in a testable collection. (off by default)



81
82
83
 
# File 'lib/exetel/api.rb', line 81

def test_mode
  @test_mode
end

Instance Attribute Details

#auth_options ⇒ Object

Returns the value of attribute auth_options.



56
57
58
 
# File 'lib/exetel/api.rb', line 56

def auth_options
  @auth_options
end

Class Method Details

.authenticate(api_id, username, password) ⇒ Object

Authenticates using the given credentials and returns an API instance with the authentication options set to use the resulting session_id.



62
63
64
65
66
67
 
# File 'lib/exetel/api.rb', line 62

def authenticate(api_id, username, password)
  api = self.new
  session_id = api.authenticate(api_id, username, password)
  api.auth_options = { :session_id => session_id }
  api
end

Instance Method Details

#account_balance ⇒ Object

Returns the number of credits remaining as a float.



155
156
157
158
 
# File 'lib/exetel/api.rb', line 155

def 
  response = execute_command('getbalance', 'http')
  parse_response(response)['Credit'].to_f
end

#authenticate(api_id, username, password) ⇒ Object

Authenticates using the specified credentials. Returns a session_id if successful which can be used in subsequent API calls.



100
101
102
103
104
105
106
107
 
# File 'lib/exetel/api.rb', line 100

def authenticate(api_id, username, password)
  response = execute_command('auth', 'http',
    :api_id => api_id,
    :user => username,
    :password => password
  )
  parse_response(response)['OK']
end

#message_status(message_id) ⇒ Object

Returns the status of a message. Use message ID returned from original send_message call.



149
150
151
152
 
# File 'lib/exetel/api.rb', line 149

def message_status(message_id)
  response = execute_command('querymsg', 'http', :apimsgid => message_id)
  parse_response(response)['Status']
end

#ping(session_id) ⇒ Object

Pings the service with the specified session_id to keep the session alive.



111
112
113
 
# File 'lib/exetel/api.rb', line 111

def ping(session_id)
  execute_command('ping', 'http', :session_id => session_id)
end

#send_message(recipient, message_text, opts = {}) ⇒ Object

Sends a message message_text to recipient. Recipient number should have an international dialing prefix and no leading zeros (unless you have set a default prefix in your clickatell account centre).

Additional options: :from - the from number/name :set_mobile_originated - mobile originated flag :client_message_id - user specified message id that can be used in place of Clickatell issued API message ID for querying message Returns a new message ID if successful.



125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/exetel/api.rb', line 125

def send_message(recipient, message_text, opts={})
  valid_options = opts.only(:from, :mo, :callback, :climsgid)
  valid_options.merge!(:req_feat => '48') if valid_options[:from]
  valid_options.merge!(:mo => '1') if opts[:set_mobile_originated]
  valid_options.merge!(:climsgid => opts[:client_message_id]) if opts[:client_message_id]
  recipient = recipient.join(",")if recipient.is_a?(Array)
  response = execute_command('sendmsg', 'http',
    {:to => recipient, :text => message_text}.merge(valid_options)
  )
  response = parse_response(response)
  response.is_a?(Array) ? response.map { |r| r['ID'] } : response['ID']
end

#send_wap_push(recipient, media_url, notification_text = '', opts = {}) ⇒ Object 



138
139
140
141
142
143
144
145
 
# File 'lib/exetel/api.rb', line 138

def send_wap_push(recipient, media_url, notification_text='', opts={})
  valid_options = opts.only(:from)
  valid_options.merge!(:req_feat => '48') if valid_options[:from]
  response = execute_command('si_push', 'mms',
    {:to => recipient, :si_url => media_url, :si_text => notification_text, :si_id => 'foo'}.merge(valid_options)
  )
  parse_response(response)['ID']
end

#sms_requests ⇒ Object 



160
161
162
 
# File 'lib/exetel/api.rb', line 160

def sms_requests
  @sms_requests ||= []
end