HipcallSMS.Adapters.Telnyx (HipcallSMS v0.2.0)
View SourceAn 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.
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 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 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: "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)
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
.