Class: SignalApi::List

Inherits:
SignalHttpApi show all
Includes:
ApiMock
Defined in:
lib/signal_api/list.rb,
lib/signal_api/mocks/list.rb

Overview

Manage subscriptions to, and send messages to subscribers of a List.

Instance Method Summary collapse

Methods included from ApiMock

included

Constructor Details

#initialize(list_id) ⇒ List

Create a new List object

Parameters:

  • list_id (Fixnum) —

    The ID of the list in the Signal platform

Raises:



25
26
27
28
 
# File 'lib/signal_api/list.rb', line 25

def initialize(list_id)
  @list_id = list_id
  raise InvalidParameterException.new("list_id cannot be nil") if @list_id.nil?
end

Instance Method Details

#create_subscription(subscription_type, contact, options = {}) ⇒ Bool

Create a new subscription to the list.

Parameters:

  • subscription_type (SubscriptionType) —

    The type of subscription to create

  • contact (Contact) —

    The contact to create the subscription for. The contact must contain a valid mobile phone number for SMS subscriptions, and a valid email address for EMAIL subscriptions. Any other attributes stored with the contact will also be stored on the Signal platform.

  • options (Hash) (defaults to: {}) —

    Optional The options used to create the subscription

Options Hash (options):

  • :source_keyword (String) —

    The source keyword to use when creating the subscription (for SMS subscriptions)

Returns:

  • (Bool) —

    True if a subscription was created, false if the subscription already existed.



41
42
43
44
45
46
47
48
49
50
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
79
80
81
82
 
# File 'lib/signal_api/list.rb', line 41

def create_subscription(subscription_type, contact, options={})
  validate_create_subscription_request(subscription_type, contact, options)

  builder = Builder::XmlMarkup.new
  body = builder.subscription do |subscription|
    subscription.tag!('subscription-type', subscription_type)
    subscription.tag!('source-keyword', options[:source_keyword]) if options[:source_keyword]
    subscription.user do |user|
      contact.attributes.each do |attribute_name, attribute_value|
        user.__send__(attribute_name, attribute_value)
      end
    end
  end

  SignalApi.logger.info "Attempting to create a subscription to list #{@list_id}"
  SignalApi.logger.debug "Subscription data: #{body}"
  self.class.with_retries do
    response = self.class.post("/api/subscription_campaigns/#{@list_id}/subscriptions.xml",
                               :body => body,
                               :format => :xml,
                               :headers => self.class.common_headers)

    if response.code == 200
      return true
    else
      if response.body.include?("Could not find the carrier for mobile phone")
        raise SignalApi::InvalidMobilePhoneException.new(response.body)
      elsif response.body.include?("already signed up")
        SignalApi.logger.info response.body
        return false
      elsif response.body.include?("Subscriber cannot be re-added since they have unsubscribed within the past")
        SignalApi.logger.info response.body
        return false
      elsif response.body.include?("User already subscribed, resending confirmation message")
        SignalApi.logger.info response.body
        return false
      else
        self.class.handle_api_failure(response)
      end
    end
  end
end

#create_subscription_additional_info ⇒ Object 



9
10
11
 
# File 'lib/signal_api/mocks/list.rb', line 9

def create_subscription_additional_info
  { :list_id => @list_id }
end

#destroy_subscription(subscription_type, contact) ⇒ Bool

Destroy a subscription which exists in this list.

Parameters:

  • subscription_type (SubscriptionType) —

    The type of subscription to destroy

  • contact (Contact) —

    The contact to destroy the subscription for. The contact must contain a valid mobile phone number for SMS subscriptions, and a valid email address for EMAIL subscriptions.

Returns:

  • (Bool) —

    True if a subscription was desctroyed, false if the subscription did not exist.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/signal_api/list.rb', line 92

def destroy_subscription(subscription_type, contact)
  validate_destroy_subscription_request(subscription_type, contact)

  SignalApi.logger.info "Attempting to destroy a subscription to list #{@list_id}"
  SignalApi.logger.debug "Contact data: #{contact.inspect}"
  
  if subscription_type == SubscriptionType::SMS
    contact_id = contact.mobile_phone
  else
    contact_id = contact.email_address
  end

  self.class.with_retries do
    response = self.class.delete("/api/subscription_campaigns/#{@list_id}/subscriptions/#{contact_id}.xml",
                                 :headers => self.class.common_headers)

    if response.code == 200
      return true
    else
      if response.body.include?("is not subscribed to campaign")
        SignalApi.logger.info response.body
        return false
      elsif response.body.include?("Invalid user ID")
        SignalApi.logger.info response.body
        return false
      else
        self.class.handle_api_failure(response)
      end
    end
  end
end

#destroy_subscription_additional_info ⇒ Object 



15
16
17
 
# File 'lib/signal_api/mocks/list.rb', line 15

def destroy_subscription_additional_info
  { :list_id => @list_id }
end

#send_message(description, text, options = {}) ⇒ Fixnum

Sends an SMS message to the subscribers of the subscription list.

Parameters:

  • description (String) —

    A description of the message.

  • text (String) —

    The message to send. Must not be greater than 160 characters.

  • options (Hash) (defaults to: {}) —

    Optional The options used when sending the message.

Options Hash (options):

  • :send_at (Time) —

    The date and time to send the message. The message will be sent immediately if not provided.

  • :segment_id (Fixnum) —

    The id of the segment to send the message to. If not specified, the message will be sent to all subscribers in the list.

  • :tags (Array<Fixnum>) —

    An array of tag ids to tag the scheduled message with.

  • :carrier_overrides (Array<CarrierOverrideMessage>) —

    An alternate text message to send to users on a particular carrier.

Returns:

  • (Fixnum) —

    The ID of the scheduled message on the Signal platform.

Raises:



137
138
139
140
141
142
143
144
145
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
182
 
# File 'lib/signal_api/list.rb', line 137

def send_message(description, text, options={})
  raise InvalidParameterException.new("A description must be provided") if description.blank?
  raise InvalidParameterException.new("A text message must be provided") if text.blank?
  raise InvalidParameterException.new("The text message must not be greater than 160 characters") if text.size > 160

  builder = Builder::XmlMarkup.new
  body = builder.message do |message|
    message.description(description)
    message.text(text)
    message.send_at(options[:send_at].strftime("%Y-%m-%d %H:%M:%S")) if options[:send_at]
    message.segment_id(options[:segment_id]) if options[:segment_id]

    if options[:tags]
      message.tags(:type => :array) do |tags|
        options[:tags].each { |tag_id| tags.tag(tag_id) }
      end
    end

    if options[:carrier_overrides]
      message.carrier_overrides(:type => :array) do |carrier_overrides|
        options[:carrier_overrides].each do |carrier_override_message|
          carrier_overrides.carrier_override do |carrier_override|
            carrier_override.carrier_id(carrier_override_message.carrier_id)
            carrier_override.text(carrier_override_message.text)
          end
        end
      end
    end
  end

  SignalApi.logger.info "Attempting to send a message to list #{@list_id}"
  SignalApi.logger.debug "Message data: #{body}"
  self.class.with_retries do
    response = self.class.post("/api/subscription_campaigns/#{@list_id}/send_message.xml",
                               :body => body,
                               :format => :xml,
                               :headers => self.class.common_headers)

    if response.code == 200
      data = response.parsed_response['scheduled_message']
      data['id']
    else
      self.class.handle_api_failure(response)
    end
  end
end