WebinarJam

A dependency-free Ruby client for the WebinarJam / EverWebinar API.

Covers every documented endpoint:

Method	Endpoint	Purpose
#webinars	POST /webinars	List all published webinars
#webinar(id)	POST /webinar	Details for one webinar (schedules, URLs, presenters)
#register(...)	POST /register	Register a user to a webinar
#registrants(...)	POST /registrants	List registrants and attendees
#unsubscribe(...)	POST /unsubscribe	Unsubscribe a lead from notifications

Installation

# Gemfile
gem "webinarjam"

Usage

require "webinarjam"

client = WebinarJam::Client.new(api_key: ENV["WEBINARJAM_API_KEY"])
# api_key: defaults to ENV["WEBINARJAM_API_KEY"], so this is equivalent:
client = WebinarJam::Client.new

# Or configure once, module-wide:
WebinarJam.configure { |config| config.api_key = "your-key" }
client = WebinarJam.client

# List all webinars
client.webinars
# => { status: "success", webinars: [{ webinar_id: 1, webinar_hash: "abcd1234", ... }] }

# Details for one webinar (schedule ids live here)
details = client.webinar(1)
schedule = details[:webinar][:schedules].first[:schedule]

# Register a user
client.register(
  webinar_id: 1,
  schedule: schedule,
  first_name: "Jane",
  email: "jane@example.com",
  # optional: last_name, country, state, timezone_id, ip_address,
  #           phone_country_code, phone, twilio_consent
)
# => { status: "success", user: { user_id: ..., live_room_url: ..., ... } }

# Registrants / attendees for one session (paginated)
listing = client.registrants(webinar_id: 1, schedule_id: schedule, search: "jane@example.com")
# => { status: "success", registrants: { current_page: 1, data: [{ lead_id: ..., email: ..., ... }] } }
# optional filters: attended_live, attended_replay, purchased, page,
#                   attended_live_timestamp, attended_replay_timestamp, date_range

# Unsubscribe a lead (lead id comes from #registrants)
client.unsubscribe(webinar_id: 1, lead_id: 818)
# => true (the API responds 204 No Content)

All responses are parsed JSON with symbolized keys.

EverWebinar

The EverWebinar API shares the same shape under a different path prefix:

client = WebinarJam::Client.new(product: :everwebinar)

Errors and rate limiting

Every API failure raises a subclass of WebinarJam::Error:

• WebinarJam::ConfigurationError — no API key provided.
• WebinarJam::AuthenticationError — HTTP 401/403 (invalid API key).
• WebinarJam::RateLimitError — HTTP 429. The API allows at most 20 calls per second per user.
• WebinarJam::APIError — any other error, including 2xx responses whose body carries "status": "error". Exposes #http_status and #body.

Opt into automatic retries on 429 (exponential backoff: 0.5s, 1s, 2s, ...):

client = WebinarJam::Client.new(max_retries: 3)

Development

bundle install
bundle exec rspec              # unit specs + integration specs (VCR replay)
bundle exec rspec spec/webinarjam  # unit specs only
bin/console                    # IRB with the gem and .env loaded

Integration specs replay VCR cassettes committed under spec/fixtures/vcr_cassettes/ — no credentials needed. To re-record against the live API, put a real key in .env (WEBINARJAM_API_KEY=...) and run:

VCR_RECORD=all bundle exec rspec spec/integration

The API key is filtered out of cassettes (<API_KEY>), but recorded bodies still contain your account's webinar names and room URLs — review cassettes before publishing them anywhere.

License

MIT