Module: Twitter::Client::FriendsAndFollowers

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

Overview

Defines methods related to friends and followers

Instance Method Summary collapse

Instance Method Details

#accept(user, options = {}) ⇒ Twitter::User

Note:

Undocumented

Allows the authenticating user to accept the specified user's follow request

Examples:

Accept @sferik's follow request

Twitter.accept("sferik")

Parameters:

  • user (Integer, String) —

    A Twitter user ID or screen name.

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

    A customizable set of options.

Returns:

Raises:

Rate Limited?:

  • No

Requires Authentication?:

  • Yes



268
269
270
271
272
 
# File 'lib/twitter/client/friends_and_followers.rb', line 268

def accept(user, options={})
  options.merge_user!(user)
  user = post("/1/friendships/accept.json", options)
  Twitter::User.new(user)
end

#deny(user, options = {}) ⇒ Twitter::User

Note:

Undocumented

Allows the authenticating user to deny the specified user's follow request

Examples:

Deny @sferik's follow request

Twitter.deny("sferik")

Parameters:

  • user (Integer, String) —

    A Twitter user ID or screen name.

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

    A customizable set of options.

Returns:

Raises:

Rate Limited?:

  • No

Requires Authentication?:

  • Yes



285
286
287
288
289
 
# File 'lib/twitter/client/friends_and_followers.rb', line 285

def deny(user, options={})
  options.merge_user!(user)
  user = post("/1/friendships/deny.json", options)
  Twitter::User.new(user)
end

#follow(user, options = {}) ⇒ Twitter::User Also known as: friendship_create

Allows the authenticating user to follow the specified user

Examples:

Follow @sferik

Twitter.follow("sferik")

Parameters:

  • user (Integer, String) —

    A Twitter user ID or screen name.

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

    A customizable set of options.

Options Hash (options):

  • :follow (Boolean) — default: false —

    Enable notifications for the target user.

  • :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



167
168
169
170
171
172
173
174
 
# File 'lib/twitter/client/friends_and_followers.rb', line 167

def follow(user, options={})
  options.merge_user!(user)
  # 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
  options.merge!(:follow => true) if options.delete(:follow)
  user = post("/1/friendships/create.json", options)
  Twitter::User.new(user)
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.

    Returns:

  • #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) —

      A Twitter user ID or screen name.

    • 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:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless requesting it from a protected user

    If getting this data of a protected user, you must authenticate (and be allowed to see that user).



34
35
36
37
38
39
40
41
 
# File 'lib/twitter/client/friends_and_followers.rb', line 34

def follower_ids(*args)
  options = {:cursor => -1}
  options.merge!(args.last.is_a?(Hash) ? args.pop : {})
  user = args.first
  options.merge_user!(user)
  cursor = get("/1/followers/ids.json", options)
  Twitter::Cursor.new(cursor, 'ids')
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.

    Returns:

  • #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) —

      A Twitter user ID or screen name.

    • 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:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless requesting it from a protected user

    If getting this data of a protected user, you must authenticate (and be allowed to see that user).



66
67
68
69
70
71
72
73
 
# File 'lib/twitter/client/friends_and_followers.rb', line 66

def friend_ids(*args)
  options = {:cursor => -1}
  options.merge!(args.last.is_a?(Hash) ? args.pop : {})
  user = args.first
  options.merge_user!(user)
  cursor = get("/1/friends/ids.json", options)
  Twitter::Cursor.new(cursor, 'ids')
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(7505382, 14100886)

Parameters:

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

    A customizable set of options.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/twitter/client/friends_and_followers.rb', line 135

def friendship(source, target, options={})
  case source
  when Integer
    options[:source_id] = source
  when String
    options[:source_screen_name] = source
  end
  case target
  when Integer
    options[:target_id] = target
  when String
    options[:target_screen_name] = target
  end
  relationship = get("/1/friendships/show.json", options)['relationship']
  Twitter::Relationship.new(relationship)
end

#friendship?(user_a, user_b, options = {}) ⇒ Boolean

Note:

Consider using #friendship instead of this method.

Test for the existence of friendship between two users

Examples:

Return true if @sferik follows @pengwynn

Twitter.friendship?("sferik", "pengwynn")

Parameters:

  • user_a (Integer, String) —

    The ID or screen_name of the subject user.

  • user_b (Integer, String) —

    The ID or screen_name of the user to test for following.

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

    A customizable set of options.

Returns:

  • (Boolean) —

    true if user_a follows user_b, otherwise false.

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless user_a or user_b is protected



87
88
89
 
# File 'lib/twitter/client/friends_and_followers.rb', line 87

def friendship?(user_a, user_b, options={})
  get("/1/friendships/exists.json", options.merge(:user_a => user_a, :user_b => user_b))
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 ID or screen name.

  • 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

Requires Authentication?:

  • Yes



235
236
237
238
239
 
# File 'lib/twitter/client/friends_and_followers.rb', line 235

def friendship_update(user, options={})
  options.merge_user!(user)
  relationship = post("/1/friendships/update.json", options)['relationship']
  Twitter::Relationship.new(relationship)
end

#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.

Returns The requested users.

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>, Set<Integer, String>) —

    Twitter user IDs or screen names.

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

    A customizable set of options.

Options Hash (options):

Returns:

Raises:

Parameters:

  • options (Hash) —

    A customizable set of options.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



213
214
215
216
217
218
219
220
 
# File 'lib/twitter/client/friends_and_followers.rb', line 213

def friendships(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  users = args
  options.merge_users!(Array(users))
  get("/1/friendships/lookup.json", options).map do |user|
    Twitter::User.new(user)
  end
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

Requires Authentication?:

  • Yes



102
103
104
105
106
 
# File 'lib/twitter/client/friends_and_followers.rb', line 102

def friendships_incoming(options={})
  options = {:cursor => -1}.merge(options)
  cursor = get("/1/friendships/incoming.json", options)
  Twitter::Cursor.new(cursor, 'ids')
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

Requires Authentication?:

  • Yes



119
120
121
122
123
 
# File 'lib/twitter/client/friends_and_followers.rb', line 119

def friendships_outgoing(options={})
  options = {:cursor => -1}.merge(options)
  cursor = get("/1/friendships/outgoing.json", options)
  Twitter::Cursor.new(cursor, 'ids')
end

#no_retweet_ids(options = {}) ⇒ Array<Integer>

Returns an array of user_ids that the currently authenticated user does not want to see retweets from.

Examples:

Enable rewteets and devise notifications for @sferik

Twitter.no_retweet_ids

Parameters:

  • user (Integer, String) —

    Twitter user ID or screen name.

  • 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

Requires Authentication?:

  • Yes



253
254
255
 
# File 'lib/twitter/client/friends_and_followers.rb', line 253

def no_retweet_ids(options={})
  get("/1/friendships/no_retweet_ids.json", options, :phoenix => true)
end

#unfollow(user, options = {}) ⇒ Twitter::User Also known as: friendship_destroy

Allows the authenticating user to unfollow the specified user

Examples:

Unfollow @sferik

Twitter.unfollow("sferik")

Parameters:

  • user (Integer, String) —

    A Twitter user ID or screen name.

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

    A customizable set of options.

Options Hash (options):

  • :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



189
190
191
192
193
 
# File 'lib/twitter/client/friends_and_followers.rb', line 189

def unfollow(user, options={})
  options.merge_user!(user)
  user = delete("/1/friendships/destroy.json", options)
  Twitter::User.new(user)
end