BessAI Ruby SDK

Official Ruby client library for the BessAI Voice AI Platform API.

Installation

Add to your Gemfile:

gem "bessai"

Then run:

bundle install

Or install directly:

gem install bessai

Requirements

• Ruby >= 3.1

Quick Start

require "bessai"

client = BessAI.new(api_key: "your-api-key")

# List agents
agents = client.agents.list
puts agents

# Create an agent
agent = client.agents.create(
  agent_name: "Support Agent",
  llm_provider: "openai",
  llm_model: "gpt-4o",
  system_prompt: "You are a helpful customer support agent.",
  voice_provider: "elevenlabs",
  voice_id: "21m00Tcm4TlvDq8ikWAM"
)
puts agent["agent_id"]

Configuration

# Via constructor
client = BessAI.new(
  api_key: "your-api-key",
  base_url: "https://your-instance.bessai.com",
  timeout: 60,
  max_retries: 5
)

# Via environment variables
# BESSAI_API_KEY=your-api-key
# BESSAI_BASE_URL=https://your-instance.bessai.com
client = BessAI.new

Resources

Agents

# CRUD
agents = client.agents.list(skip: 0, limit: 20)
agent = client.agents.get("agent-id")
agent = client.agents.create(agent_name: "My Agent", llm_model: "gpt-4o")
agent = client.agents.update("agent-id", agent_name: "Updated Name")
client.agents.delete("agent-id")

# Publishing & versions
client.agents.publish("agent-id")
versions = client.agents.get_versions("agent-id")

# Export / Import
data = client.agents.export("agent-id")
agent = client.agents.import_agent("/path/to/agent.json")

# Workflow links
client.agents.link_workflow("agent-id", "workflow-id", priority: 1)
client.agents.unlink_workflow("agent-id", "workflow-id")
workflows = client.agents.list_workflows("agent-id")

Calls

# Create calls
call = client.calls.create_phone_call(
  agent_id: "agent-id",
  from_number: "+1234567890",
  to_number: "+0987654321"
)

web_call = client.calls.create_web_call(agent_id: "agent-id")
test_call = client.calls.create_test_call(agent_id: "agent-id")

# Manage
call = client.calls.get("call-id")
calls = client.calls.list(agent_id: "agent-id", status: "completed")
client.calls.end_call("call-id")
client.calls.delete("call-id")

Phone Numbers

numbers = client.phone_numbers.list
number = client.phone_numbers.create(
  phone_number: "+1234567890",
  provider: "custom",
  inbound_agent_id: "agent-id"
)
client.phone_numbers.update_agents("number-id",
  inbound_agent_id: "agent-1",
  outbound_agent_id: "agent-2"
)

# SIP connections
conn = client.phone_numbers.create_sip_connection("number-id",
  termination_uri: "sip.example.com",
  connection_type: "inbound"
)
connections = client.phone_numbers.list_sip_connections("number-id")
client.phone_numbers.sync_sip_connection("number-id", "conn-id")

Batch Calls

batch = client.batch_calls.create(
  agent_id: "agent-id",
  from_number: "+1234567890",
  contacts: [
    { phone_number: "+1111111111", dynamic_variables: { name: "Alice" } },
    { phone_number: "+2222222222", dynamic_variables: { name: "Bob" } }
  ],
  max_concurrent_calls: 5
)

client.batch_calls.start(batch["batch_call_id"])
client.batch_calls.pause(batch["batch_call_id"])
client.batch_calls.resume(batch["batch_call_id"])
client.batch_calls.cancel(batch["batch_call_id"])

items = client.batch_calls.list_items(batch["batch_call_id"])
active = client.batch_calls.list_active

Workflows

# Generate & refine
wf = client.workflows.create(
  name: "Post-Call Summary",
  description: "Send a summary email after each call",
  trigger_type: "post_call"
)
wf = client.workflows.refine(wf["workflow_id"], feedback: "Add Slack notification")

# Deploy & execute
client.workflows.deploy(wf["workflow_id"])
result = client.workflows.execute(wf["workflow_id"], context_data: { key: "value" })
result = client.workflows.test(wf["workflow_id"], test_data: { key: "value" })

# Secrets
client.workflows.save_secrets(wf["workflow_id"],
  secrets: [{ key_name: "SMTP_PASSWORD", value: "secret", type: "string" }]
)

# Agent links
client.workflows.link_agent(wf["workflow_id"], "agent-id", priority: 1)
client.workflows.list_agents(wf["workflow_id"])

# Scheduling
client.workflows.set_schedule(wf["workflow_id"], cron: "0 9 * * *", timezone: "US/Eastern")
client.workflows.get_schedule(wf["workflow_id"])
client.workflows.remove_schedule(wf["workflow_id"])

# Import / Export
data = client.workflows.export(wf["workflow_id"])
client.workflows.import_workflow("/path/to/workflow.json")

Analytics

summary = client.analytics.get_summary(from_date: "2025-01-01", agent_id: "agent-id")
latency = client.analytics.get_latency(from_date: "2025-01-01")
daily = client.analytics.get_calls_by_day(days: 30)

Billing

balance = client.billing.get_balance
check = client.billing.check_balance(required: 10.0)

transactions = client.billing.list_transactions(limit: 50)
usage = client.billing.list_usage(event_type: "llm_completion")
summary = client.billing.get_usage_summary(start_date: "2025-01-01")
daily = client.billing.get_daily_usage(days: 30)
call_usage = client.billing.get_call_usage("call-id")

pricing = client.billing.get_pricing
estimate = client.billing.estimate_pricing(
  llm_provider: "openai",
  llm_model: "gpt-4o",
  voice_provider: "elevenlabs"
)

Configuration

providers = client.configuration.get_providers
stt = client.configuration.get_provider("stt")
defaults = client.configuration.get_defaults
languages = client.configuration.get_languages

Knowledge Bases

kb = client.knowledge_bases.create(name: "FAQ", description: "Customer FAQ documents")
kbs = client.knowledge_bases.list
kb = client.knowledge_bases.get("kb-id")

doc = client.knowledge_bases.upload_document("kb-id", "/path/to/document.pdf")
client.knowledge_bases.delete_document("kb-id", "doc-id")
client.knowledge_bases.delete("kb-id")

API Keys

key = client.api_keys.create(
  name: "Production Key",
  scopes: ["agents:read", "calls:write"],
  expires_in_days: 365
)
puts key["key"]  # Shown only once

keys = client.api_keys.list
key = client.api_keys.get("key-id")
client.api_keys.update("key-id", name: "Renamed Key")

rotated = client.api_keys.rotate("key-id", grace_period_hours: 48)
usage = client.api_keys.get_usage("key-id")
client.api_keys.delete("key-id")

Error Handling

begin
  client.agents.get("nonexistent")
rescue BessAI::AuthenticationError => e
  puts "Invalid API key: #{e.message}"
rescue BessAI::NotFoundError => e
  puts "Agent not found: #{e.message}"
rescue BessAI::RateLimitError => e
  puts "Rate limited, retry after: #{e.retry_after}s"
rescue BessAI::ValidationError => e
  puts "Validation errors: #{e.errors}"
rescue BessAI::Error => e
  puts "API error (#{e.status_code}): #{e.message}"
end

License

MIT - see LICENSE for details.