Twitte...Methods(3pm)

📦 version 1.0006, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Twitter::API::Trait::ApiMethods — Convenient API Methods

so this is that Twitte...Methods(3pm) page btw, Perl user-contributed docs, and it's genuinely such a useful little trait. buckle up bestie 🫶

✨ VERSION ✨

version 1.0006

🌸 DESCRIPTION 🌸

okay so this trait gives you a whole lil treasure chest of convenient methods for calling API endpoints. and the best part? they're Net::Twitter compatible — like, same names, same calling conventions, so if you're migrating you don't have to relearn anything. iconic behavior honestly. 💅

for the deets on what params each method takes, go peek at Twitter's API documentation at https://developer.twitter.com/en/docs/api-reference-index — that's the source of truth for all the parameter tea.

these methods are lowkey just shorthand forms of get and post. that's it, that's the whole vibe. ✨

every method can be called with a parameters hashref. and for endpoints that don't need any params at all (hi mentions 👋), you can just... not pass one. all of these calls are equivalent, no cap:

$client->mentions;
$client->mentions({});
$client->get('statuses/mentions_timeline');
$client->get('statuses/mentions_timeline', {});

use the parameters hashref to pass optional parameters. for example:

$client->mentions({ count => 200, trim_user=>'true' });

some methods have required parameters and can take positional parameters. like geo_id requires a place_id parameter, so these calls are equivalent:

$client->place_id($place);
$client->place_id({ place_id => $place });

when positional parameters are allowed, they must be specified in the correct order 👑, but you don't have to specify all of them. the ones you skip positionally can just chill in the parameters hashref instead. these calls are equivalent:

