Omni-Twilio

Go SDK for Twilio with adapters for OmniChat (SMS) and OmniVoice (voice).

Features

• 📞 CallSystem: PSTN call handling (incoming/outgoing phone calls)
• 📡 Transport: Twilio Media Streams for real-time audio
• 🗣️ TTS: Text-to-speech via Twilio's Say verb (Alice, Polly, Google voices)
• 👂 STT: Speech recognition via Gather verb and real-time transcription
• 💬 SMS: Send/receive SMS via OmniChat provider interface

Installation

go get github.com/plexusone/omni-twilio

Package Structure

omni-twilio/
├── client/           # Exported Twilio REST API client
├── omnichat/         # SMS provider for omnichat
└── omnivoice/
    ├── callsystem/   # Call handling provider
    ├── transport/    # Media Streams provider
    ├── stt/          # Speech-to-text provider
    └── tts/          # Text-to-speech provider

Quick Start

SMS (OmniChat)

import "github.com/plexusone/omni-twilio/omnichat"

provider, _ := omnichat.New(
    omnichat.WithAccountSID("ACxxxxxxxx"),
    omnichat.WithAuthToken("your-token"),
    omnichat.WithPhoneNumber("+15551234567"),
)

// Connect and send SMS
provider.Connect(ctx)
provider.Send(ctx, "+15559876543", provider.OutgoingMessage{
    Content: "Hello from Twilio!",
})

// Handle incoming SMS via webhook
http.Handle("/sms", provider.WebhookHandler())

Voice Calls (OmniVoice)

import (
    "github.com/plexusone/omni-twilio/omnivoice/callsystem"
    "github.com/plexusone/omni-twilio/omnivoice/transport"
)

// Create call system
cs, _ := callsystem.New(
    callsystem.WithPhoneNumber("+15551234567"),
    callsystem.WithWebhookURL("wss://your-server.com/media-stream"),
)

// Handle incoming calls
cs.OnIncomingCall(func(call callsystem.Call) error {
    fmt.Printf("Incoming call from %s\n", call.From())
    return call.Answer(context.Background())
})

// Make outbound call
call, _ := cs.MakeCall(ctx, "+15559876543")
fmt.Printf("Call initiated: %s\n", call.ID())

// Set up webhooks
http.HandleFunc("/incoming", handleIncoming(cs))
http.HandleFunc("/media-stream", handleMediaStream(cs.Transport()))

Direct Client Usage

import "github.com/plexusone/omni-twilio/client"

c, _ := client.New(&client.Config{
    AccountSID: "ACxxxxxxxx",
    AuthToken:  "your-token",
})

// Send SMS
msg, _ := c.SendSMS(ctx, &client.SendSMSParams{
    To:   "+15559876543",
    From: "+15551234567",
    Body: "Hello!",
})

// Make call
call, _ := c.MakeCall(ctx, &client.MakeCallParams{
    To:    "+15559876543",
    From:  "+15551234567",
    Twiml: "<Response><Say>Hello!</Say></Response>",
})

TTS (Text-to-Speech)

import "github.com/plexusone/omni-twilio/omnivoice/tts"

provider, _ := tts.New(
    tts.WithVoice("Polly.Joanna"),
    tts.WithLanguage("en-US"),
)

// Generate TwiML
result, _ := provider.Synthesize(ctx, "Hello!", tts.SynthesisConfig{
    VoiceID: "Polly.Matthew",
})
// result.Audio contains TwiML

STT (Speech-to-Text)

import "github.com/plexusone/omni-twilio/omnivoice/stt"

provider, _ := stt.New(
    stt.WithLanguage("en-US"),
    stt.WithSpeechModel("phone_call"),
)

// Generate TwiML for speech recognition
twiml := provider.GenerateGatherTwiML(stt.GatherConfig{
    Input:         "speech",
    Language:      "en-US",
    SpeechTimeout: "auto",
    Action:        "/handle-speech",
    Prompt:        "Please say your account number",
})

Transport (Media Streams)

import "github.com/plexusone/omni-twilio/omnivoice/transport"

tr, _ := transport.New()

// Listen for Media Stream connections
connCh, _ := tr.Listen(ctx, "/media-stream")

for conn := range connCh {
    go func(c transport.Connection) {
        audio := make([]byte, 1024)
        for {
            n, _ := c.AudioOut().Read(audio)
            // Process audio...
            c.AudioIn().Write(responseAudio)
        }
    }(conn)
}

Configuration

Environment Variables

export TWILIO_ACCOUNT_SID="your-account-sid"
export TWILIO_AUTH_TOKEN="your-auth-token"

Available Voices

Twilio Basic: alice, man, woman

Amazon Polly: Polly.Joanna, Polly.Matthew, Polly.Amy, Polly.Brian, etc.

Google TTS: Google.en-US-Standard-A through D, Google.en-US-Wavenet-A through D

Testing

# Unit tests
go test -v ./...

# Integration tests (requires credentials)
export TWILIO_ACCOUNT_SID="ACxxxx"
export TWILIO_AUTH_TOKEN="xxxx"
export TWILIO_PHONE_NUMBER="+15551234567"
go test -v -tags=integration ./...

Migration

From twilio-go (v0.5.0)

This package was renamed from twilio-go to omni-twilio in v0.5.0 to align with the omni-* naming convention.

# Update imports
find . -name "*.go" -exec sed -i '' \
  's|github.com/plexusone/twilio-go|github.com/plexusone/omni-twilio|g' {} +

# Update go.mod
go get github.com/plexusone/omni-twilio@v0.5.0
go mod tidy

From omnivoice-twilio (v0.4.0)

Before	After
github.com/plexusone/omnivoice-twilio/callsystem	github.com/plexusone/omni-twilio/omnivoice/callsystem
github.com/plexusone/omnivoice-twilio/transport	github.com/plexusone/omni-twilio/omnivoice/transport
github.com/plexusone/omnivoice-twilio/tts	github.com/plexusone/omni-twilio/omnivoice/tts
github.com/plexusone/omnivoice-twilio/stt	github.com/plexusone/omni-twilio/omnivoice/stt

Added in v0.4.0:

• github.com/plexusone/omni-twilio/client - Exported Twilio client
• github.com/plexusone/omni-twilio/omnichat - SMS provider for OmniChat

Related Packages

• omnivoice-core - Voice interfaces
• omnichat - Chat interfaces
• elevenlabs-go - ElevenLabs SDK

License

MIT