Class: Clockwork::API

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

Overview

You must create an instance of Clockwork::API to begin using the API.

Author:

  • James Inman <james@mediaburst.co.uk>

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"
BALANCE_URL =

URL of the SMS API check balance action

"api.clockworksms.com/xml/balance"

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (API) initalize(api_key) - (API) initalize(username, password)

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

Overloads:

  • - (API) initalize(api_key)

    Parameters:

    • api_key (string)

      API key, 40-character hexadecimal string

    • options (hash)

      Optional hash of attributes on API

  • - (API) initalize(username, password)
    Deprecated.

    Use an API key instead. Support for usernames and passwords will be removed in a future version of this wrapper.

    Parameters:

    • username (string)

      Your API username

    • password (string)

      Your API password

    • options (hash)

      Optional hash of attributes on API

Raises:

  • ArgumentError - if more than 3 parameters are passed

  • Clockwork::Error::InvalidAPIKey - if API key is invalid



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
# File 'lib/clockwork/api.rb', line 97

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

Instance Attribute Details

- (string) api_key (readonly)

API key provided in Clockwork::API#initialize.

Returns:

  • (string)


20
21
22
# File 'lib/clockwork/api.rb', line 20

def api_key
  @api_key
end

- (symbol) concat

Note:

Defaults to 3 if not set and Clockwork::API#long is set to true.

This is the number of messages to concatenate (join together).

Returns:

  • (symbol)

    One of error, :replace, :remove

Raises:

  • ArgumentError - if a value less than 2 or more than 3 is passed



26
27
28
# File 'lib/clockwork/api.rb', line 26

def concat
  @concat
end

- (string) from

Note:

This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.

The from address displayed on a phone when the SMS is received. This can be either a 12 digit number or 11 characters long.

Returns:

  • (string)


32
33
34
# File 'lib/clockwork/api.rb', line 32

def from
  @from
end

- (symbol) invalid_char_action

Note:

This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.

What to do with any invalid characters in the message content. :error will raise a Clockwork::InvalidCharacterException, :replace will replace a small number of common invalid characters, such as the smart quotes used by Microsoft Office with a similar match, :remove will remove invalid characters.

Returns:

  • (symbol)

    One of error, :replace, :remove

Raises:

  • ArgumentError - if value is not one of :error, :replace, :remove



38
39
40
# File 'lib/clockwork/api.rb', line 38

def invalid_char_action
  @invalid_char_action
end

- (boolean) long

Note:

This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.

Set to true to enable long SMS. A standard text can contain 160 characters, a long SMS supports up to 459. Each recipient will cost up to 3 message credits.

Returns:

  • (boolean)


44
45
46
# File 'lib/clockwork/api.rb', line 44

def long
  @long
end

- (Clockwork::MessageCollection) messages

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



49
50
51
# File 'lib/clockwork/api.rb', line 49

def messages
  @messages
end

- (string) password (readonly)

Deprecated.

Use api_key instead.

Password provided in Clockwork::API#initialize.

Returns:

  • (string)


54
55
56
# File 'lib/clockwork/api.rb', line 54

def password
  @password
end

- (boolean) truncate

Note:

This can be overriden for specific Clockwork::SMS objects; if it is not set your account default will be used.

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

Returns:

  • (boolean)


60
61
62
# File 'lib/clockwork/api.rb', line 60

def truncate
  @truncate
end

- (boolean) use_ssl

Whether to use SSL when connecting to the API. Defaults to true

Returns:

  • (boolean)


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

def use_ssl
  @use_ssl
end

- (string) username (readonly)

Deprecated.

Use api_key instead.

Username provided in Clockwork::API#initialize.

Returns:

  • (string)


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

def username
  @username
end

Instance Method Details

- (integer) balance

Check the remaining credit for this account.

Returns:

  • (integer)

    Number of messages remaining

Raises:

  • Clockwork::Error::Authentication - if API login details are incorrect



128
129
130
131
132
# File 'lib/clockwork/api.rb', line 128

def balance
  xml = Clockwork::XML::Balance.build( self )
  response = Clockwork::HTTP.post( Clockwork::API::BALANCE_URL, xml, @use_ssl )
  balance = Clockwork::XML::Balance.parse( response )
end

- (integer) credit

Check the remaining credit for this account.

Returns:

  • (integer)

    Number of messages remaining

Raises:

  • Clockwork::Error::Authentication - if API login details are incorrect



119
120
121
122
123
# File 'lib/clockwork/api.rb', line 119

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

- (array) deliver

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

Returns:

  • (array)

    Array of Clockwork::SMS::Response objects for messages.



136
137
138
139
140
# File 'lib/clockwork/api.rb', line 136

def deliver
  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

- (Object) get_credit

Deprecated.

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

Alias for Clockwork::API#credit to preserve backwards compatibility with original Mediaburst API.



74
75
76
# File 'lib/clockwork/api.rb', line 74

def get_credit
  credit
end