HipcallSMS.Adapters.Twilio (HipcallSMS v0.2.0)
View SourceAn 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
Delivers an SMS through Twilio's REST API.
Callback implementation for HipcallSMS.Adapter.get_config_value/2
.
Callback implementation for HipcallSMS.Adapter.validate_config/1
.
Callback implementation for HipcallSMS.Adapter.validate_dependency/0
.
Functions
@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 detailsconfig
- 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)
Callback implementation for HipcallSMS.Adapter.get_config_value/2
.
Callback implementation for HipcallSMS.Adapter.validate_config/1
.
Callback implementation for HipcallSMS.Adapter.validate_dependency/0
.