Module: Twitter::API::FriendsAndFollowers

Includes:
Utils
Included in:
Client
Defined in:
lib/twitter/api/friends_and_followers.rb

Constant Summary

Constants included from Utils

Utils::DEFAULT_CURSOR

Instance Method Summary collapse

Instance Method Details

#follow(*users) ⇒ Array<Twitter::User> #follow(*users, options) ⇒ Array<Twitter::User> Also known as: friendship_create

Allows the authenticating user to follow the specified users, unless they are already followed

Overloads:

  • #follow(*users) ⇒ Array<Twitter::User>

    Examples:

    Follow @sferik

    Twitter.follow('sferik')

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

  • #follow(*users, options) ⇒ Array<Twitter::User>

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :follow (Boolean) — default: false —

      Enable notifications for the target user.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/twitter/api/friends_and_followers.rb', line 130

def follow(*args)
  arguments = Twitter::API::Arguments.new(args)
  # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
  # so only send follow if it's true
  arguments.options[:follow] = true if !!arguments.options.delete(:follow)
  existing_friends = Thread.new do
    friend_ids.ids
  end
  new_friends = Thread.new do
    users(args).map(&:id)
  end
  follow!(new_friends.value - existing_friends.value, arguments.options)
end

#follow!(*users) ⇒ Array<Twitter::User> #follow!(*users, options) ⇒ Array<Twitter::User> Also known as: friendship_create!

Allows the authenticating user to follow the specified users

Overloads:

  • #follow!(*users) ⇒ Array<Twitter::User>

    Examples:

    Follow @sferik

    Twitter.follow!('sferik')

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

  • #follow!(*users, options) ⇒ Array<Twitter::User>

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :follow (Boolean) — default: false —

      Enable notifications for the target user.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/twitter/api/friends_and_followers.rb', line 160

def follow!(*args)
  arguments = Twitter::API::Arguments.new(args)
  # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
  # so only send follow if it's true
  arguments.options[:follow] = true if !!arguments.options.delete(:follow)
  arguments.flatten.threaded_map do |user|
    begin
      object_from_response(Twitter::User, :post, "/1.1/friendships/create.json", merge_user(arguments.options, user))
    rescue Twitter::Error::Forbidden
      # This error will be raised if the user doesn't have permission to
      # follow list_member, for whatever reason.
    end
  end.compact
end

#follower_ids(options = {}) ⇒ Twitter::Cursor #follower_ids(user, options = {}) ⇒ Twitter::Cursor

Overloads:

  • #follower_ids(options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user following the authenticated user

    Examples:

    Return the authenticated user's followers' IDs

    Twitter.follower_ids

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.

  • #follower_ids(user, options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user following the specified user

    Examples:

    Return @sferik's followers' IDs

    Twitter.follower_ids('sferik')
Twitter.follower_ids(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



59
60
61
 
# File 'lib/twitter/api/friends_and_followers.rb', line 59

def follower_ids(*args)
  cursor_from_response_with_user(:ids, nil, :get, "/1.1/followers/ids.json", args, :follower_ids)
end

#friend_ids(options = {}) ⇒ Twitter::Cursor #friend_ids(user, options = {}) ⇒ Twitter::Cursor

Returns a cursored collection of user objects for users following the specified user.

Examples:

Return the cursored collection of users following @sferik

Twitter.followers('sferik')
Twitter.followers(7505382)    # Same as above

Overloads:

  • #friend_ids(options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user the authenticated user is following

    Examples:

    Return the authenticated user's friends' IDs

    Twitter.friend_ids

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee's Tweets when set to true, 't' or 1.

    • :include_user_entities (Boolean, String, Integer) —

      The user entities node will be disincluded when set to false.

  • #friend_ids(user, options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user the specified user is following

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee's Tweets when set to true, 't' or 1.

    • :include_user_entities (Boolean, String, Integer) —

      The user entities node will be disincluded when set to false.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



282
283
284
 
# File 'lib/twitter/api/friends_and_followers.rb', line 282

def followers(*args)
  cursor_from_response_with_user(:users, Twitter::User, :get, "/1.1/followers/list.json", args, :followers)
end

#friend_ids(options = {}) ⇒ Twitter::Cursor #friend_ids(user, options = {}) ⇒ Twitter::Cursor

Overloads:

  • #friend_ids(options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user the authenticated user is following

    Examples:

    Return the authenticated user's friends' IDs

    Twitter.friend_ids

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.

  • #friend_ids(user, options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user the specified user is following

    Examples:

    Return @sferik's friends' IDs

    Twitter.friend_ids('sferik')
Twitter.friend_ids(7505382)  # Same as above

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



34
35
36
 
# File 'lib/twitter/api/friends_and_followers.rb', line 34

def friend_ids(*args)
  cursor_from_response_with_user(:ids, nil, :get, "/1.1/friends/ids.json", args, :friend_ids)
end

#friend_ids(options = {}) ⇒ Twitter::Cursor #friend_ids(user, options = {}) ⇒ Twitter::Cursor Also known as: following

Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their "friends").

