SMSTunnel for Ruby and Rails

bundle add smstunnel

require "smstunnel"

client = SMSTunnel::Client.new(api_key: ENV.fetch("SMSTUNNEL_API_KEY"))

result = client.send_sms("+14155550123", "Your order #1042 has shipped.")
result.message_id # keep it to look up the status later
result.queued?    # true when the phone was offline: the text waits and goes out when the phone is back

SMSTunnel.send_sms("+14155550123", "The backup finished.")

bundle add smstunnel
bin/rails generate smstunnel:install

bin/rails credentials:edit

smstunnel:
  api_key: sk_live_...
  device_id:        # optional: the phone that sends (Phones → copy its ID)

SMSTunnel.send_sms("+14155550123", "Hello from Rails")

# config/initializers/smstunnel.rb
SMSTunnel.configure do |config|
  config.api_key = Rails.application.credentials.dig(:smstunnel, :api_key).presence || ENV["SMSTUNNEL_API_KEY"]
  config.device_id = nil               # a phone ID, or nil to let SMSTunnel pick one of yours
  config.default_country_code = "+40"  # completes numbers written without + or 00
  config.timeout = 30                  # seconds to wait for an answer
  config.open_timeout = 10             # seconds to connect
end

class Order < ApplicationRecord
  after_update_commit :text_customer, if: -> { saved_change_to_status?(to: "shipped") }

  private

  def text_customer
    SMSTunnel::SendTextJob.perform_later(phone, "Your order ##{number} has shipped.")
  end
end

SMSTunnel::SendTextJob.perform_later("+14155550123", "Your table is ready.")
SMSTunnel::SendTextJob.perform_later(user.phone, "Your sign-in code is #{code}", sign_in_code: true)
SMSTunnel::SendTextJob.set(queue: :texts, wait: 1.hour).perform_later(phone, "Reminder: see you at 10:30.",
                                                                       device_id: "...", default_country_code: "+1")

class ShippingTextJob < ApplicationJob
  include SMSTunnel::JobRetries # retries 5xx, timeouts and 429; safe only because every send has a key

  def perform(order)
    SMSTunnel.send_sms(order.phone, "Your order ##{order.number} has shipped.",
                       idempotency_key: "order-#{order.id}-shipped")
  end
end

class OrderShippedNotifier < Noticed::Event
  deliver_by :smstunnel do |config|
    config.phone = -> { recipient.phone }                     # a String in international format
    config.message = -> { "Your order ##{params[:order].number} has shipped." }
    config.if = -> { recipient.phone.present? }               # skip recipients without a number
  end
end

OrderShippedNotifier.with(order: order).deliver(order.customer)

client = SMSTunnel::Client.new(
  api_key: ENV.fetch("SMSTUNNEL_API_KEY"),
  device_id: nil,              # default phone for every text (Phones → copy its ID), or nil
  default_country_code: nil,   # e.g. "+40"
  timeout: 30, open_timeout: 10
)

client.send_sign_in_code("+14155550123", "Your sign-in code is 482913")

status = client.message_status(result.message_id)
status.state         # "pending", "sent", "delivered", "failed" or "unconfirmed"
status.delivered?    # also pending?, sent?, failed?, unconfirmed?
status.final?        # true once it will not change any more
status.sent_at       # a Time (UTC), or nil
status.error_message # why it failed, or nil

client.phones.each { |phone| puts "#{phone.name}: #{phone.online? ? "online" : "offline"}" }
client.phones.find_by_id("...") # phone.id, phone.name, phone.online?, phone.last_seen_at

usage = client.usage
usage.plan      # e.g. "standard"
usage.usage     # {"smsClean" => 15, "smsBranded" => 0, "twoFaClean" => 4}
usage.remaining # {"smsClean" => 1985, "twoFaClean" => "unlimited"}

page = client.received_texts(limit: 20, since: 1.day.ago)
page.each { |text| puts "#{text.sender}: #{text.message}" } # text.received_at, text.device_name...
page.total  # all texts that match, on every page
page.more?  # ask for page: 2

begin
  SMSTunnel.send_sms(phone, "Your table is ready.", idempotency_key: "table-#{booking.id}")
rescue SMSTunnel::RateLimitError => e
  retry_later(wait: e.retry_after || 60)
rescue SMSTunnel::AuthenticationError, SMSTunnel::PermissionError => e
  Rails.logger.error("SMSTunnel key problem: #{e.message} (#{e.code})") # fix the key; don't retry
rescue SMSTunnel::Error => e
  Rails.logger.warn("The text did not go out: #{e.message}")
end

stub_request(:post, "https://smstunnel.io/api/v1/sms/send")
  .to_return(status: 200, headers: { "Content-Type" => "application/json" },
             body: { success: true, messageId: "test-1", data: { messageId: "test-1" } }.to_json)

assert_enqueued_with(job: SMSTunnel::SendTextJob, args: ["+14155550123", "Your table is ready."])