BessAI .NET SDK

Official .NET SDK for the BessAI Voice AI Platform.

Requirements

• .NET 6.0 or later

Installation

dotnet add package BessAI

Or via NuGet Package Manager:

Install-Package BessAI

Quick Start

using BessAI;
using BessAI.Types;

// Create client (reads BESSAI_API_KEY from environment)
using var client = BessAIClient.CreateBuilder()
    .ApiKey("your-api-key")
    .Build();

// List agents
var agents = await client.Agents.ListAsync();
foreach (var agent in agents)
    Console.WriteLine($"{agent.Id}: {agent.Name}");

// Create an agent
var newAgent = await client.Agents.CreateAsync(new AgentParams
{
    Name = "Customer Support",
    SystemPrompt = "You are a helpful customer support agent.",
    LlmProvider = "openai",
    LlmModel = "gpt-4o-mini"
});

Configuration

Environment Variables

Variable	Description
BESSAI_API_KEY	API key for authentication
BESSAI_BASE_URL	Custom API base URL

Builder Pattern

using var client = BessAIClient.CreateBuilder()
    .ApiKey("your-api-key")
    .BaseUrl("https://your-instance.com")
    .Timeout(TimeSpan.FromSeconds(60))
    .MaxRetries(5)
    .Header("X-Custom-Header", "value")
    .Build();

Shorthand

using var client = BessAIClient.WithApiKey("your-api-key");

Resources

Agents

// List all agents
var agents = await client.Agents.ListAsync();

// Get a specific agent
var agent = await client.Agents.GetAsync("agent-id");

// Create an agent
var created = await client.Agents.CreateAsync(new AgentParams
{
    Name = "My Agent",
    SystemPrompt = "You are a helpful assistant.",
    LlmProvider = "openai",
    LlmModel = "gpt-4o-mini",
    VoiceProvider = "elevenlabs",
    VoiceId = "voice-id"
});

// Update an agent
var updated = await client.Agents.UpdateAsync("agent-id", new AgentParams
{
    Name = "Updated Name"
});

// Delete an agent
await client.Agents.DeleteAsync("agent-id");

// Publish & version management
await client.Agents.PublishAsync("agent-id");
var versions = await client.Agents.ListVersionsAsync("agent-id");
var version = await client.Agents.GetVersionAsync("agent-id", 1);
var duplicate = await client.Agents.DuplicateAsync("agent-id", "Copy of Agent");

Calls

// List calls with filters
var calls = await client.Calls.ListAsync(new CallListParams
{
    Status = "completed",
    Limit = 10
});

// Create a phone call
var call = await client.Calls.CreatePhoneCallAsync(new PhoneCallParams
{
    AgentId = "agent-id",
    FromNumber = "+1234567890",
    ToNumber = "+0987654321"
});

// Create a web call
var webCall = await client.Calls.CreateWebCallAsync(new WebCallParams
{
    AgentId = "agent-id"
});

// End a call
await client.Calls.EndAsync("call-id");

Phone Numbers

// List phone numbers
var numbers = await client.PhoneNumbers.ListAsync();

// Create a phone number
var number = await client.PhoneNumbers.CreateAsync(new PhoneNumberCreateParams
{
    PhoneNumber = "+1234567890",
    DisplayName = "Main Line",
    AgentId = "agent-id"
});

// SIP connections
var sipConnections = await client.PhoneNumbers.ListSIPConnectionsAsync();
var sipConn = await client.PhoneNumbers.CreateSIPConnectionAsync(new SIPConnectionParams
{
    Name = "My SIP",
    SipAddress = "sip.example.com",
    Transport = "TCP"
});

Batch Calls

// Create a batch call campaign
var batch = await client.BatchCalls.CreateAsync(new BatchCallCreateParams
{
    Name = "Campaign Q1",
    AgentId = "agent-id",
    FromNumber = "+1234567890",
    Contacts = new List<BatchCallContact>
    {
        new() { ToNumber = "+1111111111" },
        new() { ToNumber = "+2222222222", DynamicVariables = new() { ["name"] = "Alice" } }
    },
    MaxConcurrent = 5
});

// Control batch execution
await client.BatchCalls.StartAsync("batch-id");
await client.BatchCalls.PauseAsync("batch-id");
await client.BatchCalls.ResumeAsync("batch-id");
await client.BatchCalls.CancelAsync("batch-id");