Examples:

Return the cursored collection of users @sferik is following

Twitter.friends('sferik')
Twitter.friends(7505382)    # Same as above

Overloads:

  • #friend_ids(options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user the authenticated user is following

    Examples:

    Return the authenticated user's friends' IDs

    Twitter.friend_ids

    Parameters:

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee's Tweets when set to true, 't' or 1.

    • :include_user_entities (Boolean, String, Integer) —

      The user entities node will be disincluded when set to false.

  • #friend_ids(user, options = {}) ⇒ Twitter::Cursor

    Returns an array of numeric IDs for every user the specified user is following

    Parameters:

    • user (Integer, String, Twitter::User) —

      A Twitter user ID, screen name, or object.

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

      A customizable set of options.

    Options Hash (options):

    • :cursor (Integer) — default: -1 —

      Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.

    • :skip_status (Boolean, String, Integer) —

      Do not include contributee's Tweets when set to true, 't' or 1.

    • :include_user_entities (Boolean, String, Integer) —

      The user entities node will be disincluded when set to false.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



313
314
315
 
# File 'lib/twitter/api/friends_and_followers.rb', line 313

def friends(*args)
  cursor_from_response_with_user(:users, Twitter::User, :get, "/1.1/friends/list.json", args, :friends)
end

#friendship(source, target, options = {}) ⇒ Twitter::Relationship Also known as: friendship_show, relationship

Returns detailed information about the relationship between two users

Examples:

Return the relationship between @sferik and @pengwynn

Twitter.friendship('sferik', 'pengwynn')
Twitter.friendship('sferik', 14100886)   # Same as above
Twitter.friendship(7505382, 14100886)    # Same as above

