Configuration.md

Configuration

Twitter API version 1.1 requires authentication on all requests. Some requests can be made with application-only authentication while other requests require single-user authentication.

Application-only Authentication

To start using the Twitter API, you need to register your application with Twitter. Registration requires you to answer some questions about your application and agree to the Twitter API Terms of Use.

Once you've registered an application, it's important that you set the correct access level. Otherwise you may see the error:

Read-only application cannot POST

Your new application will be assigned a consumer key/secret pair that identifies your application to Twitter. This is all you need to configure your client for application-only authentication.

client = Twitter::REST::Client.new do |config|
  config.consumer_key    = "YOUR_CONSUMER_KEY"
  config.consumer_secret = "YOUR_CONSUMER_SECRET"
end

If you prefer, you can pass in configuration as a Hash:

config = {
  consumer_key:    "YOUR_CONSUMER_KEY",
  consumer_secret: "YOUR_CONSUMER_SECRET",
}

client = Twitter::REST::Client.new(config)

Regardless of your configuration style, you should now be able to use this client to make any Twitter API request that does not require single-user authentication. For example:

client.user("sferik")

Note: The first time this method is called, it will make two API requests. First, it will fetch an access token to perform the request. Then, it will fetch the requested user. The access token will be cached for subsequent requests made with the same client but you may wish to manually fetch the access token once and use it when initializing clients to avoid making two requests every time.

client.bearer_token

This token never expires and will not change unless it is invalidated. Once you've obtained a bearer token, you can use it to initialize clients to avoid making an extra request.

client = Twitter::REST::Client.new do |config|
  config.consumer_key    = "YOUR_CONSUMER_KEY"
  config.consumer_secret = "YOUR_CONSUMER_SECRET"
  config.bearer_token    = "YOUR_BEARER_TOKEN"
end

Single-user Authentication

Not all Twitter API resources are accessible with application-only authentication. Some resources require single-user authentication tokens, which you can obtain from the 3-legged authorization flow.

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
end

You can use this client to make any Twitter REST API request. For example:

client.update("I'm tweeting with @gem!")

Premium Search API

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.dev_environment     = "YOUR_DEV_ENVIRONMENT"
end

You can use this client to make a REST 30-Day or Fullarchive Search API request. For example:

client.premium_search("#ruby", { maxResults: 100 }, { product: 'fullarchive' })

Streaming Clients

Streaming clients are initialized just like single-user authenticated REST clients:

client = Twitter::Streaming::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
end

client.sample do |object|
  puts object.text if object.is_a?(Twitter::Tweet)
end

For more information, see the documentation for the Twitter::Client, Twitter::REST::Client, and Twitter::Streaming::Client classes.

Using a Proxy

If you'd like to connect via a proxy, a proxy can be configured by passing a Hash to your configuration:

proxy = {
  host: "proxy.example.com",
  port: 8080,
  username: "proxy_username",
  password: "proxy_password"
}

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
  config.proxy               = proxy
end

Note that only a host and port are required, but a username and password can be optionally configured for an authenticated proxy server. Proxies are supported by both Twitter::REST::Client and Twitter::Streaming::Client classes.