DOCSEARCHbyAlgolia
Submit Docs

twilio-ruby

repository·main·Indexed 23 days ago

https://github.com/twilio/twilio-ruby

The official Ruby helper library for the Twilio API. It enables developers to programmatically make calls, send SMS, manage Twilio resources, and generate TwiML. The library includes the Twilio::REST::Client for API interactions, Twilio::TwiML for markup generation, and support for custom HTTP clients via Faraday for proxy configurations and advanced request handling.

Tokens
11.5K
Snippets
13
Records
62
Agent score
80%

What's inside twilio-ruby

  1. How paging works with list and stream

    main

    The library automatically handles pagination for collections like calls and messages.

    • list: Eagerly fetches all records (up to the specified limit) and returns them as an array.
    • stream: Returns an enumerator that lazily retrieves pages of records as you iterate over the collection.

    You can control the number of records retrieved via limit and the size of each individual page fetch via page_size.

    Example of iterating through records using list:

    @client.calls.list.each do |call|
  puts call.direction
end
    require 'twilio-ruby'

account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio::REST::Client.new(account_sid, auth_token)

@client.calls.list
       .each do |call|
         puts call.direction
       end

  2. Implement a custom HTTP client for proxy support

    main

    To implement a custom HTTP client, your class must respond to the request method. This method is called by the Twilio library with the following signature:

    request(host, port, method, url, params = {}, data = {}, headers = {}, auth = nil, timeout = nil)

    Inside this method, you can use any HTTP library (the Twilio library uses Faraday internally) to execute the request. A common use case is configuring a proxy using the proxy_prot, proxy_addr, and proxy_port parameters.

    class MyRequestClass
  def initialize(proxy_prot = nil, proxy_addr = nil, proxy_port = nil, timeout: nil)
    @proxy_prot = proxy_prot
    @proxy_addr = proxy_addr
    @proxy_port = proxy_port
    @timeout = timeout
    @adapter = Faraday.default_adapter
  end

  def request(host, port, method, url, params = {}, data = {}, headers = {}, auth = nil, timeout = nil)
    # Implementation logic using Faraday or another HTTP library
    # ...
  end
end

  3. Understand the twilio-ruby versioning strategy

    main

    The twilio-ruby library follows a modified Semantic Versioning (MAJOR.MINOR.PATCH) pattern. To ensure stability, it is strongly recommended to pin your dependency to at least a specific major version, and potentially a specific minor version, to prevent unexpected breaking changes during updates.

    • PATCH (MAJOR.MINOR.PATCH): Incremented for backwards-compatible bug fixes. These are generally safe to upgrade.
    • MINOR (MAJOR.MINOR.PATCH): Incremented when new features are added in a backwards-compatible way or when small breaking changes (like function signature changes) are introduced. Upgrading may require manual code adjustments.
    • MAJOR (MAJOR.MINOR.PATCH): Incremented for significant breaking changes that require extensive code reworking. New major versions are communicated in advance via Release Candidates.

  4. Identify supported versions of twilio-ruby

    main
    Twilio only provides support for the current MAJOR version of twilio-ruby. New features, bug fixes, and security updates are exclusively applied to the most recent major version. If you are using an older major version, you should plan an upgrade to the current one to continue receiving updates.

  5. Use a custom HTTP client with Twilio::REST::Client

    main

    By default, Twilio::REST::Client uses a default Twilio::Http::Client to make requests. If you need to modify HTTP requests—for example, to connect through an enterprise proxy server, add custom headers, or mock API responses for testing—you can provide your own implementation of an HTTP client during initialization.

    To use a custom client, pass it as the fifth argument to the Twilio::REST::Client.new constructor. The constructor signature follows this order: account_sid, auth_token, region, edge, and http_client.

  6. Migrate Chat Message creation from 5.x.x to 5.3.x

    main

    In version 5.3.x, the Body parameter for creating Chat messages is no longer required as a positional argument. This change was made to support sending media in Chat messages, allowing users to provide either a body or a media_sid.

    When upgrading from 5.x.x to 5.3.x, you must switch from passing the body as a positional argument to using the body: keyword argument.

  7. Install twilio-ruby

    main

    You can install the twilio-ruby library using Bundler, Rubygems, or by building from the source code.

    Using Bundler Add this to your Gemfile:

    gem 'twilio-ruby', '~> 7.10.7'

    Using Rubygems Run the following command in your terminal:

    gem install twilio-ruby -v 7.10.7

    Building from source

    git clone git@github.com:twilio/twilio-ruby.git
cd twilio-ruby
make install

  8. Authenticate the Twilio Client

    main

    To interact with the Twilio API, you must initialize a Twilio::REST::Client using your Account SID and Auth Token from the Twilio Console.

    Standard Authentication

    require 'twilio-ruby'

account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

@client = Twilio::REST::Client.new account_sid, auth_token

    Using an API Key If you prefer to use an API Key instead of your primary Auth Token:

    require 'twilio-ruby'

account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
api_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz'
api_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

@client = Twilio::REST::Client.new api_key_sid, api_key_secret, account_sid
    require 'twilio-ruby'

# Your Account SID and Auth Token from console.twilio.com
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# Initialize the Twilio Client with your credentials
@client = Twilio::REST::Client.new account_sid, auth_token

  9. Enable debug logging for the Twilio Client

    main

    To inspect the communication between the library and the Twilio API, pass a Ruby Logger instance to the client with the level set to at least DEBUG.

    @client = Twilio::REST::Client.new account_sid, auth_token
myLogger = Logger.new(STDOUT)
myLogger.level = Logger::DEBUG
@client.logger = myLogger

  11. Use the main Twilio namespaces

    main

    The SDK provides several primary namespaces for interacting with Twilio services:

    • Twilio::REST: The primary interface for making REST API calls to Twilio services.
    • Twilio::TwiML: Tools for generating TwiML (Twilio Markup Language) responses.
    • Twilio::JWT: Utilities for working with JSON Web Tokens.
    • Twilio::HTTP: The underlying HTTP client used for requests.

  12. Initialize the Twilio REST Client

    main
    The Twilio::REST::Client is the primary entry point for interacting with the Twilio API. It provides access to various Twilio domains (e.g., Accounts, Api, Chat, Messaging, Voice) through domain-specific methods. To use it, you typically instantiate it with your Twilio Account SID and Auth Token.