Ruby SDK Reference

gem "whatsrb_cloud"

bundle install

gem install whatsrb_cloud

WhatsrbCloud.configure do |c|
  c.api_key  = "wrb_live_xxx"
  c.base_url = "https://api.whatsrb.com"  # default
  c.timeout  = 30                          # seconds
end

client = WhatsrbCloud::Client.new

client = WhatsrbCloud::Client.new(
  api_key:  "wrb_live_xxx",
  base_url: "https://api.whatsrb.com",
  timeout:  10
)

# config/initializers/whatsrb_cloud.rb
WhatsrbCloud.configure do |c|
  c.api_key = Rails.application.credentials.whatsrb_cloud_api_key
end

session = client.sessions.create(name: "Support Bot")
session.id      # => "sess_abc123"
session.status  # => "connecting"

list = client.sessions.list
list.data   # => [Session, Session, ...]
list.meta   # => { "total" => 3, "plan_limit" => 5 }

session = client.sessions.retrieve("sess_abc123")
session.name          # => "Support Bot"
session.status        # => "connected"
session.connected?    # => true
session.phone_number  # => "+33612345678"

client.sessions.delete("sess_abc123")  # => true

session = client.sessions.create(name: "My Bot")

session.wait_for_qr(timeout: 60, interval: 2) do |qr_data|
  # qr_data is a base64-encoded PNG
  puts "Scan this QR code!"

  # Save to file
  File.write("qr.png", Base64.decode64(qr_data))

  # Or display in terminal (with catimg, kitty, etc.)
end

puts "Connected as #{session.phone_number}"

session = client.sessions.create(name: "My Bot")

loop do
  session.reload
  break if session.connected?

  if session.status == "qr_pending" && session.qr_code
    puts "QR ready — scan it!"
  end

  sleep 2
end

# Via session object
msg = session.send_message(to: "+33612345678", text: "Hello!")
msg.id      # => "msg_xyz"
msg.status  # => "queued"

# Via client
msg = client.messages("sess_abc").create(
  to: "+33612345678",
  text: "Hello!"
)

# Image
session.send_image(to: "+33612345678", url: "https://example.com/photo.jpg")

# Document
session.send_document(to: "+33612345678", url: "https://example.com/invoice.pdf")

# Video
session.send_video(to: "+33612345678", url: "https://example.com/clip.mp4")

# Audio
session.send_audio(to: "+33612345678", url: "https://example.com/voice.ogg")

# Location
session.send_location(
  to: "+33612345678",
  latitude: 48.8566,
  longitude: 2.3522
)

# Contact card
session.send_contact(
  to: "+33612345678",
  name: "John Doe",
  phone: "+33698765432"
)

messages = client.messages("sess_abc").list
messages.data.each do |msg|
  puts "#{msg.message_type}: #{msg.content} (#{msg.status})"
end

msg = client.messages("sess_abc").retrieve("msg_xyz")
msg.status        # => "delivered"
msg.sent_at       # => 2026-02-26 12:00:00 +0000
msg.delivered_at  # => 2026-02-26 12:00:03 +0000

wh = client.webhooks.create(
  url: "https://yourapp.com/webhooks/whatsrb",
  events: ["message.received", "session.connected"]
)
wh.id      # => "wh_abc"
wh.secret  # => "whsec_..." (only returned on create — save it!)

client.webhooks.list.data.each do |wh|
  puts "#{wh.url} — #{wh.events.join(', ')}"
end

client.webhooks.update("wh_abc",
  events: ["message.received", "message.delivered", "session.disconnected"]
)

client.webhooks.delete("wh_abc")  # => true

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    payload   = request.body.read
    signature = request.headers["X-Webhook-Signature"]

    unless WhatsrbCloud::WebhookSignature.verify?(
      payload:   payload,
      secret:    ENV["WHATSRB_WEBHOOK_SECRET"],
      signature: signature
    )
      head :unauthorized
      return
    end

    event = JSON.parse(payload)

    case event["type"]
    when "message.received"
      handle_incoming(event["data"])
    when "session.disconnected"
      handle_disconnect(event["data"])
    end

    head :ok
  end
