Class: Hellio::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/hellio/client.rb

Overview

Hellio Messaging API v1 client. Authenticates with a Bearer token and exposes one method per endpoint. Every call returns the decoded JSON as a Hash with string keys (payloads are under "data"); non-2xx responses raise a typed Hellio::Error subclass.

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.helliomessaging.com/v1"
DEFAULT_TIMEOUT = 
30

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(token: nil, base_url: nil, timeout: nil, default_sender: nil, http: nil) ⇒ Client

token - API token (falls back to HELLIO_API_TOKEN). base_url - API base URL (falls back to HELLIO_BASE_URL, then default). timeout - request timeout in seconds (default 30). default_sender - Sender ID used by #sms (falls back to HELLIO_DEFAULT_SENDER). http - HTTP adapter; inject a fake in tests. Defaults to net/http.



25
26
27
28
29
30
31
 
# File 'lib/hellio/client.rb', line 25

def initialize(token: nil, base_url: nil, timeout: nil, default_sender: nil, http: nil)
  @token = token || ENV["HELLIO_API_TOKEN"]
  @base_url = (base_url || ENV["HELLIO_BASE_URL"] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
  @timeout = timeout || DEFAULT_TIMEOUT
  @default_sender = default_sender || ENV["HELLIO_DEFAULT_SENDER"]
  @http = http || NetHttpAdapter.new
end

Instance Attribute Details

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



18
19
20
 
# File 'lib/hellio/client.rb', line 18

def base_url
  @base_url
end

#default_sender ⇒ Object (readonly)

Returns the value of attribute default_sender.



18
19
20
 
# File 'lib/hellio/client.rb', line 18

def default_sender
  @default_sender
end

#timeout ⇒ Object (readonly)

Returns the value of attribute timeout.



18
19
20
 
# File 'lib/hellio/client.rb', line 18

def timeout
  @timeout
end

Instance Method Details

#balance ⇒ Object

Current account balance and available credit.



36
37
38
 
# File 'lib/hellio/client.rb', line 36

def balance
  get("balance")
end

#campaign(id) ⇒ Object

Summary for a single campaign.



64
65
66
 
# File 'lib/hellio/client.rb', line 64

def campaign(id)
  get("campaigns/#{id}")
end

#create_webhook(url, events: []) ⇒ Object

Register a webhook. Pass events to subscribe to specific event types.



159
160
161
162
163
164
 
# File 'lib/hellio/client.rb', line 159

def create_webhook(url, events: [])
  post("webhooks", compact(
    "url" => url,
    "events" => (events.nil? || events.empty? ? nil : events)
  ))
end

#delete_webhook(id) ⇒ Object

Delete a webhook by id.



167
168
169
 
# File 'lib/hellio/client.rb', line 167

def delete_webhook(id)
  delete("webhooks/#{id}")
end

#lookup(numbers) ⇒ Object

Submit numbers for HLR lookup. numbers accepts a string, comma list, or array.



130
131
132
 
# File 'lib/hellio/client.rb', line 130

def lookup(numbers)
  post("lookup", "numbers" => to_list(numbers))
end

#lookup_result(id) ⇒ Object

Result for a single lookup.



140
141
142
 
# File 'lib/hellio/client.rb', line 140

def lookup_result(id)
  get("lookup/#{id}")
end

#lookups ⇒ Object

List previously submitted lookups.



135
136
137
 
# File 'lib/hellio/client.rb', line 135

def lookups
  get("lookups")
end

#message(id) ⇒ Object

Delivery status for a single message.



59
60
61
 
# File 'lib/hellio/client.rb', line 59

def message(id)
  get("messages/#{id}")
end

#otp(to, sender: nil, channel: "sms", purpose: nil, length: nil, expiry: nil, gateway: nil) ⇒ Object

Send a one-time passcode. to is a phone number (sms/voice/whatsapp) or an email (email). sender (Sender ID) is required for sms/voice and must be approved on your account; it is ignored for whatsapp and email. Optional length (4-10 digits) and expiry (validity in minutes).



74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/hellio/client.rb', line 74

def otp(to, sender: nil, channel: "sms", purpose: nil, length: nil, expiry: nil, gateway: nil)
  destination_key = (channel == "email" ? "email" : "mobile_number")

  post("otp/send", compact(
    "channel" => channel,
    destination_key => to,
    "sender" => sender,
    "purpose" => purpose,
    "length" => length,
    "expiry" => expiry,
    "gateway" => gateway
  ))
end

#pricing(country = nil) ⇒ Object

Per-network SMS pricing. Pass an ISO-2 country code to narrow by country.



41
42
43
 
# File 'lib/hellio/client.rb', line 41

def pricing(country = nil)
  get("pricing", country.nil? ? {} : { "country" => country })
end

#sms(recipients, message, sender: nil, gateway: nil) ⇒ Object

Send an SMS. recipients may be a single string, a comma-separated string, or an array of numbers.



49
50
51
52
53
54
55
56
 
# File 'lib/hellio/client.rb', line 49

def sms(recipients, message, sender: nil, gateway: nil)
  post("sms/send", compact(
    "recipients" => to_list(recipients),
    "sender" => sender || default_sender,
    "message" => message,
    "gateway" => gateway
  ))
end

#verify(to, code, channel: "sms") ⇒ Object

Convenience wrapper: true when the code is valid, false otherwise. A 422 validation failure is treated as "not verified".



101
102
103
104
105
106
 
# File 'lib/hellio/client.rb', line 101

def verify(to, code, channel: "sms")
  result = verify_otp(to, code, channel: channel)
  truthy?(result.is_a?(Hash) ? result.dig("data", "verified") : nil)
rescue ValidationError
  false
end

#verify_email(emails) ⇒ Object

Verify one or more email addresses. emails accepts a string, comma list, or array.



147
148
149
 
# File 'lib/hellio/client.rb', line 147

def verify_email(emails)
  post("email/verify", "emails" => to_list(emails))
end

#verify_otp(to, code, channel: "sms") ⇒ Object

Verify a one-time passcode and return the full response.



89
90
91
92
93
94
95
96
97
 
# File 'lib/hellio/client.rb', line 89

def verify_otp(to, code, channel: "sms")
  destination_key = (channel == "email" ? "email" : "mobile_number")

  post("otp/verify", compact(
    "channel" => channel,
    destination_key => to,
    "code" => code
  ))
end

#voice(recipients, caller_id, text: nil, audio_url: nil, name: nil) ⇒ Object

Voice broadcast. Provide text (read with TTS) OR audio_url (fetched and played). recipients accepts the same shapes as #sms.



112
113
114
115
116
117
118
119
120
 
# File 'lib/hellio/client.rb', line 112

def voice(recipients, caller_id, text: nil, audio_url: nil, name: nil)
  post("voice/send", compact(
    "recipients" => to_list(recipients),
    "caller_id" => caller_id,
    "text" => text,
    "audio_url" => audio_url,
    "name" => name
  ))
end

#voice_status(id) ⇒ Object

Status for a single voice broadcast.



123
124
125
 
# File 'lib/hellio/client.rb', line 123

def voice_status(id)
  get("voice/#{id}")
end

#webhooks ⇒ Object

List registered webhooks.



154
155
156
 
# File 'lib/hellio/client.rb', line 154

def webhooks
  get("webhooks")
end