HipcallSMS.Adapters.Twilio (HipcallSMS v0.2.0)

View Source

An adapter for Twilio SMS API.

This adapter provides SMS delivery through Twilio's REST API. It supports all major Twilio SMS features including messaging services, status callbacks, scheduling, and media attachments.

For reference: Twilio API docs

Configuration

The Twilio adapter requires the following configuration:

  • :account_sid - Your Twilio Account SID
  • :auth_token - Your Twilio Auth Token

Configuration Examples

# In config/config.exs
config :hipcall_sms,
  adapter: HipcallSMS.Adapters.Twilio,
  twilio_account_sid: {:system, "TWILIO_ACCOUNT_SID"},
  twilio_auth_token: {:system, "TWILIO_AUTH_TOKEN"}

# Runtime configuration override
config = [
  adapter: HipcallSMS.Adapters.Twilio,
  account_sid: "ACxxxxx",
  auth_token: "your_auth_token"
]

Provider Options

The Twilio adapter supports the following provider-specific options via provider_options:

  • :messaging_service_sid - Use a Twilio Messaging Service
  • :status_callback - URL for delivery status webhooks
  • :media_url - URL for MMS media attachments
  • :max_price - Maximum price per message
  • :validity_period - Message validity period in seconds
  • :send_at - Schedule message for future delivery
  • :smart_encoded - Enable smart encoding
  • :shorten_urls - Enable URL shortening

Examples

# Basic SMS
sms = SMS.new(from: "+15551234567", to: "+15555555555", text: "Hello!")
{:ok, response} = HipcallSMS.deliver(sms)

# SMS with messaging service
sms =
  SMS.new(to: "+15555555555", text: "Hello!")
  |> SMS.put_provider_option(:messaging_service_sid, "MGxxxxx")

# SMS with status callback
sms =
  SMS.new(from: "+15551234567", to: "+15555555555", text: "Hello!")
  |> SMS.put_provider_option(:status_callback, "https://example.com/webhook")

# Scheduled SMS
send_at = DateTime.utc_now() |> DateTime.add(3600, :second) |> DateTime.to_iso8601()
sms =
  SMS.new(from: "+15551234567", to: "+15555555555", text: "Reminder!")
  |> SMS.put_provider_option(:send_at, send_at)

Summary

Functions

deliver(sms, config \\ [])

@spec deliver(HipcallSMS.SMS.t(), Keyword.t()) :: {:ok, map()} | {:error, map()}

Delivers an SMS through Twilio's REST API.

This function sends an SMS message using Twilio's Messages API. It handles authentication, request formatting, and response parsing.

Parameters

  • sms - The SMS struct containing message details
  • config - Configuration keyword list (optional, defaults to application config)

Returns

  • {:ok, response} - Success with normalized response containing message ID and status
  • {:error, reason} - Failure with error details including HTTP status and body

Response Format

Success responses are normalized to:

%{
  id: "SMxxxxx",           # Twilio message SID
  status: "queued",        # Message status
  provider: "twilio",      # Provider identifier
  provider_response: %{}   # Full Twilio API response
}

Examples

# Basic delivery
sms = SMS.new(from: "+15551234567", to: "+15555555555", text: "Hello!")
{:ok, response} = deliver(sms)
# => {:ok, %{id: "SMxxxxx", status: "queued", provider: "twilio"}}

# Delivery with custom config
config = [account_sid: "ACxxxxx", auth_token: "custom_token"]
{:ok, response} = deliver(sms, config)

get_config_value(key, default)

Callback implementation for HipcallSMS.Adapter.get_config_value/2.

validate_config(config)

Callback implementation for HipcallSMS.Adapter.validate_config/1.

validate_dependency()

Callback implementation for HipcallSMS.Adapter.validate_dependency/0.