end

usage = client.usage
usage["messages_sent"]    # => 150
usage["sessions_active"]  # => 3
usage["plan"]             # => "pro"
usage["plan_limit"]       # => 2_000

begin
  session.send_message(to: "+33612345678", text: "Hello!")
rescue WhatsrbCloud::AuthenticationError
  # 401 — Invalid or missing API key
rescue WhatsrbCloud::ForbiddenError
  # 403 — Plan limit reached
rescue WhatsrbCloud::NotFoundError
  # 404 — Session or message not found
rescue WhatsrbCloud::ValidationError
  # 422 — Invalid parameters
rescue WhatsrbCloud::ConflictError
  # 409 — Session not connected
rescue WhatsrbCloud::RateLimitError => e
  # 429 — Too many requests
  sleep(e.retry_after || 1)
  retry
rescue WhatsrbCloud::ServerError
  # 5xx — Server error, retry later
rescue WhatsrbCloud::Error => e
  # Catch-all
  puts "#{e.message} (HTTP #{e.status})"
end

# config/initializers/whatsrb_cloud.rb
WhatsrbCloud.configure do |c|
  c.api_key = Rails.application.credentials.whatsrb_cloud_api_key
end

# app/services/whatsapp_sender.rb
class WhatsappSender
  def initialize(session_id: nil)
    @client = WhatsrbCloud::Client.new
    @session_id = session_id || default_session_id
  end

  def send_text(to:, text:)
    session.send_message(to: to, text: text)
  end

  def send_image(to:, url:)
    session.send_image(to: to, url: url)
  end

  private

  def session
    @session ||= @client.sessions.retrieve(@session_id)
  end

  def default_session_id
    # Cache the connected session ID
    Rails.cache.fetch("whatsrb:default_session", expires_in: 5.minutes) do
      @client.sessions.list.data.find(&:connected?)&.id
    end
  end
end

# In a controller
class OrdersController < ApplicationController
  def confirm
    @order = Order.find(params[:id])
    @order.confirm!

    WhatsappSender.new.send_text(
      to: @order.customer_phone,
      text: "Your order ##{@order.number} is confirmed!"
    )

    redirect_to @order, notice: "Order confirmed & customer notified."
  end
end

# In a background job
class OrderNotificationJob < ApplicationJob
  def perform(order_id)
    order = Order.find(order_id)

    WhatsappSender.new.send_text(
      to: order.customer_phone,
      text: "Your order ##{order.number} has been shipped!"
    )
  end
end

# config/routes.rb
post "webhooks/whatsrb", to: "whatsrb_webhooks#create"

# app/controllers/whatsrb_webhooks_controller.rb
class WhatsrbWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    payload   = request.body.read
    signature = request.headers["X-Webhook-Signature"]

    unless WhatsrbCloud::WebhookSignature.verify?(
      payload:   payload,
      secret:    Rails.application.credentials.whatsrb_webhook_secret,
      signature: signature
    )
      head :unauthorized and return
    end

    event = JSON.parse(payload)

    case event["type"]
    when "message.received"
      handle_incoming(event["data"])
    when "session.disconnected"
      notify_admin("WhatsApp session disconnected!")
    end

    head :ok
  end

  private

  def handle_incoming(data)
    IncomingMessage.create!(
      from:    data["from"],
      body:    data["content"],
      received_at: Time.current
    )
  end

  def notify_admin(message)
    AdminMailer.alert(message).deliver_later
  end
end

# lib/tasks/whatsapp.rake
namespace :whatsapp do
  desc "Setup a new WhatsApp session"
  task setup: :environment do
    client  = WhatsrbCloud::Client.new
    session = client.sessions.create(name: "Production Bot")

    puts "Session created: #{session.id}"
    puts "Waiting for QR code..."

    session.wait_for_qr(timeout: 120) do |qr_data|
      File.write("tmp/qr.png", Base64.decode64(qr_data))
      puts "QR saved to tmp/qr.png — scan it with WhatsApp!"
    end

    puts "Connected as #{session.phone_number}"
  end
end