HipcallSMS (HipcallSMS v0.2.0)

View Source

HipcallSMS 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!")

Summary

Functions

Delivers an SMS using the configured adapter.

Quick function to send an SMS without creating an SMS struct first.

Returns the current version of HipcallSMS.

Types

config()

@type config() :: Keyword.t()

delivery_result()

@type delivery_result() :: {:ok, map()} | {:error, map()}

Functions

deliver(sms, config \\ [])

@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 - A HipcallSMS.SMS struct containing the message details
  • config - 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

send_sms(from, to, text, config \\ [])

@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 content
  • config - 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

version()

@spec version() :: String.t()

Returns the current version of HipcallSMS.

Examples

iex> HipcallSMS.version()
"0.2.0"