twilio

README

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

Documentation

Overview

Package twilio provides a Go SDK for Twilio with adapters for omnichat and omnivoice.

This package implements:

• omnichat.Provider: SMS messaging
• omnivoice interfaces: callsystem, transport, tts, stt

Installation

go get github.com/plexusone/omni-twilio

Environment Variables

TWILIO_ACCOUNT_SID - Your Twilio Account SID
TWILIO_AUTH_TOKEN  - Your Twilio Auth Token

Quick Start - SMS (omnichat)

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

provider, _ := omnichat.New(
    omnichat.WithPhoneNumber("+1234567890"),
)
provider.Send(ctx, "+1987654321", provider.OutgoingMessage{Content: "Hello!"})

Quick Start - Voice (omnivoice)

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

cs, _ := callsystem.New()
tr, _ := transport.New()

Index

• Constants

Constants

const (
	// DefaultAPIBaseURL is the Twilio REST API base URL.
	DefaultAPIBaseURL = "https://api.twilio.com/2010-04-01"

	// DefaultMediaStreamURL is the WebSocket URL format for Media Streams.
	// Format: wss://media-stream.twilio.com/v1/Accounts/{AccountSid}/Calls/{CallSid}/Media
	DefaultMediaStreamURL = "wss://media-stream.twilio.com"
)

Twilio API constants.

const (
	// AudioEncodingMulaw is the μ-law encoding (8-bit, 8kHz).
	AudioEncodingMulaw = "audio/x-mulaw"

	// AudioEncodingPCM is the PCM encoding (16-bit, 8kHz).
	AudioEncodingPCM = "audio/x-l16"

	// DefaultSampleRate is the default sample rate for Twilio audio (8kHz).
	DefaultSampleRate = 8000
)

Audio format constants for Media Streams.

const (
	VoiceAlice  = "alice"   // Twilio's default voice
	VoiceMan    = "man"     // Male voice
	VoiceWoman  = "woman"   // Female voice
	VoicePolly  = "Polly."  // Amazon Polly prefix (e.g., "Polly.Joanna")
	VoiceGoogle = "Google." // Google TTS prefix (e.g., "Google.en-US-Standard-A")
	VoiceAmazon = "Amazon." // Amazon prefix
)

TwiML voice options.

const (
	CallStatusQueued     = "queued"
	CallStatusRinging    = "ringing"
	CallStatusInProgress = "in-progress"
	CallStatusCompleted  = "completed"
	CallStatusBusy       = "busy"
	CallStatusFailed     = "failed"
	CallStatusNoAnswer   = "no-answer"
	CallStatusCanceled   = "canceled"
)

Call status constants.

const ProviderName = "twilio"

ProviderName is the name used to identify this provider in OmniVoice.

const Version = "0.5.0"

Version is the SDK version.