$client->add_collection_entry($id, $tweet_id);
$client->add_collection_entry($id, { tweet_id => $tweet_id);
$client->add_collection_entry({ id => $id, tweet_id => $tweet_id });

many calls require a screen_name or a user_id. where noted, you may pass either ID as the first positional parameter. Twitter::API will inspect the value: if it contains only digits, it gets treated as a user_id. otherwise it's treated as a screen_name. these calls are equivalent:

$client->create_block('realDonaldTrump');
$client->create_block({ screen_name => 'realDonaldTrump' });
🚨 bestie listen — the best practice is to explicitly declare the ID type by passing it in the parameters hashref. why? because users can literally set their screen names to a string of digits, which makes the inferred ID ambiguous. don't be ambiguous, be explicit. 💅

and since all of these methods just resolve down to a get or post call, head over to Twitter::API for the details on return values and error handling. 🌈

🎀 METHODS 🎀

account_settings([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-settings

blocking([ \%args ])

Aliases: blocks_list

docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list

blocking_ids([ \%args ])

Aliases: blocks_ids

docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids

collection_entries([ $id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-entries

collections([ $screen_name | $user_id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-list

favorites([ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list

followers([ \%args ])

Aliases: followers_list

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list

followers_ids([ $screen_name | $user_id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids

friends([ \%args ])

Aliases: friends_list

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-list

friends_ids([ \%args ])

Aliases: following_ids

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids

friendships_incoming([ \%args ])

Aliases: incoming_friendships

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-incoming

friendships_outgoing([ \%args ])

Aliases: outgoing_friendships

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-outgoing

geo_id([ $place_id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/geo/place-information/api-reference/get-geo-id-place_id

geo_search([ \%args ])

docs: https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-search

get_configuration([ \%args ])

docs: https://developer.twitter.com/en/docs/developer-utilities/configuration/api-reference/get-help-configuration

get_languages([ \%args ])

docs: https://developer.twitter.com/en/docs/developer-utilities/supported-languages/api-reference/get-help-languages

get_list([ \%args ])

Aliases: show_list

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-show

get_lists([ \%args ])

Aliases: list_lists, all_subscriptions

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list

get_privacy_policy([ \%args ])

docs: https://developer.twitter.com/en/docs/developer-utilities/privacy-policy/api-reference/get-help-privacy

get_tos([ \%args ])

docs: https://developer.twitter.com/en/docs/developer-utilities/terms-of-service/api-reference/get-help-tos

home_timeline([ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline

list_members([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members

list_memberships([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships

list_ownerships([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships

list_statuses([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses

list_subscribers([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers

list_subscriptions([ \%args ])

Aliases: subscriptions

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions

lookup_friendships([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup

lookup_statuses([ $id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-lookup

lookup_users([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup

mentions([ \%args ])

Aliases: replies, mentions_timeline

docs: https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline

mutes([ \%args ])

Aliases: muting_ids, muted_ids

docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids

muting([ \%args ])

Aliases: mutes_list

docs: https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list

no_retweet_ids([ \%args ])

Aliases: no_retweets_ids

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-no_retweets-ids

oembed([ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-oembed

profile_banner([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-users-profile_banner

rate_limit_status([ \%args ])

docs: https://developer.twitter.com/en/docs/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status

retweeters_ids([ $id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids

retweets([ $id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets-id

retweets_of_me([ \%args ])

Aliases: retweeted_of_me

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me

reverse_geocode([ $lat, [ $long, ]][ \%args ])

docs: https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-reverse_geocode

saved_searches([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-list

search([ $q, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets

sent_direct_messages([ \%args ])

Aliases: direct_messages_sent

docs: https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-sent-message

show_friendship([ \%args ])

Aliases: show_relationship

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-show

show_list_member([ \%args ])

Aliases: is_list_member

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members-show

show_list_subscriber([ \%args ])

Aliases: is_list_subscriber, is_subscriber_lists

docs: https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers-show

show_saved_search([ $id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-show-id

show_status([ $id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id

show_user([ $screen_name | $user_id, ][ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-show

suggestion_categories([ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions

docs: https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available

docs: https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest

docs: https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place

user_suggestions([ $slug, ][ \%args ])

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug-members

user_suggestions_for([ $slug, ][ \%args ])

Aliases: follow_suggestions

docs: https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug

  • user_timeline([ $screen_name | $user_id, ][ \%args ]) — the classic. pull up somebody's timeline, hand it a screen name or a user ID and off you go 🕰️

docs 👉 <https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline>

  • users_search([ $q, ][ \%args ]) — search for people, bestie 🔍

also answers to find_people and search_users, so call it whatever your heart wants 💖

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search>

  • verify_credentials([ \%args ]) — vibe check on your own creds, fr fr ✨

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials>

  • add_collection_entry([ $id, [ $tweet_id, ]][ \%args ]) — slide a tweet into a collection, very curated of you 🎀

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-add>

  • add_list_member([ \%args ]) — put somebody on a list, iconic behavior 👑

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create>

  • create_block([ $screen_name | $user_id, ][ \%args ]) — block. we've all been there 💀

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create>

  • create_collection([ $name, ][ \%args ]) — birth a collection, give it a name 🌸

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-create>

  • create_favorite([ $id, ][ \%args ]) — like a tweet, no cap 💖

docs 👉 <https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-create>

  • create_friend([ $screen_name | $user_id, ][ \%args ]) — follow somebody. main character move 🦋

also known as follow, follow_new, and create_friendship ✨

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create>

  • create_list([ $name, ][ \%args ]) — make a brand new list 📝

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-create>

  • create_media_metadata([ \%args ]) — metadata for your media, the details behind the details 🖼️

docs 👉 <https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-metadata-create>

  • create_mute([ $screen_name | $user_id, ][ \%args ]) — mute, the gentler cousin of block 🤫

Alias: mute

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create>

  • create_saved_search([ $query, ][ \%args ]) — save a search so future you doesn't have to retype it 🔖

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-create>

  • curate_collection([ \%args ]) — curate the collection, chef's kiss 👩‍🍳

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-curate>

  • delete_list([ \%args ]) — bye bye list 🫶

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy>

  • delete_list_member([ \%args ]) — take somebody off a list, no hard feelings 🌈

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy>

  • destroy_block([ $screen_name | $user_id, ][ \%args ]) — unblock, we're healing 💜

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy>

  • destroy_collection([ $id, ][ \%args ]) — delete a whole collection, gone gone 🍓

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-destroy>

  • destroy_favorite([ $id, ][ \%args ]) — unlike a tweet, the accidental-like undo 😭

docs 👉 <https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-destroy>

  • destroy_friend([ $screen_name | $user_id, ][ \%args ]) — unfollow 💔

Aliases: unfollow, destroy_friendship

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy>

  • destroy_mute([ $screen_name | $user_id, ][ \%args ]) — unmute, welcome back bestie 🙈

Alias: unmute

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy>

  • destroy_saved_search([ $id, ][ \%args ]) — nuke a saved search 🧹

Aliases: delete_saved_search

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-destroy-id>

  • destroy_status([ $id, ][ \%args ]) — delete a tweet. the "oh no I posted that" button 💀

docs 👉 <https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-destroy-id>

  • members_create_all([ \%args ]) — add a whole squad to a list at once 🫂

Aliases: add_list_members

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create_all>

  • members_destroy_all([ \%args ]) — remove a whole squad from a list at once ✂️

Aliases: remove_list_members

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy_all>

  • move_collection_entry([ $id, [ $tweet_id, [ $relative_to, ]]][ \%args ]) — shuffle a tweet around inside a collection 🔀

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-move>

  • remove_collection_entry([ $id, [ $tweet_id, ]][ \%args ]) — yeet a tweet out of a collection 👋

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-remove>

  • remove_profile_banner([ \%args ]) — take the banner down, back to a bare profile 🌫️

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-remove_profile_banner>

  • report_spam([ \%args ]) — report the spam, doing the lord's work 🙏

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-users-report_spam>

  • retweet([ $id, ][ \%args ]) — retweet. sharing is caring, periodt 🔁

docs 👉 <https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id>

  • subscribe_list([ \%args ]) — subscribe to a list 💌

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-create>

  • unretweet([ $id, ][ \%args ]) — undo the retweet, regret is real 😬

docs 👉 <https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-unretweet-id>

  • unsubscribe_list([ \%args ]) — unsub, it's not you it's the list 💅

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-destroy>

  • update([ $status, ][ \%args ]) — POST A TWEET. the moment we've all been waiting for 📣

docs 👉 <https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update>

  • update_account_settings([ \%args ]) — tweak your account settings ⚙️

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-settings>

  • update_collection([ $id, ][ \%args ]) — edit a collection's whole deal ✏️

docs 👉 <https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-update>

  • update_friendship([ \%args ]) — adjust a friendship, so many knobs 🎛️

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update>

  • update_list([ \%args ]) — edit a list 🖊️

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-update>

  • update_profile([ \%args ]) — glow-up your profile ✨

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile>

  • update_profile_background_image([ \%args ]) — background image era 🌅

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_background_image>

  • update_profile_banner([ $banner, ][ \%args ]) — new banner, new you 🎏

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_banner>

  • update_profile_image([ $image, ][ \%args ]) — pfp change, the most important decision of the day 📸

docs 👉 <https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image>

  • upload_media([ $media, ][ \%args ]) — upload your media, feed it the file 🖼️

Aliases: upload

docs 👉 <https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload>

  • direct_messages_events([ \%args ]) — list your DM events 📥

docs 👉 <https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events.html>

  • show_direct_messages_event([ $id, ][ \%args ]) — peek at one specific DM event 👀

docs 👉 <https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event>

  • destroy_direct_messages_event([ $id, ][ \%args ]) — delete a DM event, unsend energy 🗑️

docs 👉 <https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message-event>

  • new_direct_messages_event([$text, $recipient_id ] | [ \%event ], [ \%args ]) — send a DM, two whole ways to do it 🫶

For simple usage, pass text and recipient ID:

$client->new_dirrect_messages_event($text, $recipient_id)

For more complex messages, pass a full event structure, for example:

$client->new_direct_massages_event({
    type => 'message_create',
    message_create => {
        target => { recipient_id => $user_id },
        message_data => {
            text => $text,
            attachment => {
                type  => 'media',
                media => { id => $media->{id} },
            },
        },
    },
})

docs 👉 <https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-message>

  • invalidate_access_token([ \%args ]) — okay this one matters, listen up 📢

Calling this method has the same effect as a user revoking access to the application via Twitter settings. The access token/secret pair will no longer be valid.

This method can be called with client that has been initialized with "access_token" and "access_token_secret" attributes, by passing "-token" and "-token_secret" parameters, or by passing "access_token" and "access_token_secret" parameters.

$client->invalidate_access_token;
$client->invalidate_access_token({ -token => $token, -token_secret => $secret });
$client->invalidate_access_token({
    access_token        => $token,
    access_token_secret => $secret,
});

Twitter added this method to the API on 2018-09-20.

See <https://developer.twitter.com/en/docs/basics/authentication/api-reference/invalidate_access_token>

👑 AUTHOR 👑

Marc Mims <marc@questright.com>

This software is copyright (c) 2015-2021 by Marc Mims.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole page, bestie 🫶 this part came to you on perl v5.32.1, dated 2021-09-11, straight from Twitte...Methods(3pm) — go forth and post 💅✨

📦 where this page comes from