Parameters:

  • source (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the source user.

  • target (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the target user.

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

    A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



227
228
229
230
231
232
233
 
# File 'lib/twitter/api/friends_and_followers.rb', line 227

def friendship(source, target, options={})
  merge_user!(options, source, "source")
  options[:source_id] = options.delete(:source_user_id) unless options[:source_user_id].nil?
  merge_user!(options, target, "target")
  options[:target_id] = options.delete(:target_user_id) unless options[:target_user_id].nil?
  object_from_response(Twitter::Relationship, :get, "/1.1/friendships/show.json", options)
end

#friendship?(source, target, options = {}) ⇒ Boolean

Test for the existence of friendship between two users

Examples:

Return true if @sferik follows @pengwynn

Twitter.friendship?('sferik', 'pengwynn')
Twitter.friendship?('sferik', 14100886)   # Same as above
Twitter.friendship?(7505382, 14100886)    # Same as above

Parameters:

  • source (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the source user.

  • target (Integer, String, Twitter::User) —

    The Twitter user ID, screen name, or object of the target user.

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

    A customizable set of options.

Returns:

  • (Boolean) —

    true if user_a follows user_b, otherwise false.

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



251
252
253
 
# File 'lib/twitter/api/friends_and_followers.rb', line 251

def friendship?(source, target, options={})
  friendship(source, target, options).source.following?
end

#friendship_update(user, options = {}) ⇒ Twitter::Relationship

Allows one to enable or disable retweets and device notifications from the specified user.

Examples:

Enable rewteets and devise notifications for @sferik

Twitter.friendship_update('sferik', :device => true, :retweets => true)

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

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

    A customizable set of options.

Options Hash (options):

  • :device (Boolean) —

    Enable/disable device notifications from the target user.

  • :retweets (Boolean) —

    Enable/disable retweets from the target user.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



208
209
210
211
 
# File 'lib/twitter/api/friends_and_followers.rb', line 208

def friendship_update(user, options={})
  merge_user!(options, user)
  object_from_response(Twitter::Relationship, :post, "/1.1/friendships/update.json", options)
end

#friendships(*users) ⇒ Array<Twitter::User> #friendships(*users, options) ⇒ Array<Twitter::User>

Returns the relationship of the authenticating user to the comma separated list of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none.

Overloads:

  • #friendships(*users) ⇒ Array<Twitter::User>

    Examples:

    Return extended information for @sferik and @pengwynn

    Twitter.friendships('sferik', 'pengwynn')
Twitter.friendships('sferik', 14100886)   # Same as above
Twitter.friendships(7505382, 14100886)    # Same as above

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

  • #friendships(*users, options) ⇒ Array<Twitter::User>

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



79
80
81
82
83
 
# File 'lib/twitter/api/friends_and_followers.rb', line 79

def friendships(*args)
  arguments = Twitter::API::Arguments.new(args)
  merge_users!(arguments.options, arguments)
  objects_from_response(Twitter::User, :get, "/1.1/friendships/lookup.json", arguments.options)
end

#friendships_incoming(options = {}) ⇒ Twitter::Cursor

Returns an array of numeric IDs for every user who has a pending request to follow the authenticating user

Examples:

Return an array of numeric IDs for every user who has a pending request to follow the authenticating user

Twitter.friendships_incoming

Parameters:

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

    A customizable set of options.

Options Hash (options):

  • :cursor (Integer) — default: -1 —

    Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



96
97
98
 
# File 'lib/twitter/api/friends_and_followers.rb', line 96

def friendships_incoming(options={})
  cursor_from_response(:ids, nil, :get, "/1.1/friendships/incoming.json", options, :friendships_incoming)
end

#friendships_outgoing(options = {}) ⇒ Twitter::Cursor

Returns an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request

Examples:

Return an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request

Twitter.friendships_outgoing

Parameters:

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

    A customizable set of options.

Options Hash (options):

  • :cursor (Integer) — default: -1 —

    Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



111
112
113
 
# File 'lib/twitter/api/friends_and_followers.rb', line 111

def friendships_outgoing(options={})
  cursor_from_response(:ids, nil, :get, "/1.1/friendships/outgoing.json", options, :friendships_outgoing)
end

#no_retweet_ids(options = {}) ⇒ Array<Integer> Also known as: no_retweets_ids

Returns a collection of user_ids that the currently authenticated user does not want to receive retweets from. =>

Examples:

Enable rewteets and devise notifications for @sferik

Twitter.no_retweet_ids

Parameters:

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

    A customizable set of options.

Options Hash (options):

  • :stringify_ids (Boolean) —

    Many programming environments will not consume our ids due to their size. Provide this option to have ids returned as strings instead. Read more about Twitter IDs, JSON and Snowflake.

Returns:

  • (Array<Integer>)

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



329
330
331
 
# File 'lib/twitter/api/friends_and_followers.rb', line 329

def no_retweet_ids(options={})
  get("/1.1/friendships/no_retweets/ids.json", options)[:body].map(&:to_i)
end

#unfollow(*users) ⇒ Array<Twitter::User> #unfollow(*users, options) ⇒ Array<Twitter::User> Also known as: friendship_destroy

Allows the authenticating user to unfollow the specified users

Overloads:

  • #unfollow(*users) ⇒ Array<Twitter::User>

    Examples:

    Unfollow @sferik

    Twitter.unfollow('sferik')

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

  • #unfollow(*users, options) ⇒ Array<Twitter::User>

    Parameters:

    • users (Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>) —

      An array of Twitter user IDs, screen names, or objects.

    • options (Hash) —

      A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • No

Authentication:

  • Requires user context



190
191
192
 
# File 'lib/twitter/api/friends_and_followers.rb', line 190

def unfollow(*args)
  threaded_user_objects_from_response(:post, "/1.1/friendships/destroy.json", args)
end