# Getting Started
## Installation
Add `twilio_elixir` to your dependencies in `mix.exs`:
```elixir
def deps do
[
{:twilio_elixir, "~> 0.1.0"}
]
end
```
Requires Elixir 1.19+ and OTP 27+.
## Configuration
Add your Twilio credentials to your application config. The recommended
pattern is to use `config/dev.exs` for test credentials and
`config/runtime.exs` for production:
```elixir
# config/dev.exs
import Config
config :twilio_elixir,
account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
auth_token: "your_test_auth_token"
```
```elixir
# config/runtime.exs
import Config
if config_env() == :prod do
config :twilio_elixir,
account_sid: System.fetch_env!("TWILIO_ACCOUNT_SID"),
auth_token: System.fetch_env!("TWILIO_AUTH_TOKEN")
end
```
### All Config Options
The only required keys are `:account_sid` and `:auth_token`. Everything else
has sensible defaults:
```elixir
config :twilio_elixir,
# Required
account_sid: "ACxxx",
auth_token: "your_auth_token",
# Optional — all have defaults if omitted
region: "ie1", # Twilio region (default: nil — US)
edge: "dublin", # Twilio edge location (default: nil)
max_retries: 3 # retry attempts (default: 0 — no retry)
```
| Key | Default | Description |
|-----|---------|-------------|
| `:account_sid` | required | Twilio Account SID (`ACxxx`) |
| `:auth_token` | required | Twilio Auth Token |
| `:region` | `nil` | Twilio region (e.g. `"us1"`, `"ie1"`, `"au1"`) |
| `:edge` | `nil` | Twilio edge location (e.g. `"ashburn"`, `"dublin"`, `"sydney"`) |
| `:max_retries` | `0` | Max retry attempts for failed requests |
## Creating a Client
Once configured, create a client with no arguments — it reads from your config
automatically:
```elixir
client = Twilio.client()
```
### Explicit Credentials
For multi-tenant apps or subaccounts, pass credentials directly:
```elixir
client = Twilio.client("ACxxx", "auth_token_xxx")
```
### With Options
Override config values for a specific client:
```elixir
client = Twilio.client("ACxxx", "auth_token_xxx",
max_retries: 3,
region: "ie1",
edge: "dublin"
)
```
### Subaccounts
To make calls on behalf of a subaccount, pass the subaccount SID as the
`:account_sid` option while authenticating with the parent credentials:
```elixir
client = Twilio.client("ACparent_sid", "parent_auth_token",
account_sid: "ACsubaccount_sid"
)
```
### Config Precedence
Options are resolved in this order (highest wins):
1. Explicit arguments to `client/2` or `client/3`
2. Application config (`config :twilio_elixir, ...`)
3. Struct defaults (e.g. `max_retries: 0`)
Clients are plain structs with no global state — safe for concurrent use
with multiple accounts.
## Making API Calls
Service modules map to Twilio's API resources. Each method takes the client
as the first argument:
```elixir
# Send a message
{:ok, message} = Twilio.Api.V2010.MessageService.create(client, %{
"To" => "+15551234567",
"From" => "+15559876543",
"Body" => "Hello from Elixir!"
})
# Fetch a call
{:ok, call} = Twilio.Api.V2010.CallService.fetch(client, "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
# List recent messages
{:ok, page} = Twilio.Api.V2010.MessageService.list(client, %{"PageSize" => "20"})
```
### Service Module Naming
Service modules follow the pattern `Twilio.<Product>.<Version>.<Resource>Service`:
| Twilio Product | Example Module |
|---------------|----------------|
| Core API | `Twilio.Api.V2010.MessageService` |
| Messaging | `Twilio.Messaging.V1.ServiceService` |
| Verify | `Twilio.Verify.V2.ServiceService` |
| Conversations | `Twilio.Conversations.V1.ConversationService` |
| Voice | `Twilio.Voice.V1.SourceIpMappingService` |
This mirrors Twilio's internal Domain/Version/Resource hierarchy.
## Typed Responses
API responses are automatically deserialized into typed Elixir structs:
```elixir
message.sid #=> "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
message.status #=> "queued"
message.body #=> "Hello from Elixir!"
message.__struct__ #=> Twilio.Resources.Api.V2010.Message
```
## Error Handling
All API errors return `{:error, %Twilio.Error{}}`:
```elixir
case Twilio.Api.V2010.MessageService.create(client, params) do
{:ok, message} ->
IO.puts("Sent: #{message.sid}")
{:error, %Twilio.Error{code: 21211} = err} ->
IO.puts("Invalid 'To' number: #{err.message}")
{:error, %Twilio.Error{code: 21608}} ->
IO.puts("Unverified number — add it in the Twilio console")
{:error, err} ->
IO.puts("Error #{err.code}: #{err.message}")
end
```
Common Twilio error codes:
| Code | Meaning |
|------|---------|
| 20003 | Authentication failure |
| 20404 | Resource not found |
| 20429 | Too many requests (rate limited) |
| 21211 | Invalid "To" phone number |
| 21608 | Unverified phone number |
| 30006 | Landline or unreachable carrier |
## Pagination
### Single Page
```elixir
{:ok, page} = Twilio.Api.V2010.MessageService.list(client, %{"PageSize" => "50"})
page.items #=> [%Twilio.Resources.Api.V2010.Message{}, ...]
```
### Auto-Paging Stream
Lazily iterate through all pages:
```elixir
client
|> Twilio.Api.V2010.MessageService.stream(%{"PageSize" => "100"})
|> Stream.filter(fn msg -> msg.status == "delivered" end)
|> Stream.take(500)
|> Enum.to_list()
```
The stream handles both Twilio pagination formats (v2010 flat and v1/v2/v3
meta wrapper) transparently.
## Updating and Deleting
```elixir
# Update
{:ok, updated} = Twilio.Api.V2010.MessageService.update(client, "SMxxx", %{
"Body" => ""
})
# Delete (returns :ok on success)
:ok = Twilio.Api.V2010.MessageService.delete(client, "SMxxx")
```
## Response Metadata
Access HTTP status, headers, and request ID by passing `return_response: true`
as an option to the client request:
```elixir
{:ok, message, response} = Twilio.Api.V2010.MessageService.fetch(
client, "SMxxx", return_response: true
)
response.status #=> 200
response.request_id #=> "RQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
response.headers #=> [{"content-type", "application/json"}, ...]
```
## Retries
Failed requests (429, 5xx, connection errors) can be automatically retried
with exponential backoff and jitter:
```elixir
# Via config
config :twilio_elixir, max_retries: 3
# Or per-client
client = Twilio.client("ACxxx", "token", max_retries: 3)
```
When retries are enabled on POST requests, an idempotency token
(`I-Twilio-Idempotency-Token`) is automatically generated and reused across
retry attempts to prevent duplicate creates.
The library also respects the `Retry-After` header on 429 responses, waiting
the server-specified duration before retrying.
## Next Steps
- [Webhooks](webhooks.md) — verify incoming Twilio requests
- [TwiML](twiml.md) — generate XML responses for voice and messaging
- [Testing](testing.md) — stub HTTP requests in your test suite
- [Telemetry](telemetry.md) — observability and metrics
