Go SDK

The official Audian SDK for Go.

Installation

Install the SDK using Go modules:

go get github.com/audian/audian-go

Quick Start

package main

import (
    "fmt"
    "log"

    audian "github.com/audian/audian-go"
)

func main() {
    client := audian.NewClient(
        audian.WithAPIKey("YOUR_API_KEY"),
    )

    // Search for phone numbers
    numbers, err := client.Numbers.Search(nil, &audian.SearchNumbersRequest{
        Location: "US-CA-415",
        Limit: 10,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d numbers\n", len(numbers.Data.Numbers))
}

Configuration

Initialize Client

client := audian.NewClient(
    audian.WithAPIKey("sk_live_..."),
    audian.WithBaseURL("https://api.audian.com:8443/v2"), // Optional
    audian.WithTimeout(30 * time.Second), // Optional
    audian.WithMaxRetries(3), // Optional
    audian.WithBackoffFactor(2), // Optional
)

Environment Variables

export AUDIAN_API_KEY='sk_live_...'

apiKey := os.Getenv("AUDIAN_API_KEY")
client := audian.NewClient(
    audian.WithAPIKey(apiKey),
)

Phone Numbers API

Search Numbers

numbers, err := client.Numbers.Search(nil, &audian.SearchNumbersRequest{
    Location: "US-CA-415",
    Pattern: "415*",
    Features: []string{"sms", "mms"},
    Limit: 20,
    Offset: 0,
})

if err != nil {
    log.Fatal(err)
}

for _, number := range numbers.Data.Numbers {
    fmt.Printf("Number: %s\n", number.Number)
}

List Your Numbers

response, err := client.Numbers.List(nil, &audian.ListNumbersRequest{
    Limit: 20,
    Offset: 0,
    Status: "active",
})

if err != nil {
    log.Fatal(err)
}

for _, number := range response.Data.Numbers {
    fmt.Printf("Number: %s\n", number.Number)
}

Get Number Details

number, err := client.Numbers.Get(nil, "num_abc123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Number: %s\n", number.Data.Number)

Purchase a Number

purchased, err := client.Numbers.Purchase(nil, &audian.PurchaseNumberRequest{
    Number: "+14155551234",
    FriendlyName: "Support Line",
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Purchased: %s\n", purchased.Data.Number)

Update Number Configuration

updated, err := client.Numbers.UpdateConfig(nil, "num_abc123", &audian.UpdateNumberConfigRequest{
    FriendlyName: "Support Line",
    CallForwarding: &audian.CallForwarding{
        Enabled: true,
        ForwardTo: "+14155559999",
        RingsBeforeForward: 4,
    },
    Voicemail: &audian.Voicemail{
        Enabled: true,
        Transcription: true,
    },
})

if err != nil {
    log.Fatal(err)
}

Set Caller ID

callerId, err := client.Numbers.SetCallerId(nil, "num_abc123", &audian.SetCallerIdRequest{
    CallerIdNumber: "+14155551234",
    CallerIdName: "Support",
})

if err != nil {
    log.Fatal(err)
}

Configure E911

e911, err := client.Numbers.SetE911(nil, "num_abc123", &audian.SetE911Request{
    AddressLine1: "123 Main Street",
    AddressLine2: "Suite 100",
    City: "San Francisco",
    State: "CA",
    PostalCode: "94102",
    Country: "US",
    CustomerName: "Acme Corp",
})

if err != nil {
    log.Fatal(err)
}

SMS API

Send SMS

response, err := client.SMS.Send(nil, &audian.SendSMSRequest{
    To: "+14155551234",
    From: "+14155559999",
    Message: "Hello, World!",
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("SMS ID: %s\n", response.Data.ID)

Send Batch SMS

response, err := client.SMS.SendBatch(nil, &audian.SendBatchSMSRequest{
    Messages: []audian.SMSMessage{
        {To: "+14155551234", Message: "Hello 1"},
        {To: "+14155551235", Message: "Hello 2"},
        {To: "+14155551236", Message: "Hello 3"},
    },
})

if err != nil {
    log.Fatal(err)
}

Get SMS Details

sms, err := client.SMS.Get(nil, "sms_abc123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %s\n", sms.Data.Status)

List SMS Messages

messages, err := client.SMS.List(nil, &audian.ListSMSRequest{
    Limit: 20,
    Offset: 0,
    Status: "delivered",
})

if err != nil {
    log.Fatal(err)
}

Voice API

Make a Call

call, err := client.Voice.MakeCall(nil, &audian.MakeCallRequest{
    To: "+14155551234",
    From: "+14155559999",
    Action: "connect",
    ConnectTo: "+14155559999",
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Call ID: %s\n", call.Data.ID)

Get Call Details

callDetails, err := client.Voice.GetCall(nil, "call_abc123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %s\n", callDetails.Data.Status)

List Calls

calls, err := client.Voice.ListCalls(nil, &audian.ListCallsRequest{
    Limit: 20,
    Status: "completed",
})

if err != nil {
    log.Fatal(err)
}

Billing API

Get Usage

usage, err := client.Billing.Usage.Get(nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("SMS Cost: %f\n", usage.Data.Usage.SMSMessages.Cost)
fmt.Printf("Voice Cost: %f\n", usage.Data.Usage.VoiceMinutes.Cost)

Get Usage Breakdown

breakdown, err := client.Billing.Usage.GetBreakdown(nil, &audian.UsageBreakdownRequest{
    Metric: "sms",
    Granularity: "day",
})

if err != nil {
    log.Fatal(err)
}

List Invoices

invoices, err := client.Billing.Invoices.List(nil, &audian.ListInvoicesRequest{
    Status: "paid",
    Limit: 20,
})

if err != nil {
    log.Fatal(err)
}

Get Invoice

invoice, err := client.Billing.Invoices.Get(nil, "inv_abc123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total: %f\n", invoice.Data.Total)

Download Invoice PDF

pdf, err := client.Billing.Invoices.GetPDF(nil, "inv_abc123")
if err != nil {
    log.Fatal(err)
}

err = os.WriteFile("invoice.pdf", pdf, 0644)
if err != nil {
    log.Fatal(err)
}

Error Handling

import "github.com/audian/audian-go/errors"

purchased, err := client.Numbers.Purchase(nil, &audian.PurchaseNumberRequest{
    Number: "+14155551234",
})

if err != nil {
    if aerr, ok := err.(*audian.AudianError); ok {
        fmt.Printf("Error: %s\n", aerr.Message)
        fmt.Printf("Code: %s\n", aerr.Code)
        fmt.Printf("Status: %d\n", aerr.HTTPStatus)
    } else {
        log.Fatal(err)
    }
}

Rate Limiting

The SDK automatically handles rate limiting with exponential backoff:

// Automatically retries with exponential backoff
numbers, err := client.Numbers.Search(nil, &audian.SearchNumbersRequest{
    Location: "US-CA-415",
})

Custom Retry Configuration

client := audian.NewClient(
    audian.WithAPIKey("YOUR_API_KEY"),
    audian.WithMaxRetries(5),
    audian.WithBackoffFactor(2),
    audian.WithInitialRetryDelay(100 * time.Millisecond),
)

Monitor Rate Limit Headers

response, err := client.Numbers.List(nil, nil)
if err != nil {
    log.Fatal(err)
}

limit := response.Headers.Get("ratelimit-limit")
remaining := response.Headers.Get("ratelimit-remaining")
reset := response.Headers.Get("ratelimit-reset")

fmt.Printf("Limit: %s, Remaining: %s, Reset: %s\n", limit, remaining, reset)

Context Support

All SDK methods support Go contexts for timeout and cancellation:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

numbers, err := client.Numbers.Search(ctx, &audian.SearchNumbersRequest{
    Location: "US-CA-415",
})

Webhooks

Verify Webhook Signature

import "github.com/audian/audian-go/webhooks"

verifier := webhooks.NewVerifier("whsec_...")

http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-Audian-Signature")

    event, err := verifier.Verify(body, signature)
    if err != nil {
        w.WriteHeader(http.StatusUnauthorized)
        fmt.Fprintf(w, `{"error": "Unauthorized"}`)
        return
    }

    fmt.Printf("Event type: %s\n", event.Type)
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    fmt.Fprintf(w, `{"success": true}`)
})

Handle Webhook Events

switch event.Type {
case "sms.received":
    sms := event.Data.(audian.SMSReceivedEvent)
    fmt.Printf("SMS from %s: %s\n", sms.From, sms.Message)

case "call.completed":
    call := event.Data.(audian.CallCompletedEvent)
    fmt.Printf("Call duration: %d seconds\n", call.Duration)

case "number.ported":
    port := event.Data.(audian.NumberPortedEvent)
    fmt.Printf("Number %s ported successfully\n", port.Number)
}

Complete Example

package main

import (
    "fmt"
    "log"
    "os"

    audian "github.com/audian/audian-go"
)

func main() {
    client := audian.NewClient(
        audian.WithAPIKey(os.Getenv("AUDIAN_API_KEY")),
    )

    // Search for available numbers
    available, err := client.Numbers.Search(nil, &audian.SearchNumbersRequest{
        Location: "US-CA-415",
        Limit: 5,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d numbers\n", len(available.Data.Numbers))

    // Purchase the first number
    if len(available.Data.Numbers) > 0 {
        number := available.Data.Numbers[0].Number

        purchased, err := client.Numbers.Purchase(nil, &audian.PurchaseNumberRequest{
            Number: number,
            FriendlyName: "Demo Number",
        })
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("Purchased: %s\n", purchased.Data.Number)

        // Send SMS from the number
        sms, err := client.SMS.Send(nil, &audian.SendSMSRequest{
            From: purchased.Data.Number,
            To: "+14155559999",
            Message: "Hello from Audian!",
        })
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("SMS sent: %s\n", sms.Data.ID)
    }
}

Support

• GitHub Repository
• Go Package
• Issues and Bug Reports

Version History

See changelog