HipcallSMS.Adapters.Twilio (HipcallSMS v0.3.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.
Gets the account balance from Twilio.
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)
Gets the account balance from Twilio.
Note: Twilio does not provide a simple balance endpoint like other providers. This function returns an error indicating that balance checking is not supported for Twilio through this adapter.
For Twilio balance information, you would need to use their Account API or check your Twilio Console.
Parameters
config
- Configuration keyword list (ignored)
Returns
{:error, reason}
- Always returns an error as this feature is not supported
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
.