BessAI Java SDK

Official Java SDK for the BessAI Voice AI platform. Build, manage, and monitor AI-powered voice agents.

Requirements

• Java 11 or higher
• No external HTTP dependencies (uses java.net.http.HttpClient)
• Jackson 2.17+ for JSON serialization

Installation

Maven

<dependency>
    <groupId>com.bessai</groupId>
    <artifactId>bessai-java</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.bessai:bessai-java:0.1.0'

Quick Start

import com.bessai.BessAI;
import com.bessai.types.*;

// Create client
BessAI client = BessAI.withApiKey("sk-your-api-key");

// Or use builder for more options
BessAI client = BessAI.builder()
    .apiKey("sk-your-api-key")
    .baseUrl("https://api.bess-ai.com")
    .timeout(30)
    .maxRetries(3)
    .build();

// List agents
List<AgentResponse> agents = client.agents().list();

// Create an agent
AgentParams params = new AgentParams()
    .setName("My Agent")
    .setSystemPrompt("You are a helpful assistant")
    .setLlmProvider("openai")
    .setLlmModel("gpt-4o-mini")
    .setVoiceProvider("elevenlabs")
    .setVoiceId("rachel");

AgentResponse agent = client.agents().create(params);

Resources

Agents

// List all agents
List<AgentResponse> agents = client.agents().list();

// Get a specific agent
AgentResponse agent = client.agents().get("agent-id");

// Create an agent
AgentResponse agent = client.agents().create(new AgentParams()
    .setName("Support Agent")
    .setSystemPrompt("You help customers with their questions"));

// Update an agent
AgentResponse updated = client.agents().update("agent-id", new AgentParams()
    .setName("Updated Name"));

// Delete an agent
client.agents().delete("agent-id");

// Publish an agent
client.agents().publish("agent-id");

// Duplicate an agent
client.agents().duplicate("agent-id", "Copy of Agent");

// List versions
List<AgentVersion> versions = client.agents().listVersions("agent-id");

Calls

// Create a phone call
CallResponse call = client.calls().createPhoneCall(new PhoneCallParams()
    .setAgentId("agent-id")
    .setFromNumber("+1234567890")
    .setToNumber("+0987654321"));

// Create a web call
CallResponse webCall = client.calls().createWebCall(new WebCallParams()
    .setAgentId("agent-id"));

// List calls
List<CallListItem> calls = client.calls().list();

// List calls with filters
List<CallListItem> filtered = client.calls().list(new CallListParams()
    .setStatus("completed")
    .setLimit(10));

// Get call details
CallResponse detail = client.calls().get("call-id");

// End a call
client.calls().end("call-id");

Phone Numbers

// List phone numbers
List<PhoneNumberResponse> numbers = client.phoneNumbers().list();

// Create a phone number
PhoneNumberResponse number = client.phoneNumbers().create(new PhoneNumberCreateParams()
    .setPhoneNumber("+1234567890")
    .setProvider("twilio")
    .setDisplayName("Main Line"));

// Assign agent to phone number
client.phoneNumbers().updateAgent("phone-id", "agent-id");

// SIP connections
List<SIPConnectionResponse> sips = client.phoneNumbers().listSIPConnections();

Batch Calls

import java.util.Arrays;

// Create a batch call
BatchCallResponse batch = client.batchCalls().create(new BatchCallCreateParams()
    .setName("Campaign 1")
    .setAgentId("agent-id")
    .setFromNumber("+1234567890")
    .setContacts(Arrays.asList(
        new BatchCallContact().setToNumber("+1111111111"),
        new BatchCallContact().setToNumber("+2222222222")
    )));

// Start the batch
client.batchCalls().start(batch.getId());

// Check status
BatchCallStatusResponse status = client.batchCalls().getStatus(batch.getId());

Workflows

// Generate a workflow with AI
GenerateResponse workflow = client.workflows().generate(new WorkflowParams.Generate()
    .setDescription("Send email after call ends")
    .setExecutionMode("async"));

// Deploy
DeployResponse deployed = client.workflows().deploy(workflow.getWorkflowId());

// Execute manually
WorkflowExecutionResponse exec = client.workflows().execute("workflow-id",
    new WorkflowParams.ManualExecute().setInput(Map.of("key", "value")));

// Link to agent
client.workflows().linkAgent("workflow-id", new WorkflowParams.LinkAgent()
    .setAgentId("agent-id")
    .setTriggerConditionDescription("When customer asks about pricing"));

Analytics

AnalyticsSummary summary = client.analytics().getSummary();
AnalyticsSummary filtered = client.analytics().getSummary("2024-01-01", "2024-12-31", null);

Billing

CreditBalanceResponse balance = client.billing().getBalance();
UsageSummaryResponse usage = client.billing().getUsageSummary();
ServicePricingResponse pricing = client.billing().getPricing();

Configuration

var providers = client.config().getProviders();
var defaults = client.config().getDefaults();
var languages = client.config().getLanguages();

Knowledge Bases

import java.nio.file.Path;

KnowledgeBase kb = client.knowledgeBases().create(new KnowledgeBaseCreateParams()
    .setName("Product Docs")
    .setDescription("Product documentation"));

// Upload document
Document doc = client.knowledgeBases().uploadDocument(kb.getId(), Path.of("docs/guide.pdf"));

API Keys

APIKeyCreated key = client.apiKeys().create(new APIKeyCreateParams()
    .setName("Production Key")
    .setScopes(Arrays.asList("agents:read", "calls:write")));

System.out.println("Key: " + key.getKey()); // Only shown once

Async Support

All resources support async operations via CompletableFuture:

// Async list agents
client.agents().listAsync()
    .thenAccept(agents -> agents.forEach(a -> System.out.println(a.getAgentName())))
    .exceptionally(e -> { System.err.println("Error: " + e); return null; });

// Async create call
client.calls().createWebCallAsync(new WebCallParams().setAgentId("agent-id"))
    .thenAccept(call -> System.out.println("Call started: " + call.getCallId()));

Streaming

Real-time event streaming via WebSocket:

import com.bessai.StreamingClient;

StreamingClient streaming = new StreamingClient(client.httpClient());
streaming.connect("call-id",
    event -> System.out.println("Event: " + event),
    error -> System.err.println("Error: " + error.getMessage()),
    () -> System.out.println("Stream closed")
).join();

// Send message
streaming.send("{\"type\": \"ping\"}");

// Close
streaming.close();

Error Handling

import com.bessai.exceptions.*;

try {
    client.agents().get("nonexistent");
} catch (NotFoundException e) {
    System.out.println("Agent not found (HTTP " + e.getStatusCode() + ")");
} catch (AuthenticationException e) {
    System.out.println("Invalid API key");
} catch (RateLimitException e) {
    System.out.println("Rate limited. Retry after " + e.getRetryAfter() + "s");
} catch (ValidationException e) {
    System.out.println("Validation errors: " + e.getErrors());
} catch (BessAIException e) {
    System.out.println("API error: " + e.getMessage());
}

Configuration

Environment Variables

export BESSAI_API_KEY=sk-your-api-key
export BESSAI_BASE_URL=https://api.bess-ai.com

// Will auto-read BESSAI_API_KEY from environment
BessAI client = BessAI.builder().build();

License

MIT