HipcallSMS.Adapters.Telnyx (HipcallSMS v0.3.0)

View Source

An adapter for Telnyx SMS API.

This adapter provides SMS delivery through Telnyx's REST API. It supports messaging profiles, webhooks, auto-detection, and media attachments for MMS.

For reference: Telnyx API docs

Configuration

The Telnyx adapter requires the following configuration:

  • :api_key - Your Telnyx API key

Configuration Examples

# In config/config.exs
config :hipcall_sms,
  adapter: HipcallSMS.Adapters.Telnyx,
  telnyx_api_key: {:system, "TELNYX_API_KEY"}

# Runtime configuration override
config = [
  adapter: HipcallSMS.Adapters.Telnyx,
  api_key: "your_api_key"
]

Provider Options

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

  • :messaging_profile_id - Messaging profile ID to use for sending
  • :webhook_url - URL for delivery status webhooks
  • :webhook_failover_url - Failover URL for webhooks
  • :use_profile_webhooks - Whether to use messaging profile webhooks (default: true)
  • :type - Message type, "SMS" or "MMS" (default: "SMS")
  • :auto_detect - Enable auto-detection of message type
  • :media_urls - Array of media URLs for MMS

Examples

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

# SMS with messaging profile
sms =
  SMS.new(from: "+15551234567", to: "+15555555555", text: "Hello!")
  |> SMS.put_provider_option(:messaging_profile_id, "profile_123")

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

# MMS with media
sms =
  SMS.new(from: "+15551234567", to: "+15555555555", text: "Check this out!")
  |> SMS.put_provider_option(:type, "MMS")
  |> SMS.put_provider_option(:media_urls, ["https://example.com/image.jpg"])

Summary

Functions

Delivers an SMS through Telnyx's REST API.

Gets the account balance from Telnyx's REST API.

Functions

deliver(sms, config \\ [])

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

Delivers an SMS through Telnyx's REST API.

This function sends an SMS message using Telnyx'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: "msg_123",           # Telnyx message ID
  status: "queued",        # Message status
  provider: "telnyx",      # Provider identifier
  provider_response: %{}   # Full Telnyx API response
}

Examples

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

# Delivery with custom config
config = [api_key: "custom_api_key"]
{:ok, response} = deliver(sms, config)

get_balance(config \\ [])

@spec get_balance(Keyword.t()) :: {:ok, map()} | {:error, map()}

Gets the account balance from Telnyx's REST API.

This function retrieves the current account balance using Telnyx's Balance API. It handles authentication and response parsing.

Parameters

  • config - Configuration keyword list (optional, defaults to application config)

Returns

  • {:ok, balance_info} - Success with balance information
  • {:error, reason} - Failure with error details including HTTP status and body

Response Format

Success responses contain normalized balance information:

%{
  balance: "300.00",           # Current account balance
  currency: "USD",             # Currency code
  credit_limit: "100.00",      # Credit limit
  available_credit: "400.00",  # Available credit (balance + credit limit)
  pending: "10.00",            # Pending amount
  provider: "telnyx",          # Provider identifier
  provider_response: %{}       # Full Telnyx API response
}

Examples

# Get balance with application config
{:ok, balance} = get_balance()

# Get balance with custom config
config = [api_key: "custom_api_key"]
{:ok, balance} = get_balance(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.