BESS AI Go SDK

Official Go client for the BESS AI Voice AI Call Center Orchestration platform.

Installation

go get github.com/BESS-Analytics/bessai-go

Requirements: Go 1.21+

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	bessai "github.com/BESS-Analytics/bessai-go"
)

func main() {
	client := bessai.NewClient(
		bessai.WithAPIKey("your-api-key"),
		bessai.WithBaseURL("https://api.bess-ai.com"),
	)

	ctx := context.Background()

	// List agents
	agents, err := client.Agent.List(ctx, 0, 20)
	if err != nil {
		log.Fatal(err)
	}
	for _, a := range agents {
		fmt.Printf("Agent: %s (%s)\n", a.AgentName, a.AgentID)
	}
}

Authentication

Set your API key via the constructor option or BESSAI_API_KEY environment variable:

// Option 1: explicit
client := bessai.NewClient(bessai.WithAPIKey("your-api-key"))

// Option 2: environment variable (BESSAI_API_KEY)
client := bessai.NewClient()

Resources

Resource	Accessor	Methods
Agents	client.Agent	Create, Retrieve, List, Update, Delete, Publish, GetVersions, Export, ImportAgent, LinkWorkflow, UnlinkWorkflow, ListWorkflows
Calls	client.Call	CreatePhoneCall, CreateWebCall, CreateTestCall, Retrieve, List, End, Delete
Phone Numbers	client.PhoneNumber	Create, Retrieve, List, Update, Delete, UpdateAgents, CreateSIPConnection, ListSIPConnections, RetrieveSIPConnection, UpdateSIPConnection, DeleteSIPConnection, SyncSIPConnection
Batch Calls	client.BatchCall	Create, Retrieve, List, ListActive, ListItems, Delete, Start, Pause, Resume, Cancel
Workflows	client.Workflow	Create, Refine, Retrieve, List, Update, Delete, Restore, SaveSecrets, GetCredentialSchema, Deploy, Test, Execute, ListExecutions, Export, ImportWorkflow, LinkAgent, UpdateAgentLink, UnlinkAgent, ListAgents, ListByAgent, SetSchedule, RemoveSchedule, GetSchedule, ListSchedules
Analytics	client.Analytics	GetSummary, GetLatency, GetCallsByDay
Billing	client.Billing	GetBalance, CheckBalance, ListTransactions, ListUsage, GetUsageSummary, GetDailyUsage, GetCallUsage, GetPricing, EstimatePricing
Config	client.Config	GetProviders, GetProvider, GetDefaults, GetLanguages
Knowledge Bases	client.KnowledgeBases	Create, List, Get, Delete, UploadDocument, DeleteDocument
API Keys	client.APIKeys	Create, List, Get, Update, Delete, Rotate, GetUsage

Usage Examples

Create an Agent

agent, err := client.Agent.Create(ctx, bessai.AgentCreateParams{
	Name:         "Support Bot",
	SystemPrompt: "You are a helpful support assistant.",
	LLMProvider:  "openai",
	LLMModel:     "gpt-4",
	VoiceProvider: "elevenlabs",
	VoiceID:      "rachel",
})

Make a Phone Call

call, err := client.Call.CreatePhoneCall(ctx, bessai.PhoneCallCreateParams{
	AgentID:    "agent-id",
	FromNumber: "+1234567890",
	ToNumber:   "+0987654321",
})

Create a Batch Call Campaign

batch, err := client.BatchCall.Create(ctx, bessai.BatchCallCreateParams{
	AgentID:    "agent-id",
	FromNumber: "+1234567890",
	Contacts: []bessai.BatchCallContact{
		{PhoneNumber: "+1111111111"},
		{PhoneNumber: "+2222222222"},
	},
})

Generate and Deploy a Workflow

// Generate
workflow, err := client.Workflow.Create(ctx, bessai.WorkflowGenerateParams{
	Name:        "Post-Call CRM Update",
	Description: "After each call, update the CRM with call summary",
})

// Deploy
deploy, err := client.Workflow.Deploy(ctx, workflow.WorkflowID)

Check Billing

balance, err := client.Billing.GetBalance(ctx)
fmt.Printf("Balance: $%.2f\n", balance.CurrentBalance)

Stream Events

stream, err := client.ConnectStream(ctx, "room-name", func(event bessai.StreamEvent) {
	fmt.Printf("Event: %s\n", event.Event)
})
if err != nil {
	log.Fatal(err)
}
defer stream.Close()

Error Handling

All errors returned implement the error interface. Typed errors are available for specific HTTP status codes:

agent, err := client.Agent.Retrieve(ctx, "nonexistent-id")
if err != nil {
	switch e := err.(type) {
	case *bessai.NotFoundError:
		fmt.Println("Agent not found")
	case *bessai.AuthenticationError:
		fmt.Println("Invalid API key")
	case *bessai.RateLimitError:
		fmt.Printf("Rate limited, retry after %d seconds\n", e.RetryAfter)
	case *bessai.ValidationError:
		fmt.Printf("Validation errors: %v\n", e.Errors)
	default:
		fmt.Printf("Error: %s\n", err.Error())
	}
}

Configuration Options

client := bessai.NewClient(
	bessai.WithAPIKey("your-api-key"),
	bessai.WithBaseURL("https://api.bess-ai.com"),
	bessai.WithTimeout(60),       // seconds
	bessai.WithMaxRetries(3),
	bessai.WithHeaders(map[string]string{
		"X-Custom-Header": "value",
	}),
)

License

MIT — see LICENSE for details.