sms

README

SMS Service Package

Package sms cung cấp abstraction layer để gửi SMS với hỗ trợ nhiều provider khác nhau.

Providers Hỗ Trợ

• ✅ Twilio API
• ✅ AWS Simple Notification Service (SNS)
• ✅ Vonage/Nexmo API
• ✅ MessageBird API

Tính Năng

• Gửi SMS đơn giản
• Gửi hàng loạt (bulk sending)
• Theo dõi trạng thái tin nhắn
• Hỗ trợ Unicode
• Tính toán segments và chi phí
• Validation số điện thoại

Sử Dụng Cơ Bản

import "github.com/vhvplatform/go-shared/sms"

// Tạo client với Twilio
client, err := sms.NewClient(sms.Config{
    Provider: sms.ProviderTwilio,
    From:     "+1234567890",
    Options: map[string]string{
        "account_sid": "your-account-sid",
        "auth_token": "your-auth-token",
    },
})

// Gửi SMS
msg := &sms.Message{
    From: "+1234567890",
    To:   []string{"+0987654321"},
    Body: "Hello from Go!",
}

result, err := client.Send(ctx, msg)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("SMS sent with ID: %s, Status: %s\n", 
    result.MessageID, result.Status)

Tính Toán Segments

msg := &sms.Message{
    Body: "Very long message...", // 200 characters
}

segments := msg.CalculateSegments()
fmt.Printf("Message will use %d segments\n", segments)

// Ước tính chi phí
cost := msg.EstimateCost(0.05) // $0.05 per segment
fmt.Printf("Estimated cost: $%.2f\n", cost)

Kiểm Tra Trạng Thái

// Sau khi gửi
result, _ := client.Send(ctx, msg)

// Kiểm tra trạng thái
time.Sleep(5 * time.Second)
status, err := client.GetStatus(ctx, result.MessageID)
fmt.Printf("Current status: %s\n", status.Status)

Gửi Hàng Loạt

messages := []*sms.Message{
    {To: []string{"+1111111111"}, Body: "Message 1"},
    {To: []string{"+2222222222"}, Body: "Message 2"},
}

results, err := client.SendBulk(ctx, messages)

Unicode Support

msg := &sms.Message{
    From:    "+1234567890",
    To:      []string{"+0987654321"},
    Body:    "Xin chào! 你好！",
    Unicode: true, // Bật hỗ trợ Unicode
}

client.Send(ctx, msg)

Status

🚧 In Development - Hiện tại package đã có interfaces và structures sẵn sàng, implementations cho các providers đang được phát triển.

Documentation

Overview

Package sms provides an abstraction layer for sending SMS messages with support for multiple providers (Twilio, AWS SNS, Nexmo, etc.)

Index

• type AWSSNSConfig
• type Client
  • func NewClient(config Config) (Client, error)
• type Config
• type Message
  • func (m *Message) CalculateSegments() int
  • func (m *Message) EstimateCost(costPerSegment float64) float64
  • func (m *Message) Validate() error
• type MessageBirdConfig
• type NexmoConfig
• type Provider
• type SendResult
• type Status
• type TwilioConfig

Types

type AWSSNSConfig

type AWSSNSConfig struct {
	Region          string // AWS region
	AccessKeyID     string // AWS access key ID
	SecretAccessKey string // AWS secret access key
}

AWSSNSConfig contains AWS SNS-specific configuration

type Client

type Client interface {
	// Send sends an SMS message
	Send(ctx context.Context, msg *Message) (*SendResult, error)

	// SendBulk sends multiple SMS messages in batch
	SendBulk(ctx context.Context, messages []*Message) ([]*SendResult, error)

	// GetStatus retrieves the status of a sent message
	GetStatus(ctx context.Context, messageID string) (*SendResult, error)

	// ValidatePhoneNumber checks if a phone number is valid
	ValidatePhoneNumber(phoneNumber string) error

	// Close closes the SMS client and releases resources
	Close() error
}

Client is the interface that all SMS providers must implement

func NewClient

func NewClient(config Config) (Client, error)

NewClient creates a new SMS client based on the provider

type Config

type Config struct {
	Provider Provider          // SMS provider to use
	From     string            // Default sender phone number or ID
	Options  map[string]string // Provider-specific options
}

Config contains configuration for SMS client

type Message

type Message struct {
	From    string   // Sender phone number or ID
	To      []string // Recipient phone numbers
	Body    string   // Message text content
	Unicode bool     // Whether message contains Unicode characters
}

Message represents an SMS message

func (*Message) CalculateSegments

func (m *Message) CalculateSegments() int

CalculateSegments calculates the number of SMS segments needed

func (*Message) EstimateCost

func (m *Message) EstimateCost(costPerSegment float64) float64

EstimateCost estimates the cost of sending the message Note: This is a rough estimate. Actual cost depends on the provider and destination

func (*Message) Validate

func (m *Message) Validate() error

Validate checks if a message is valid

type MessageBirdConfig

type MessageBirdConfig struct {
	APIKey     string // MessageBird API key
	Originator string // Sender name or number
}

MessageBirdConfig contains MessageBird-specific configuration

type NexmoConfig

type NexmoConfig struct {
	APIKey    string // Nexmo API key
	APISecret string // Nexmo API secret
	FromName  string // Sender name or number
}

NexmoConfig contains Nexmo/Vonage-specific configuration

type Provider

type Provider string

Provider represents an SMS service provider

const (
	// ProviderTwilio uses Twilio API
	ProviderTwilio Provider = "twilio"
	// ProviderAWSSNS uses AWS Simple Notification Service
	ProviderAWSSNS Provider = "aws_sns"
	// ProviderNexmo uses Vonage/Nexmo API
	ProviderNexmo Provider = "nexmo"
	// ProviderMessageBird uses MessageBird API
	ProviderMessageBird Provider = "messagebird"
)

type SendResult

type SendResult struct {
	MessageID string    // Unique message identifier
	SentAt    time.Time // Time when SMS was sent
	Provider  Provider  // Provider used to send the SMS
	Status    Status    // Current message status
	Cost      float64   // Cost of sending (if available)
	Segments  int       // Number of SMS segments used
}

SendResult contains the result of an SMS send operation

type Status

type Status string

Status represents the status of an SMS message

const (
	// StatusQueued indicates message is queued for sending
	StatusQueued Status = "queued"
	// StatusSending indicates message is being sent
	StatusSending Status = "sending"
	// StatusSent indicates message was sent successfully
	StatusSent Status = "sent"
	// StatusDelivered indicates message was delivered to recipient
	StatusDelivered Status = "delivered"
	// StatusFailed indicates message failed to send
	StatusFailed Status = "failed"
	// StatusUndelivered indicates message could not be delivered
	StatusUndelivered Status = "undelivered"
)

type TwilioConfig

type TwilioConfig struct {
	AccountSID string // Twilio account SID
	AuthToken  string // Twilio auth token
	FromNumber string // Sender phone number
}

TwilioConfig contains Twilio-specific configuration