- Notifications
You must be signed in to change notification settings - Fork472
A Ruby gem for communicating with the Twilio API and generating TwiML
License
twilio/twilio-ruby
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
The documentation for the Twilio API can be foundhere.
The individual releaseshere.
twilio-ruby uses a modified version ofSemantic Versioning for all changes.See this document for details.
This library supports the following Ruby implementations:
Ruby 2.4
Ruby 2.5
Ruby 2.6
Ruby 2.7
Ruby 3.0
Ruby 3.1
Ruby 3.2
JRuby 9.2
JRuby 9.3
JRuby 9.4
To install usingBundler grab the latest stable version:
gem'twilio-ruby','~> 7.6.5'
To manually installtwilio-ruby viaRubygems simply gem install:
gem install twilio-ruby -v 7.6.5
To build and install the development branch yourself from the latest source:
git clone git@github.com:twilio/twilio-ruby.gitcd twilio-rubymake installInfoIf the command line gives you an error message that says Permission Denied, try running the above commands with sudo.
For example:
sudo gem install twilio-ruby
To make sure the installation was successful, try sending yourself an SMS message, like this:
require"twilio-ruby"# Your Account SID and Auth Token from console.twilio.comaccount_sid="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"auth_token="your_auth_token"@client=Twilio::REST::Client.newaccount_sid,auth_tokenmessage=@client.messages.create(body:"Hello from Ruby",to:"+12345678901",# Text this numberfrom:"+15005550006",# From a valid Twilio number)putsmessage.sid
WarningIt'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 outHow to Set Environment Variables for more information.
require'twilio-ruby'# Your Account SID and Auth Token from console.twilio.comaccount_sid='ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'auth_token='yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'# Initialize the Twilio Client with your credentials@client=Twilio::REST::Client.newaccount_sid,auth_token
require'twilio-ruby'# Your Account SID from console.twilio.comaccount_sid='ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'# API Key from twilio.com/console/project/api-keysapi_key_sid='zzzzzzzzzzzzzzzzzzzzzz'api_key_secret='yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'# set up a client to talk to the Twilio REST API using an API Key@client=Twilio::REST::Client.newapi_key_sid,api_key_secret,account_sid
To take advantage of Twilio'sGlobal Infrastructure, specify the target Region and/or Edge for the client:
# set up a client to talk to the Twilio REST API over a specific region and edge@client=Twilio::REST::Client.newaccount_sid,auth_token,nil,'au1'@client.edge='sydney'# you may also specify the region and/or edge after client creation@client=Twilio::REST::Client.newaccount_sid,auth_token@client.region='au1'@client.edge='sydney'
This will result in thehostname transforming fromapi.twilio.com toapi.sydney.au1.twilio.com.
@client.calls.create(from:'+14159341234',to:'+16105557069',url:'http://example.com')
@client.messages.create(from:'+14159341234',to:'+16105557069',body:'Hey there!')
@client.messages.list(limit:20)
# put the message sid you want to retrieve here:message_sid='SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'@client.messages(message_sid).fetch
The library automatically handles paging for you. Collections, such ascalls andmessages, havelist 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.
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.
For more information about these methods, view the auto-generated library docs.
require'twilio-ruby'account_sid='ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'auth_token='your_auth_token'@client=Twilio::REST::Client.new(account_sid,auth_token)@client.calls.list.eachdo |call|putscall.directionend
In order to enable debug logging, pass in a 'logger' instance to the client with the level set to at least 'DEBUG'
@client=Twilio::REST::Client.newaccount_sid,auth_tokenmyLogger=Logger.new(STDOUT)myLogger.level=Logger::DEBUG@client.logger=myLogger@client=Twilio::REST::Client.newaccount_sid,auth_tokenmyLogger=Logger.new('my_log.log')myLogger.level=Logger::DEBUG@client.logger=myLogger
If the Twilio API returns a 400 or a 500 level HTTP response, thetwilio-rubylibrary will throw aTwilio::REST::RestError. 400-level errors are normalduring API operation (“Invalid number”,“Cannot deliver SMS to that number”,for example) and should be handled appropriately.
require'twilio-ruby'account_sid='ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'auth_token='your_auth_token'@client=Twilio::REST::Client.newaccount_sid,auth_tokenbeginmessages=@client.messages.list(limit:20)rescueTwilio::REST::RestError=>eputse.messageend
To 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.
For example, you can retrieve the status code of the last response like so:
require'rubygems'# Not necessary with ruby 1.9 but included for completenessrequire'twilio-ruby'# Your Account SID and Auth Token from console.twilio.comaccount_sid='ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'auth_token='your_auth_token'@client=Twilio::REST::Client.new(account_sid,auth_token)@message=@client.messages.create(to:'+14158675309',from:'+14258675310',body:'Ahoy!')# Retrieve the status code of the last response from the HTTP clientputs@client.http_client.last_response.status_code
twilio-ruby usesFaraday to make HTTP requests. You can tellTwilio::REST::Client to use any of the Faraday adapters like so:
@client.http_client.adapter=:typhoeus
To use a custom HTTP client with this helper library, please see theadvanced example of how to do so.
To apply customizations such as middleware, you can use theconfigure_connection method like so:
@client.http_client.configure_connectiondo |faraday|faraday.useSomeMiddlewareend
If you just need to generate a Capability Token for use with Twilio Client, you can do this:
require'twilio-ruby'# put your own account credentials here:account_sid='ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'auth_token='yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'# set upcapability=Twilio::JWT::ClientCapability.newaccount_sid,auth_token# allow outgoing calls to an applicationoutgoing_scope=Twilio::JWT::ClientCapability::OutgoingClientScope.new'AP11111111111111111111111111111111'capability.add_scope(outgoing_scope)# allow incoming calls to 'andrew'incoming_scope=Twilio::JWT::ClientCapability::IncomingClientScope.new'andrew'capability.add_scope(incoming_scope)# generate the token string@token=capability.to_s
There is a slightly more detailed document in theCapability section of the wiki.
We are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.
API exampleshere
To control phone calls, your application needs to outputTwiML.
You can construct a TwiML response like this:
require'twilio-ruby'response=Twilio::TwiML::VoiceResponse.newdo |r|r.say(message:'hello there',voice:'alice')r.dial(caller_id:'+14159992222')do |d|d.client'jenny'endend# print the resultputsresponse.to_s
This will print the following (except for the whitespace):
<?xml version="1.0" encoding="UTF-8"?><Response> <Sayvoice="alice">hello there</Say> <DialcallerId="+14159992222"> <Client>jenny</Client> </Dial></Response>
TheDockerfile present in this repository and its respectivetwilio/twilio-ruby Docker image are currently used by Twilio for testing purposes only.
If you need help installing or using the library, please check theTwilio Support Help Center first, andfile a support ticket if you don't find an answer to your question.
If 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!
About
A Ruby gem for communicating with the Twilio API and generating TwiML
Topics
Resources
License
Code of conduct
Uh oh!
There was an error while loading.Please reload this page.