Ruby SDK

Official Orbit Ruby SDK quickstart

Ruby SDK

The official Orbit Ruby SDK provides an idiomatic Ruby client for the Orbit API. Supports Ruby 3.1+ with automatic retries, structured errors, and a clean DSL.

Installation

Add to your Gemfile:

gem 'devotel'

Then run:

bundle install

Or install directly:

gem install devotel

Quick Start

require 'devotel'

orbit = Devotel::Orbit.new(api_key: 'dv_live_sk_your_key_here')

# Send an SMS
message = orbit.messages.send(
  channel: 'sms',
  to: '[phone]',
  body: 'Hello from Orbit!'
)

puts message["data"]["message_id"] # msg_abc123

Messaging

# Send WhatsApp template
wa_message = orbit.messages.send(
  channel: 'whatsapp',
  to: '[phone]',
  type: 'template',
  template: {
    name: 'order_confirmation',
    language: 'en',
    components: [
      {
        type: 'body',
        parameters: [{ type: 'text', text: 'ORD-12345' }]
      }
    ]
  }
)

# Send Email
email = orbit.messages.send(
  channel: 'email',
  to: '[e-mail]',
  from: '[e-mail]',
  subject: 'Welcome!',
  html: '<h1>Welcome to Acme</h1>'
)

Voice

# Make an outbound call
call = orbit.voice.create_call(
  to: '[phone]',
  from: '[phone]'
)

# Retrieve call details
call_details = orbit.voice.get_call(call["data"]["id"])

Verify

# Send OTP
verification = orbit.verify.send(
  to: '[phone]',
  channel: 'sms'
)

# Check OTP
result = orbit.verify.check(
  verification_id: verification["data"]["verification_id"],
  code: '482901'
)

puts result["data"]["status"] # "approved"

Webhooks

require 'devotel'

# Sinatra example
post '/webhooks/orbit' do
  signature = request.env['HTTP_X_DEVOTEL_SIGNATURE']
  payload = request.body.read

  unless Devotel::Webhook.verify(payload, signature, 'whsec_your_secret')
    halt 401, { error: 'Invalid signature' }.to_json
  end

  event = JSON.parse(payload)
  case event['type']
  when 'message.delivered'
    handle_delivery(event)
  when 'call.completed'
    handle_call_complete(event)
  end

  { received: true }.to_json
end

Rails Controller

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def orbit
    signature = request.headers['X-Devotel-Signature']
    payload = request.raw_post

    unless Devotel::Webhook.verify(payload, signature, ENV['DEVOTEL_WEBHOOK_SECRET'])
      return render json: { error: 'Invalid signature' }, status: :unauthorized
    end

    event = JSON.parse(payload)
    WebhookProcessorJob.perform_later(event)

    render json: { received: true }
  end
end

Error Handling

begin
  orbit.messages.send(channel: 'sms', to: 'invalid', body: 'Hi')
rescue Devotel::DevotelApiError => e
  puts e.code        # "INVALID_PHONE_NUMBER"
  puts e.status_code # 422
  puts e.message     # "The to field must be a valid E.164 phone number"
end

Configuration

orbit = Devotel::Orbit.new(
  api_key: 'dv_live_sk_your_key_here',
  base_url: 'https://orbit-api.devotel.io/api/v1'
)

Option	Type	Default	Description
api_key	String	—	Your Devotel API key (required)
base_url	String	https://orbit-api.devotel.io/api/v1	API base URL

Requirements

• Ruby 3.1 or later
• faraday (installed automatically)