HipcallSMS (HipcallSMS v0.3.0)
View SourceHipcallSMS is a unified SMS library for sending SMS messages through multiple providers.
Supported providers:
- Telnyx
- Twilio
- Iletimerkezi
Configuration
You can configure providers in your config.exs
:
config :hipcall_sms,
adapter: HipcallSMS.Adapters.Telnyx,
telnyx_api_key: {:system, "TELNYX_API_KEY"},
twilio_account_sid: {:system, "TWILIO_ACCOUNT_SID"},
twilio_auth_token: {:system, "TWILIO_AUTH_TOKEN"},
iletimerkezi_key: {:system, "ILETIMERKEZI_KEY"},
iletimerkezi_hash: {:system, "ILETIMERKEZI_HASH"}
Usage
# Create and send an SMS
sms =
HipcallSMS.SMS.new()
|> HipcallSMS.SMS.from("+15551234567")
|> HipcallSMS.SMS.to("+15555555555")
|> HipcallSMS.SMS.text("Hello from HipcallSMS!")
HipcallSMS.deliver(sms)
# Or with configuration override
config = [
adapter: HipcallSMS.Adapters.Twilio,
account_sid: "your_account_sid",
auth_token: "your_auth_token"
]
HipcallSMS.deliver(sms, config)
# Quick send
HipcallSMS.send_sms("+15551234567", "+15555555555", "Hello!")
# Check account balance
{:ok, balance} = HipcallSMS.get_balance()
IO.puts("Current balance: " <> balance.balance <> " " <> balance.currency)
Summary
Functions
Delivers an SMS using the configured adapter.
Gets the account balance from the configured SMS provider.
Quick function to send an SMS without creating an SMS struct first.
Returns the current version of HipcallSMS.
Types
Functions
@spec deliver(HipcallSMS.SMS.t(), config()) :: delivery_result()
Delivers an SMS using the configured adapter.
This function takes an SMS struct and optional configuration to send the message through the specified provider. If no configuration is provided, it uses the application configuration.
Parameters
sms
- AHipcallSMS.SMS
struct containing the message detailsconfig
- Optional keyword list to override adapter configuration
Returns
{:ok, response}
- Success with provider response containing message ID and status{:error, reason}
- Failure with error details
Examples
# Basic usage with application config
sms = SMS.new(from: "+15551234567", to: "+15555555555", text: "Hello!")
{:ok, response} = HipcallSMS.deliver(sms)
# => {:ok, %{id: "msg_123", status: "queued", provider: "twilio"}}
# With configuration override for Twilio
config = [
adapter: HipcallSMS.Adapters.Twilio,
account_sid: "ACxxxxx",
auth_token: "your_auth_token"
]
{:ok, response} = HipcallSMS.deliver(sms, config)
# With configuration override for Telnyx
config = [
adapter: HipcallSMS.Adapters.Telnyx,
api_key: "your_api_key"
]
{:ok, response} = HipcallSMS.deliver(sms, config)
# With configuration override for Iletimerkezi
config = [
adapter: HipcallSMS.Adapters.Iletimerkezi,
key: "your_key",
hash: "your_hash"
]
{:ok, response} = HipcallSMS.deliver(sms, config)
Error Handling
case HipcallSMS.deliver(sms) do
{:ok, response} ->
IO.puts("Message sent with ID: " <> response.id)
{:error, %{status: 401}} ->
IO.puts("Authentication failed")
{:error, %{status: 400, body: body}} ->
IO.puts("Bad request: " <> inspect(body))
{:error, reason} ->
IO.puts("Failed to send: " <> inspect(reason))
end
Gets the account balance from the configured SMS provider.
This function retrieves the current account balance information from the provider's API. The response format may vary between providers but will be normalized to include common balance information.
Parameters
config
- Optional keyword list to override adapter configuration
Returns
{:ok, balance_info}
- Success with balance information map{:error, reason}
- Failure with error details
Examples
# Get balance with application config
{:ok, balance} = HipcallSMS.get_balance()
# With Telnyx configuration override
config = [
adapter: HipcallSMS.Adapters.Telnyx,
api_key: "your_api_key"
]
{:ok, balance} = HipcallSMS.get_balance(config)
# => {:ok, %{balance: "300.00", currency: "USD", credit_limit: "100.00", ...}}
# With Iletimerkezi configuration override
config = [
adapter: HipcallSMS.Adapters.Iletimerkezi,
key: "your_key",
hash: "your_hash"
]
{:ok, balance} = HipcallSMS.get_balance(config)
# => {:ok, %{balance: "0", sms_balance: "18343", currency: "TRY", ...}}
Error Handling
case HipcallSMS.get_balance() do
{:ok, balance} ->
IO.puts("Current balance: " <> balance.balance <> " " <> balance.currency)
{:error, %{status: 401}} ->
IO.puts("Authentication failed")
{:error, %{status: 400, body: body}} ->
IO.puts("Bad request: " <> inspect(body))
{:error, reason} ->
IO.puts("Failed to get balance: " <> inspect(reason))
end
@spec send_sms(String.t(), String.t(), String.t(), config()) :: delivery_result()
Quick function to send an SMS without creating an SMS struct first.
This is a convenience function that creates an SMS struct internally and delivers it using the specified or configured adapter.
Parameters
from
- The sender phone number (E.164 format recommended)to
- The recipient phone number (E.164 format recommended)text
- The message contentconfig
- Optional keyword list to override adapter configuration
Returns
{:ok, response}
- Success with provider response{:error, reason}
- Failure with error details
Examples
# Basic usage
{:ok, response} = HipcallSMS.send_sms("+15551234567", "+15555555555", "Hello!")
# With Twilio configuration override
config = [
adapter: HipcallSMS.Adapters.Twilio,
account_sid: "ACxxxxx",
auth_token: "your_auth_token"
]
{:ok, response} = HipcallSMS.send_sms("+15551234567", "+15555555555", "Hello!", config)
# Sending a longer message
message = "This is a longer SMS message that demonstrates sending multi-part messages through HipcallSMS."
{:ok, response} = HipcallSMS.send_sms("+15551234567", "+15555555555", message)
# International numbers
{:ok, response} = HipcallSMS.send_sms("+442071234567", "+33123456789", "Hello from UK to France!")
Error Handling
case HipcallSMS.send_sms("+15551234567", "+15555555555", "Hello!") do
{:ok, response} ->
IO.puts("SMS sent successfully")
{:error, reason} ->
IO.puts("Failed to send SMS")
end
@spec version() :: String.t()
Returns the current version of HipcallSMS.
Examples
iex> HipcallSMS.version()
"0.3.0"