Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/danielberkompas/ex_twilio
Twilio API client for Elixir
https://github.com/danielberkompas/ex_twilio
elixir hex twilio
Last synced: about 9 hours ago
JSON representation
Twilio API client for Elixir
- Host: GitHub
- URL: https://github.com/danielberkompas/ex_twilio
- Owner: danielberkompas
- License: mit
- Created: 2015-03-27T21:58:14.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-04-28T23:49:28.000Z (8 months ago)
- Last Synced: 2024-12-05T23:05:00.695Z (7 days ago)
- Topics: elixir, hex, twilio
- Language: Elixir
- Homepage:
- Size: 443 KB
- Stars: 337
- Watchers: 12
- Forks: 148
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - Twilio API client for Elixir. (Third Party APIs)
- fucking-awesome-elixir - ex_twilio - Twilio API client for Elixir. (Third Party APIs)
- awesome-elixir - ex_twilio - Twilio API client for Elixir. (Third Party APIs)
README
ExTwilio
========
[](https://hex.pm/packages/ex_twilio)
[](https://danielberkompas.semaphoreci.com/projects/ex_twilio)
[](http://inch-ci.org/github/danielberkompas/ex_twilio)
[](https://hex.pm/packages/xxx)
[](https://hexdocs.pm/ex_twilio/)
[](https://hex.pm/packages/xxx)
[](https://github.com/danielberkompas/xxx/blob/master/LICENSE)
[](https://github.com/danielberkompas/xxx/commits/master)
ExTwilio is a relatively full-featured API client for the Twilio API.
## Installation
ExTwilio is currently beta software. You can install it from Hex:
```elixir
def deps do
[
{:ex_twilio, "~> 0.10.0"}
]
end
```
Or from Github:
```elixir
def deps do
[
{:ex_twilio, github: "danielberkompas/ex_twilio"}
]
end
```
and run `mix deps.get`.
If using Elixir 1.3 or lower add `:ex_twilio` as a application dependency:
```elixir
def application do
[
applications: [:ex_twilio]
]
end
```
## Configuration
You will need to set the following configuration variables in your
`config/config.exs` file:
```elixir
import Config
config :ex_twilio, account_sid: {:system, "TWILIO_ACCOUNT_SID"},
auth_token: {:system, "TWILIO_AUTH_TOKEN"},
workspace_sid: {:system, "TWILIO_WORKSPACE_SID"} # optional
```
For security, I recommend that you use environment variables rather than hard
coding your account credentials. If you don't already have an environment
variable manager, you can create a `.env` file in your project with the
following content:
```bash
export TWILIO_ACCOUNT_SID=
export TWILIO_AUTH_TOKEN=
export TWILIO_WORKSPACE_SID= #optional
```
Then, just be sure to run `source .env` in your shell before compiling your
project.
### Multiple Environments
If you want to use different Twilio credentials for different environments, then
create separate Mix configuration files for each environment. To do this, change
`config/config.exs` to look like this:
```elixir
# config/config.exs
import Config
# shared configuration for all environments here ...
import_config "#{Mix.env}.exs"
```
Then, create a `config/#{environment_name}.exs` file for each environment. You
can then set the `config :ex_twilio` variables differently in each file.
## Usage
ExTwilio comes with a module for each supported Twilio API resource. For example,
the "Call" resource is accessible through the `ExTwilio.Call` module. Depending
on what the underlying API supports, a resource module may have the following
methods:
| Method | Description |
|-------------|-------------------------------------------------------------------|
| **all** | Eager load all of the resource items on all pages. Use with care! |
| **stream** | Create a Stream of all the items. Use like any Stream. |
| **find** | Find a resource given its SID. |
| **create** | Create a resource. |
| **update** | Update a resource. |
| **destroy** | Destroy a resource. |
Resource modules may contain their own custom methods. If the underlying API
endpoint does not support an action, the related method will _not_ be available
on that module.
### Supported Endpoints
ExTwilio currently supports the following Twilio endpoints:
- [Account](https://www.twilio.com/docs/api/2010-04-01/rest/account). Including SubAccounts.
- [Address](https://www.twilio.com/docs/api/2010-04-01/rest/addresses)
- [DependentPhoneNumber](https://www.twilio.com/docs/api/2010-04-01/rest/addresses#instance-subresources)
- [Application](https://www.twilio.com/docs/api/2010-04-01/rest/applications)
- [AuthorizedConnectApp](https://www.twilio.com/docs/api/2010-04-01/rest/authorized-connect-apps)
- [AvailablePhoneNumber](https://www.twilio.com/docs/api/2010-04-01/rest/available-phone-numbers)
- [Call](https://www.twilio.com/docs/api/2010-04-01/rest/call)
- [Feedback](https://www.twilio.com/docs/api/2010-04-01/rest/call-feedback)
- [Conference](https://www.twilio.com/docs/api/2010-04-01/rest/conference)
- [Participant](https://www.twilio.com/docs/api/2010-04-01/rest/participant)
- [ConnectApp](https://www.twilio.com/docs/api/2010-04-01/rest/connect-apps)
- [IncomingPhoneNumber](https://www.twilio.com/docs/api/2010-04-01/rest/incoming-phone-numbers)
- [Message](https://www.twilio.com/docs/api/2010-04-01/rest/message)
- [Media](https://www.twilio.com/docs/api/2010-04-01/rest/media)
- [Notification](https://www.twilio.com/docs/api/notifications/rest)
- [OutgoingCallerId](https://www.twilio.com/docs/api/2010-04-01/rest/outgoing-caller-ids)
- [Queue](https://www.twilio.com/docs/api/2010-04-01/rest/queue)
- [Member](https://www.twilio.com/docs/api/2010-04-01/rest/member)
- [Recording](https://www.twilio.com/docs/api/2010-04-01/rest/recording)
- [ShortCode](https://www.twilio.com/docs/api/2010-04-01/rest/short-codes)
- [Token](https://www.twilio.com/docs/api/2010-04-01/rest/token)
- [Transcription](https://www.twilio.com/docs/api/2010-04-01/rest/transcription)
- [SipCredentialList](https://www.twilio.com/docs/api/2010-04-01/rest/credential-list)
- [SipCredential](https://www.twilio.com/docs/api/rest/credential-list#subresources)
- [SipDomain](https://www.twilio.com/docs/api/2010-04-01/rest/domain)
- [SipIPAccessControlList](https://www.twilio.com/docs/api/2010-04-01/rest/ip-access-control-list)
- [SipIpAddress](https://www.twilio.com/docs/api/rest/ip-access-control-list#subresources)
Twilio's Lookup Rest API:
- [Lookup](https://www.twilio.com/docs/api/lookups)
Twilio's TaskRouter API:
- [Overview](https://www.twilio.com/docs/api/taskrouter/rest-api)
- [Activites](https://www.twilio.com/docs/api/taskrouter/activities)
- [Events](https://www.twilio.com/docs/api/taskrouter/events)
- [Task Channels](https://www.twilio.com/docs/api/taskrouter/rest-api-task-channel)
- [Tasks](https://www.twilio.com/docs/api/taskrouter/tasks)
- [Reservations](https://www.twilio.com/docs/api/taskrouter/reservations)
- [TaskQueues](https://www.twilio.com/docs/api/taskrouter/taskqueues)
- [Statistics](https://www.twilio.com/docs/api/taskrouter/taskqueue-statistics)
- [Workers](https://www.twilio.com/docs/api/taskrouter/workers)
- [Channels](https://www.twilio.com/docs/api/taskrouter/rest-api-workerchannel)
- [Statistics](https://www.twilio.com/docs/api/taskrouter/worker-statistics)
- [Workflows](https://www.twilio.com/docs/api/taskrouter/workflows)
- [Statistics](https://www.twilio.com/docs/api/taskrouter/workflow-statistics)
- [Workspaces](https://www.twilio.com/docs/api/taskrouter/workspaces)
- [Statistics](https://www.twilio.com/docs/api/taskrouter/workspace-statistics)
Twilio's ProgrammableChat API:
- [Overview](https://www.twilio.com/docs/api/chat/rest)
- [Services](https://www.twilio.com/docs/api/chat/rest/services)
- [Channels](https://www.twilio.com/docs/api/chat/rest/channels)
- [Members](https://www.twilio.com/docs/api/chat/rest/members)
- [Users](https://www.twilio.com/docs/api/chat/rest/users)
- [UserChannels](https://www.twilio.com/docs/api/chat/rest/user-channels)
- [Roles](https://www.twilio.com/docs/api/chat/rest/user-channels)
- [Credentials](https://www.twilio.com/docs/api/chat/rest/credentials)
Twilio Capability Tokens:
- [Worker](https://www.twilio.com/docs/api/taskrouter/worker-js)
- [Calling](https://www.twilio.com/docs/api/client/capability-tokens) (Deprecated, use Access Token instead)
Twilio Access Token Grants:
- [Chat](https://www.twilio.com/docs/chat/identity)
- [Voice](https://www.twilio.com/docs/iam/access-tokens)
- [Video](https://www.twilio.com/docs/video/tutorials/user-identity-access-tokens#about-access-tokens)
### Example
```elixir
# Get all the calls in the Call endpoint. Be warned, this will block
# until all the pages of calls have been fetched.
calls = ExTwilio.Call.all
# Create a stream of all the calls
stream = ExTwilio.Call.stream
# Lazily filter calls by duration, then map to get only their SIDs
stream
|> Stream.filter(fn(call) -> call.duration > 120 end)
|> Stream.map(fn(call) -> call.sid end)
|> Enum.into([]) # Only here does any work happen.
# => ["CAc14d7...", "CA649ea861..."]
# Find a call
{:ok, call} = ExTwilio.Call.find("CA13a9c7f80c6f3761fabae43242b5b6c6")
inspect(call)
# %ExTwilio.Call{
# account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
# answered_by: nil, caller_name: "",
# date_created: "Sat, 14 Mar 2015 14:27:38 +0000",
# date_updated: "Sat, 14 Mar 2015 14:28:35 +0000",
# direction: "outbound-api",
# duration: "52",
# end_time: "Sat, 14 Mar 2015 14:28:35 +0000",
# forwarded_from: nil,
# from: "+1xxxxxxxxxx",
# parent_call_sid: nil,
# phone_number_sid: "",
# price: "-0.01500",
# price_unit: "USD",
# sid: "CA13a9c7f80c6f3761fabae43242b5b6c6",
# start_time: "Sat, 14 Mar 2015 14:27:43 +0000",
# status: "completed",
# to: "+1xxxxxxxxxx",
# uri: "/2010-04-01/Accounts/ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/Calls/CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.json"
# }
# Update a call
call = ExTwilio.Call.update(call, status: "canceled")
# Get a call's recordings. This pattern is repeated wherever you are
# getting a nested resource.
recordings = ExTwilio.Recording.all(call: call.sid)
# Destroy a call
ExTwilio.Call.destroy(call)
```
For more in-depth documentation, see the generated docs for each module.
### Making and Receiving Calls
See the [CALLING_TUTORIAL.md](CALLING_TUTORIAL.md) file for instructions on
making and receiving calls from the browser with ExTwilio.
### Sending SMS messages
Please look at `ExTwilio.Message`
## Contributing
See the [CONTRIBUTING.md](CONTRIBUTING.md) file for contribution guidelines.
## Copyright and License
Copyright (c) 2015 Daniel Berkompas
ExTwilio is licensed under the MIT license. For more details, see the `LICENSE`
file at the root of the repository. It depends on Elixir, which is under the
Apache 2 license.
Twilio™ is trademark of Twilio, Inc.