Class: Clickatell::API

Inherits:
Object
  • Object
show all
Defined in:
lib/clickatell/api.rb,
lib/clickatell/api/error.rb,
lib/clickatell/api/command.rb,
lib/clickatell/api/message_status.rb,
lib/clickatell/api/command_executor.rb

Overview

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

Defined Under Namespace

Classes: Command, CommandExecutor, Error, FakeHttpResponse, MessageStatus

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.



47
48
49
 
# File 'lib/clickatell/api.rb', line 47

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

Class Attribute Details

.api_service_host ⇒ Object

Allow customizing URL



25
26
27
 
# File 'lib/clickatell/api.rb', line 25

def api_service_host
  @api_service_host
end

.ca_file ⇒ Object

Enable secure mode (SSL)



22
23
24
 
# File 'lib/clickatell/api.rb', line 22

def ca_file
  @ca_file
end

.ca_path ⇒ Object

Enable secure mode (SSL)



22
23
24
 
# File 'lib/clickatell/api.rb', line 22

def ca_path
  @ca_path
end

.debug_mode ⇒ Object

Set to true to enable debugging (off by default)



19
20
21
 
# File 'lib/clickatell/api.rb', line 19

def debug_mode
  @debug_mode
end

.proxy_host ⇒ Object

Set to your HTTP proxy details (off by default)



28
29
30
 
# File 'lib/clickatell/api.rb', line 28

def proxy_host
  @proxy_host
end

.proxy_password ⇒ Object

Set to your HTTP proxy details (off by default)



28
29
30
 
# File 'lib/clickatell/api.rb', line 28

def proxy_password
  @proxy_password
end

.proxy_port ⇒ Object

Set to your HTTP proxy details (off by default)



28
29
30
 
# File 'lib/clickatell/api.rb', line 28

def proxy_port
  @proxy_port
end

.proxy_username ⇒ Object

Set to your HTTP proxy details (off by default)



28
29
30
 
# File 'lib/clickatell/api.rb', line 28

def proxy_username
  @proxy_username
end

.secure_mode ⇒ Object

Enable secure mode (SSL)



22
23
24
 
# File 'lib/clickatell/api.rb', line 22

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)



33
34
35
 
# File 'lib/clickatell/api.rb', line 33

def test_mode
  @test_mode
end

Instance Attribute Details

#auth_options ⇒ Object

Returns the value of attribute auth_options.



5
6
7
 
# File 'lib/clickatell/api.rb', line 5

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.



11
12
13
14
15
16
 
# File 'lib/clickatell/api.rb', line 11

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.



124
125
126
127
 
# File 'lib/clickatell/api.rb', line 124

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.



54
55
56
57
58
59
60
61
 
# File 'lib/clickatell/api.rb', line 54

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_charge(message_id) ⇒ Object 



118
119
120
121
 
# File 'lib/clickatell/api.rb', line 118

def message_charge(message_id)
  response = execute_command('getmsgcharge', 'http', :apimsgid => message_id)
  parse_response(response)['charge'].to_f
end

#message_status(message_id) ⇒ Object

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



113
114
115
116
 
# File 'lib/clickatell/api.rb', line 113

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.



65
66
67
 
# File 'lib/clickatell/api.rb', line 65

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).

Messages over 160 characters are split into multiple messages automatically, and the :concat option will be set, overwriting any manual value of this option.

You normally wouldn’t need to set :concat manually and can rely on the automatica splitting behaviour.

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
:concat - number of concatenations allowed. I.E. how long is a message allowed to be.

Returns a new message ID if successful.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/clickatell/api.rb', line 86

def send_message(recipient, message_text, opts={})
  valid_options = opts.only(:from, :mo, :callback, :climsgid, :concat)
  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]
  if message_text.length > 160
    valid_options.merge!(:concat => (message_text.length.to_f / 160).ceil)
  end
  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 



102
103
104
105
106
107
108
109
 
# File 'lib/clickatell/api.rb', line 102

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 



129
130
131
 
# File 'lib/clickatell/api.rb', line 129

def sms_requests
  @sms_requests ||= []
end