Module: Twitter::Client::Tweets

Included in:
Twitter::Client
Defined in:
lib/twitter/client/tweets.rb

Overview

Defines methods related to tweets

Instance Method Summary collapse

Instance Method Details

#oembed(id_or_url, options = {}) ⇒ Object

Returns an oEmbed version of a single status, specified by ID or url to the tweet

Parameters:

Options Hash (options):

  • :maxwidth (Integer) —

    The maximum width in pixels that the embed should be rendered at. This value is constrained to be between 250 and 550 pixels.

  • :hide_media (Boolean, String, Integer) —

    Specifies whether the embedded Tweet should automatically expand images which were uploaded via POST statuses/update_with_media. When set to either true, t or 1 images will not be expanded. Defaults to false.

  • :hide_thread (Boolean, String, Integer) —

    Specifies whether the embedded Tweet should automatically show the original message in the case that the embedded Tweet is a reply. When set to either true, t or 1 the original Tweet will not be shown. Defaults to false.

  • :omit_script (Boolean, String, Integer) —

    Specifies whether the embedded Tweet HTML should include a <script> element pointing to widgets.js. In cases where a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included. When set to either true, t or 1 the <script> element will not be included in the embed HTML, meaning that pages must include a reference to widgets.js manually. Defaults to false.

  • :align (String) —

    Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page. Valid values are left, right, center, and none. Defaults to none, meaning no alignment styles are specified for the Tweet.

  • :related (String) —

    A value for the TWT related parameter, as described in Web Intents. This value will be forwarded to all Web Intents calls.

  • :lang (String) —

    Language code for the rendered embed. This will affect the text and localization of the rendered HTML.

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless the author of the status is protected



88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/twitter/client/tweets.rb', line 88

def oembed(id_or_url, options={})
  case id_or_url
  when Integer
    id = id_or_url
    oembed = get("/1/statuses/oembed.json?id=#{id}", options)
  when String
    url = id_or_url
    escaped_url = URI.escape(url, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
    oembed = get("/1/statuses/oembed.json?url=#{escaped_url}", options)
  end
  Twitter::OEmbed.new(oembed)
end

#retweet(id, options = {}) ⇒ Twitter::Status

Retweets a tweet

Examples:

Retweet the status with the ID 28561922516

Twitter.retweet(28561922516)

Parameters:

  • id (Integer) —

    The numerical ID of the desired status.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



132
133
134
135
136
137
 
# File 'lib/twitter/client/tweets.rb', line 132

def retweet(id, options={})
  new_status = post("/1/statuses/retweet/#{id}.json", options)
  orig_status = new_status.delete('retweeted_status')
  orig_status['retweeted_status'] = new_status
  Twitter::Status.new(orig_status)
end

#retweeters_of(id, options = {}) ⇒ Array

Show up to 100 users who retweeted the status

Examples:

Show up to 100 users who retweeted the status with the ID 28561922516

Twitter.retweeters_of(28561922516)

Parameters:

  • id (Integer) —

    The numerical ID of the desired status.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

  • :ids_only (Boolean) — default: 'false' —

    Only return user ids instead of full user objects.

Returns:

  • (Array)

Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



26
27
28
29
30
31
32
33
34
 
# File 'lib/twitter/client/tweets.rb', line 26

def retweeters_of(id, options={})
  if ids_only = !!options.delete(:ids_only)
    get("/1/statuses/#{id}/retweeted_by/ids.json", options)
  else
    get("/1/statuses/#{id}/retweeted_by.json", options).map do |user|
      Twitter::User.new(user)
    end
  end
end

#retweets(id, options = {}) ⇒ Array<Twitter::Status>

Returns up to 100 of the first retweets of a given tweet

Examples:

Return up to 100 of the first retweets of the status with the ID 28561922516

Twitter.retweets(28561922516)

Parameters:

  • id (Integer) —

    The numerical ID of the desired status.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 100.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



50
51
52
53
54
 
# File 'lib/twitter/client/tweets.rb', line 50

def retweets(id, options={})
  get("/1/statuses/retweets/#{id}.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#status(id, options = {}) ⇒ Twitter::Status

Returns a single status, specified by ID

Examples:

Return the status with the ID 25938088801

Twitter.status(25938088801)

Parameters:

  • id (Integer) —

    The numerical ID of the desired status.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless the author of the status is protected



68
69
70
71
 
# File 'lib/twitter/client/tweets.rb', line 68

def status(id, options={})
  status = get("/1/statuses/show/#{id}.json", options)
  Twitter::Status.new(status)
end

#status_destroy(id, options = {}) ⇒ Twitter::Status

Note:

The authenticating user must be the author of the specified status.

Destroys the specified status

Examples:

Destroy the status with the ID 25938088801

Twitter.status_destroy(25938088801)

Parameters:

  • id (Integer) —

    The numerical ID of the desired status.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Requires Authentication?:

  • Yes



114
115
116
117
 
# File 'lib/twitter/client/tweets.rb', line 114

def status_destroy(id, options={})
  status = delete("/1/statuses/destroy/#{id}.json", options)
  Twitter::Status.new(status)
end

#update(status, options = {}) ⇒ Twitter::Status

Note:

A status update with text identical to the authenticating user's current status will be ignored to prevent duplicates.

Updates the authenticating user's status

Examples:

Update the authenticating user's status

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

Parameters:

  • status (String) —

    The text of your status update, up to 140 characters.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :in_reply_to_status_id (Integer) —

    The ID of an existing status that the update is in reply to.

  • :lat (Float) —

    The latitude of the location this tweet refers to. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.

  • :long (Float) —

    The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :place_id (String) —

    A place in the world. These IDs can be retrieved from Geo#reverse_geocode.

  • :display_coordinates (String) —

    Whether or not to put a pin on the exact coordinates a tweet has been sent from.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Requires Authentication?:

  • Yes



158
159
160
161
 
# File 'lib/twitter/client/tweets.rb', line 158

def update(status, options={})
  status = post("/1/statuses/update.json", options.merge(:status => status))
  Twitter::Status.new(status)
end

#update_with_media(status, image, options = {}) ⇒ Twitter::Status

Note:

A status update with text/media identical to the authenticating user's current status will NOT be ignored

Updates with media the authenticating user's status

Examples:

Update the authenticating user's status

Twitter.update_with_media("I'm tweeting with @gem!", File.new('my_awesome_pic.jpeg'))
Twitter.update_with_media("I'm tweeting with @gem!", {'io' => StringIO.new(pic), 'type' => 'jpg'})

Parameters:

  • status (String) —

    The text of your status update, up to 140 characters.

  • media (File) —

    A File object with your picture (PNG, JPEG or GIF)

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :in_reply_to_status_id (Integer) —

    The ID of an existing status that the update is in reply to.

  • :lat (Float) —

    The latitude of the location this tweet refers to. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.

  • :long (Float) —

    The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :place_id (String) —

    A place in the world. These IDs can be retrieved from Geo#reverse_geocode.

  • :display_coordinates (String) —

    Whether or not to put a pin on the exact coordinates a tweet has been sent from.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, 't' or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Requires Authentication?:

  • Yes



184
185
186
187
 
# File 'lib/twitter/client/tweets.rb', line 184

def update_with_media(status, image, options={})
  status = post("/1/statuses/update_with_media.json", options.merge('media[]' => image, 'status' => status), :endpoint => media_endpoint)
  Twitter::Status.new(status)
end