// Monitor progress
var status = await client.BatchCalls.GetStatusAsync("batch-id");
var results = await client.BatchCalls.GetCallResultsAsync("batch-id");

Workflows

// Generate a workflow with AI
var generated = await client.Workflows.GenerateAsync(new WorkflowParams.Generate
{
    Description = "Send an email when a call ends",
    ExecutionMode = "async"
});

// Deploy a workflow
await client.Workflows.DeployAsync("workflow-id");

// Execute a workflow
var execution = await client.Workflows.ExecuteAsync("workflow-id",
    new WorkflowParams.ManualExecute
    {
        Input = new() { ["key"] = "value" }
    });

// Link agents to workflows
await client.Workflows.LinkAgentAsync("workflow-id", new WorkflowParams.LinkAgent
{
    AgentId = "agent-id",
    TriggerConditionDescription = "When customer asks for discount"
});

Analytics

// Get summary analytics
var summary = await client.Analytics.GetSummaryAsync();
Console.WriteLine($"Total calls: {summary.TotalCalls}");

// Get agent-specific analytics
var agentStats = await client.Analytics.GetAgentAnalyticsAsync("agent-id",
    startDate: "2025-01-01", endDate: "2025-01-31");

Billing

// Check credit balance
var balance = await client.Billing.GetBalanceAsync();
Console.WriteLine($"Balance: {balance.Balance} {balance.Currency}");

// Get usage summary
var usage = await client.Billing.GetUsageSummaryAsync();

// Estimate costs
var estimate = await client.Billing.EstimateCostAsync(new PricingEstimateParams
{
    LlmProvider = "openai",
    LlmModel = "gpt-4o-mini",
    EstimatedDurationMinutes = 10
});

Configuration

var providers = await client.Config.GetProvidersAsync();
var defaults = await client.Config.GetDefaultsAsync();
var languages = await client.Config.GetLanguagesAsync();

Knowledge Bases

// Create a knowledge base
var kb = await client.KnowledgeBases.CreateAsync(new KnowledgeBaseCreateParams
{
    Name = "Product FAQ",
    Description = "Product documentation"
});

// Upload a document
var doc = await client.KnowledgeBases.UploadDocumentAsync("kb-id", "/path/to/document.pdf");

API Keys

// Create an API key
var key = await client.ApiKeys.CreateAsync(new APIKeyCreateParams
{
    Name = "Production Key",
    Scopes = new List<string> { "agents:read", "calls:write" }
});
Console.WriteLine($"Key: {key.Key}"); // Only shown once

// Revoke a key
await client.ApiKeys.RevokeAsync("key-id");

Streaming

var streaming = new StreamingClient(client.HttpClient);

await streaming.ConnectAsync("call-id",
    onMessage: message => Console.WriteLine($"Received: {message}"),
    onError: error => Console.Error.WriteLine($"Error: {error.Message}"),
    onClose: () => Console.WriteLine("Connection closed"));

await streaming.SendAsync("Hello from client");

// Later...
await streaming.CloseAsync();
streaming.Dispose();

Error Handling

using BessAI.Exceptions;

try
{
    var agent = await client.Agents.GetAsync("nonexistent-id");
}
catch (NotFoundException ex)
{
    Console.WriteLine($"Not found: {ex.Message}");
}
catch (AuthenticationException ex)
{
    Console.WriteLine($"Auth failed: {ex.Message}");
}
catch (ValidationException ex)
{
    Console.WriteLine($"Validation: {ex.Message}");
    foreach (var error in ex.Errors ?? new())
        Console.WriteLine($"  - {error}");
}
catch (RateLimitException ex)
{
    Console.WriteLine($"Rate limited. Retry after: {ex.RetryAfter}s");
}
catch (BessAIException ex)
{
    Console.WriteLine($"API error ({ex.StatusCode}): {ex.Message}");
}

Synchronous Usage

All async methods have synchronous counterparts:

// Async (recommended)
var agents = await client.Agents.ListAsync();

// Sync
var agents = client.Agents.List();

Dependency Injection

// In Startup.cs or Program.cs
services.AddSingleton<BessAIClient>(sp =>
    BessAIClient.CreateBuilder()
        .ApiKey(configuration["BessAI:ApiKey"]!)
        .Build());

License

MIT - see LICENSE for details.