{"id":13747300,"url":"https://github.com/twilio/twilio-ruby","last_synced_at":"2026-02-05T14:17:12.709Z","repository":{"id":664424,"uuid":"307486","full_name":"twilio/twilio-ruby","owner":"twilio","description":"A Ruby gem for communicating with the Twilio API and generating TwiML","archived":false,"fork":false,"pushed_at":"2025-05-14T14:33:38.000Z","size":14712,"stargazers_count":1364,"open_issues_count":36,"forks_count":468,"subscribers_count":85,"default_branch":"main","last_synced_at":"2025-05-14T22:05:34.456Z","etag":null,"topics":["twilio","twilio-api","twiml"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twilio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2009-09-15T06:17:02.000Z","updated_at":"2025-05-14T14:33:41.000Z","dependencies_parsed_at":"2023-11-06T23:40:53.704Z","dependency_job_id":"88c0ca6b-978c-45d3-9d6b-badbd15e1f5c","html_url":"https://github.com/twilio/twilio-ruby","commit_stats":{"total_commits":1323,"total_committers":127,"mean_commits":"10.417322834645669","dds":0.8510959939531368,"last_synced_commit":"a3018ec4e10eb89bdd840168f08873611e238dcb"},"previous_names":[],"tags_count":320,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twilio","download_url":"https://codeload.github.com/twilio/twilio-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235687,"owners_count":22036962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["twilio","twilio-api","twiml"],"created_at":"2024-08-03T06:01:24.376Z","updated_at":"2026-02-05T14:17:12.694Z","avatar_url":"https://github.com/twilio.png","language":"Ruby","readme":"# twilio-ruby\n\n[![Tests](https://github.com/twilio/twilio-ruby/actions/workflows/test-and-deploy.yml/badge.svg)][github-actions]\n[![Gem Version](https://img.shields.io/gem/v/twilio-ruby.svg)](https://rubygems.org/gems/twilio-ruby)\n[![Learn with TwilioQuest](https://img.shields.io/static/v1?label=TwilioQuest\u0026message=Learn%20to%20contribute%21\u0026color=F22F46\u0026labelColor=1f243c\u0026style=flat-square\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAMAAAD04JH5AAAASFBMVEUAAAAZGRkcHBwjIyMoKCgAAABgYGBoaGiAgICMjIyzs7PJycnMzMzNzc3UoBfd3d3m5ubqrhfrMEDu7u739/f4vSb/3AD///9tbdyEAAAABXRSTlMAAAAAAMJrBrEAAAKoSURBVHgB7ZrRcuI6EESdyxXGYoNFvMD//+l2bSszRgyUYpFAsXOeiJGmj4NkuWx1Qeh+Ekl9DgEXOBwOx+Px5xyQhDykfgq4wG63MxxaR4ddIkg6Ul3g84vCIcjPBA5gmUMeXESrlukuoK33+33uID8TWeLAdOWsKpJYzwVMB7bOzYSGOciyUlXSn0/ABXTosJ1M1SbypZ4O4MbZuIDMU02PMbauhhHMHXbmebmALIiEbbbbbUrpF1gwE9kFfRNAJaP+FQEXCCTGyJ4ngDrjOFo3jEL5JdqjF/pueR4cCeCGgAtwmuRS6gDwaRiGvu+DMFwSBLTE3+jF8JyuV1okPZ+AC4hDFhCHyHQjdjPHUKFDlHSJkHQXMB3KpSwXNGJPcwwTdZiXlRN0gSp0zpWxNtM0beYE0nRH6QIbO7rawwXaBYz0j78gxjokDuv12gVeUuBD0MDi0OQCLvDaAho4juP1Q/jkAncXqIcCfd+7gAu4QLMACCLxpRsSuQh0igu0C9Svhi7weAGZg50L3IE3cai4IfkNZAC8dfdhsUD3CgKBVC9JE5ABAFzg4QL/taYPAAWrHdYcgfLaIgAXWJ7OV38n1LEF8tt2TH29E+QAoDoO5Ve/LtCQDmKM9kPbvCEBApK+IXzbcSJ0cIGF6e8gpcRhUDogWZ8JnaWjPXc/fNnBBUKRngiHgTUSivSzDRDgHZQOLvBQgf8rRt+VdBUUhwkU6VpJ+xcOwQUqZr+mR0kvBUgv6cB4+37hQAkXqE8PwGisGhJtN4xAHMzrsgvI7rccXqSvKh6jltGlrOHA3Xk1At3LC4QiPdX9/0ndHpGVvTjR4bZA1ypAKgVcwE5vx74ulwIugDt8e/X7JgfkucBMIAr26ndnB4UCLnDOqvteQsHlgX9N4A+c4cW3DXSPbwAAAABJRU5ErkJggg==)](https://twil.io/learn-open-source)\n\n## Documentation\n\nThe documentation for the Twilio API can be found [here][apidocs].\n\nThe individual releases [here][refdocs].\n\n## Versions\n\n`twilio-ruby` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.\n\n### Supported Ruby Versions\n\nThis library supports the following Ruby implementations:\n\n* Ruby 2.4\n* Ruby 2.5\n* Ruby 2.6\n* Ruby 2.7\n* Ruby 3.0\n* Ruby 3.1\n* Ruby 3.2\n\n* JRuby 9.2\n* JRuby 9.3\n* JRuby 9.4\n\n### Migrating from 5.x\n\n[Upgrade Guide][upgrade]\n\n## Installation\n\nTo install using [Bundler][bundler] grab the latest stable version:\n\n```ruby\ngem 'twilio-ruby', '~\u003e 7.10.0'\n```\n\nTo manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install:\n\n```bash\ngem install twilio-ruby -v 7.10.0\n```\n\nTo build and install the development branch yourself from the latest source:\n\n```bash\ngit clone git@github.com:twilio/twilio-ruby.git\ncd twilio-ruby\nmake install\n```\n\n\u003e **Info**\n\u003e If the command line gives you an error message that says Permission Denied, try running the above commands with sudo.\n\u003e\n\u003e For example: `sudo gem install twilio-ruby`\n\n### Test your installation\n\nTo make sure the installation was successful, try sending yourself an SMS message, like this:\n\n```rb\nrequire \"twilio-ruby\"\n\n# Your Account SID and Auth Token from console.twilio.com\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\n\n@client = Twilio::REST::Client.new account_sid, auth_token\nmessage = @client.messages.create(\n  body: \"Hello from Ruby\",\n  to: \"+12345678901\",  # Text this number\n  from: \"+15005550006\", # From a valid Twilio number\n)\n\nputs message.sid\n```\n\n\u003e **Warning**\n\u003e It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.\n\n## Usage\n\n### Authenticate the Client\n\n```ruby\nrequire 'twilio-ruby'\n\n# Your Account SID and Auth Token from console.twilio.com\naccount_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'\nauth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'\n\n# Initialize the Twilio Client with your credentials\n@client = Twilio::REST::Client.new account_sid, auth_token\n```\n\n### Use An API Key\n\n```ruby\nrequire 'twilio-ruby'\n\n# Your Account SID from console.twilio.com\naccount_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'\n# API Key from twilio.com/console/project/api-keys\napi_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz'\napi_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'\n\n# set up a client to talk to the Twilio REST API using an API Key\n@client = Twilio::REST::Client.new api_key_sid, api_key_secret, account_sid\n```\n\n### Specify a Region and/or Edge\n\nTo take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:\n\n```ruby\n# set up a client to talk to the Twilio REST API over a specific region and edge\n@client = Twilio::REST::Client.new account_sid, auth_token, nil, 'au1'\n@client.edge = 'sydney'\n\n# you may also specify the region and/or edge after client creation\n@client = Twilio::REST::Client.new account_sid, auth_token\n@client.region = 'au1'\n@client.edge = 'sydney'\n```\n\nThis will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`.\n\n### Make a Call\n\n```ruby\n@client.calls.create(\n  from: '+14159341234',\n  to: '+16105557069',\n  url: 'http://example.com'\n)\n```\n\n### Send an SMS\n\n```ruby\n@client.messages.create(\n  from: '+14159341234',\n  to: '+16105557069',\n  body: 'Hey there!'\n)\n```\n\n### List your SMS Messages\n\n```ruby\n@client.messages.list(limit: 20)\n```\n\n### Fetch a single SMS message by Sid\n\n```ruby\n# put the message sid you want to retrieve here:\nmessage_sid = 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'\n@client.messages(message_sid).fetch\n```\n\n### Iterate through records\n\nThe library automatically handles paging for you. Collections, such as `calls` and `messages`, have `list` and stream methods that page under the hood. With both `list` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`page_size`). The library will then handle the task for you.\n\n`list` eagerly fetches all records and returns them as a list, whereas `stream` returns an enumerator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.\n\nFor more information about these methods, view the [auto-generated library docs](https://www.twilio.com/docs/libraries/reference/twilio-ruby).\n\n```rb\nrequire 'twilio-ruby'\n\naccount_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'\nauth_token = 'your_auth_token'\n\n@client = Twilio::REST::Client.new(account_sid, auth_token)\n\n@client.calls.list\n       .each do |call|\n         puts call.direction\n       end\n```\n\n### Enable Debug logging\n\nIn order to enable debug logging, pass in a 'logger' instance to the client with the level set to at least 'DEBUG'\n\n```ruby\n@client = Twilio::REST::Client.new account_sid, auth_token\nmyLogger = Logger.new(STDOUT)\nmyLogger.level = Logger::DEBUG\n@client.logger = myLogger\n\n@client = Twilio::REST::Client.new account_sid, auth_token\nmyLogger = Logger.new('my_log.log')\nmyLogger.level = Logger::DEBUG\n@client.logger = myLogger\n```\n\n### Handle Exceptions {#exceptions}\n\nIf the Twilio API returns a 400 or a 500 level HTTP response, the `twilio-ruby`\nlibrary will throw a `Twilio::REST::RestError`. 400-level errors are normal\nduring API operation (`“Invalid number”`, `“Cannot deliver SMS to that number”`,\nfor example) and should be handled appropriately.\n\n```rb\nrequire 'twilio-ruby'\n\naccount_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'\nauth_token = 'your_auth_token'\n\n@client = Twilio::REST::Client.new account_sid, auth_token\n\nbegin\n  messages = @client.messages.list(limit: 20)\nrescue Twilio::REST::RestError =\u003e e\n  puts e.message\nend\n```\n\n### Debug API requests\n\nTo assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.\n\nFor example, you can retrieve the status code of the last response like so:\n\n```ruby\nrequire 'rubygems' # Not necessary with ruby 1.9 but included for completeness\nrequire 'twilio-ruby'\n\n# Your Account SID and Auth Token from console.twilio.com\naccount_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'\nauth_token = 'your_auth_token'\n\n@client = Twilio::REST::Client.new(account_sid, auth_token)\n\n@message = @client.messages.create(\n  to: '+14158675309',\n  from: '+14258675310',\n  body: 'Ahoy!'\n)\n\n# Retrieve the status code of the last response from the HTTP client\nputs @client.http_client.last_response.status_code\n```\n\n### Customize your HTTP Client\n\n`twilio-ruby` uses [Faraday][faraday] to make HTTP requests. You can tell `Twilio::REST::Client` to use any of the Faraday adapters like so:\n\n```ruby\n@client.http_client.adapter = :typhoeus\n```\n\nTo use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md).\n\nTo apply customizations such as middleware, you can use the `configure_connection` method like so:\n\n```ruby\n@client.http_client.configure_connection do |faraday|\n  faraday.use SomeMiddleware\nend\n```\n\n### Get started With Client Capability Tokens\n\nIf you just need to generate a Capability Token for use with Twilio Client, you can do this:\n\n```ruby\nrequire 'twilio-ruby'\n\n# put your own account credentials here:\naccount_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'\nauth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'\n\n# set up\ncapability = Twilio::JWT::ClientCapability.new account_sid, auth_token\n\n# allow outgoing calls to an application\noutgoing_scope = Twilio::JWT::ClientCapability::OutgoingClientScope.new 'AP11111111111111111111111111111111'\ncapability.add_scope(outgoing_scope)\n\n# allow incoming calls to 'andrew'\nincoming_scope = Twilio::JWT::ClientCapability::IncomingClientScope.new 'andrew'\ncapability.add_scope(incoming_scope)\n\n# generate the token string\n@token = capability.to_s\n```\n\nThere is a slightly more detailed document in the [Capability][capability] section of the wiki.\n\n## OAuth Feature for Twilio APIs\nWe are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.\n\nAPI examples [here](https://github.com/twilio/twilio-ruby/blob/main/examples/public_oauth.rb)\n\n### Generate TwiML\n\nTo control phone calls, your application needs to output [TwiML][twiml].\n\nYou can construct a TwiML response like this:\n\n```ruby\nrequire 'twilio-ruby'\n\nresponse = Twilio::TwiML::VoiceResponse.new do |r|\n  r.say(message: 'hello there', voice: 'alice')\n  r.dial(caller_id: '+14159992222') do |d|\n    d.client 'jenny'\n  end\nend\n\n# print the result\nputs response.to_s\n```\n\nThis will print the following (except for the whitespace):\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cResponse\u003e\n  \u003cSay voice=\"alice\"\u003ehello there\u003c/Say\u003e\n  \u003cDial callerId=\"+14159992222\"\u003e\n    \u003cClient\u003ejenny\u003c/Client\u003e\n  \u003c/Dial\u003e\n\u003c/Response\u003e\n```\n\n## Docker Image\n\nThe `Dockerfile` present in this repository and its respective `twilio/twilio-ruby` Docker image are currently used by Twilio for testing purposes only.\n\n## Getting help\n\nIf you need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question.\n\nIf you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!\n\n[apidocs]: https://www.twilio.com/docs/api\n[twiml]: https://www.twilio.com/docs/api/twiml\n[libdocs]: https://www.twilio.com/docs/libraries/reference/twilio-ruby/\n[refdocs]: https://twilio.github.io/twilio-ruby\n[capability]: https://github.com/twilio/twilio-ruby/wiki/JWT-Tokens\n[wiki]: https://github.com/twilio/twilio-ruby/wiki\n[bundler]: https://bundler.io\n[rubygems]: https://rubygems.org\n[gem]: https://rubygems.org/gems/twilio\n[github-actions]: https://github.com/twilio/twilio-ruby/actions/workflows/test-and-deploy.yml\n[upgrade]: https://github.com/twilio/twilio-ruby/wiki/Ruby-Version-5.x-Upgrade-Guide\n[issues]: https://github.com/twilio/twilio-ruby/issues\n[faraday]: https://github.com/lostisland/faraday\n","funding_links":[],"categories":["Third-party APIs","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwilio%2Ftwilio-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwilio%2Ftwilio-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwilio%2Ftwilio-ruby/lists"}