simple_twitter

simple_twitter

Dead simple X (formerly Twitter) API client. Supports both v1 and v2

Installation

Add this line to your application's Gemfile:

gem 'simple_twitter'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install simple_twitter

Example

require 'simple_twitter'

client = SimpleTwitter::Client.new(bearer_token: "...")
pp client.get("https://api.twitter.com/2/tweets",
              params: { ids: "1302127884039909376,1369885448319889409" })

Result:

{:data=>
  [{:id=>"1302127884039909376",
    :text=>
     "We conclude RubyKaigi Takeout 2020. We hope we can meet in-person, safely at RubyKaigi 2021 in Mie! Thank you all for tuning in. #rubykaigi"},
   {:id=>"1369885448319889409",
    :text=>
     "RubyKaigi 2021 is going online again: RubyKaigi Takeout 2021 will happen this fall. https://t.co/Fv1PlvmUHh"}]}

As you see hash keys are converted into symbols (Note that strings as values are not converted.)

Call API on user context

Some operations (eg. posting a tweet) needs OAuth instead of bearer_token.

config = (load from yaml or something)
client = SimpleTwitter::Client.new(
  api_key: config[:api_key],
  api_secret_key: config[:api_secret_key],
  access_token: config[:access_token],
  access_token_secret: config[:access_token_secret],
)
pp client.post("https://api.twitter.com/1.1/statuses/update.json",
               params: { status: "Test." })

You can get the access_token and access_token_secret for your own at the Twitter Developer Portal. For other users, you need to get them via OAuth (out of scope of this gem.)

Post with JSON body

Since Twitter API v2, POST must be sent as JSON body

e.g.https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/post-tweets

Send using the json argument.

e.g.

client = SimpleTwitter::Client.new(bearer_token: ENV["ACCESS_TOKEN"])
client.post("https://api.twitter.com/2/tweets", json: { text: "Hello twitter!" })

Upload media

If you want to tweet with an image, you need to do the following steps

1. Upload image as media
   • c.f. https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/post-media-upload
2. Tweet with media
   • c.f. https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/post-tweets

e.g.

config = (load from yaml or something)
client = SimpleTwitter::Client.new(
  api_key: config[:api_key],
  api_secret_key: config[:api_secret_key],
  access_token: config[:access_token],
  access_token_secret: config[:access_token_secret],
)

# Upload image as media
media = client.post(
          "https://upload.twitter.com/1.1/media/upload.json",
          form: {
            media: HTTP::FormData::File.new("/path/to/image.png")
          }
        )
# =>
# {:media_id=>12345678901234567890,
#  :media_id_string=>"12345678901234567890",
#  :size=>60628,
#  :expires_after_secs=>86400,
#  :image=>{:image_type=>"image/png", :w=>400, :h=>400}}

# Tweet with media
client.post(
  "https://api.twitter.com/2/tweets",
  json: { 
    text: "Test tweet with image", 
    media: { media_ids: [media[:media_id_string]] },
  }
)

Advanced

If you want the raw json string or use streaming API, use get_raw, post_raw, etc. which returns HTTP::Response of the http gem.

res = client.get_raw("https://api.twitter.com/2/tweets/sample/stream")
p res #=> #<HTTP::Response ...>
loop do
  puts res.body.readpartial
end

Hint

Some API parameters has . in its name (eg. tweet.fields.) Did you know that in Ruby you can include . in a hash key if quoted? :-)

tweets = @client.get("https://api.twitter.com/2/users/#{id}/tweets", params: {
  expansions: "author_id",
  max_results: 100,
  "tweet.fields": "author_id,created_at,referenced_tweets,text",
})

Detailed error details

If an error is returned from the API, you may need more information.

In such cases, you can retrieve it as follows.

begin
  client = SimpleTwitter::Client.new(bearer_token: "invalid_bearer_token")
  client.get("https://api.twitter.com/2/users/me")
rescue SimpleTwitter::Error => error
  error.raw_response.class
  #=> HTTP::Response

  error.raw_response.code
  #=> 403

  error.body[:title]
  # => "Unsupported Authentication"
end

See more. SimpleTwitter::Error

API Reference

See https://yhara.github.io/simple_twitter/

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yhara/simple_twitter.

License

The gem is available as open source under the terms of the MIT License.