NAME Net::Twitter - Perl interface to twitter.com VERSION This document describes Net::Twitter version 1.22 SYNOPSIS #!/usr/bin/perl use Net::Twitter; my $twit = Net::Twitter->new(username=>"myuser", password=>"mypass" ); $result = $twit->update("My current Status"); $twit->credentials("otheruser", "otherpass"); $result = $twit->update("Status for otheruser"); DESCRIPTION http://www.twitter.com provides a web 2.0 type of ubiquitous presence. This module allows you to set your status, as well as review the statuses of your friends. You can view the latest status of Net::Twitter on it's own twitter timeline at http://twitter.com/net_twitter "new(...)" You must supply a hash containing the configuration for the connection. Valid configuration items are: "username" Username of your account at twitter.com. This is usually your email address. "user" is an alias for "username". REQUIRED. "password" Password of your account at twitter.com. "pass" is an alias for "password" REQUIRED. "useragent" OPTIONAL: Sets the User Agent header in the HTTP request. If omitted, this will default to "Net::Twitter/$Net::Twitter::Version (Perl)" "useragent_class" OPTIONAL: A LWP::UserAgent compatible class, e.g., LWP::UserAgent::POE. If omitted, this will default to LWP::UserAgent. "source" OPTIONAL: Sets the source name, so messages will appear as "from " instead of "from web". Defaults to displaying "Perl Net::Twitter". Note: see Twitter FAQ, your client source needs to be included at twitter manually. This value will be a code which is assigned to you by Twitter. For example, the default value is "twitterpm", which causes Twitter to display the "from Perl Net::Twitter" in your timeline. Twitter claims that specifying a nonexistant code will cause the system to default to "from web". Some testing with invalid source codes has caused certain requests to fail, returning undef. If you don't have a code from twitter, don't set one. "clientname" OPTIONAL: Sets the X-Twitter-Client-Name: HTTP Header. If omitted, this defaults to "Perl Net::Twitter" "clientver" OPTIONAL: Sets the X-Twitter-Client-Version: HTTP Header. If omitted, this defaults to the current Net::Twitter version, $Net::Twitter::VERSION. "clienturl" OPTIONAL: Sets the X-Twitter-Client-URL: HTTP Header. If omitted, this defaults to "http://x4.net/Net-Twitter/meta.xml". By standard, this file should be in XML format, as at the default location. "apiurl" OPTIONAL. The URL of the API for twitter.com. This defaults to "http://twitter.com/" if not set. "apihost" "apirealm" OPTIONAL: If you do point to a different URL, you will also need to set "apihost" and "apirealm" so that the internal LWP can authenticate. "apihost" defaults to "www.twitter.com:80". "apirealm" defaults to "Twitter API". "twittervision" OPTIONAL: If the "twittervision" argument is passed with a true value, the module will enable use of the API. If enabled, the "show_user" method will include relevant location data in its response hashref. Also, the "update_twittervision" method will allow setting of the current location. "credentials($username, $password, $apihost, $apiurl)" Change the credentials for logging into twitter. This is helpful when managing multiple accounts. "apirealm" and "apihost" are optional and will default to the standard twitter versions if omitted. "http_code" Returns the HTTP response code of the most recent request. "http_message" Returns the HTTP response message of the most recent request. "get_error" If the last request returned an error, the hashref containing the error message can be retrieved with "get_error". This will provide some additional debugging information in addition to the http code and message above. STATUS METHODS "update(...)" Set your current status. This returns a hashref containing your most recent status. Returns undef if an error occurs. This method's args changed slightly starting with Net::Twitter 1.18. In 1.17 and back this method took a single argument of a string to set as update. For backwards compatibility, this manner of calling update is still valid. As of 1.18 Net::Twitter will also accept a hashref containing one or two arguments. "status" REQUIRED. The text of your status update. "in_reply_to_status_id" OPTIONAL. The ID of an existing status that the status to be posted is in reply to. This implicitly sets the in_reply_to_user_id attribute of the resulting status to the user ID of the message being replied to. Invalid/missing status IDs will be ignored. "update_twittervision($location)" If the "twittervision" argument is passed to "new" when the object is created, this method will update your location setting at twittervision.com. If the "twittervision" arg is not set at object creation, this method will return an empty hashref, otherwise it will return a hashref containing the location data. "show_status($id)" Returns status of a single tweet. The status' author will be returned inline. The argument is the ID or email address of the twitter user to pull, and is REQUIRED. "destroy_status($id)" Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status. "user_timeline(...)" Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user. It's also possible to request another user's timeline via the id parameter below. Accepts an optional argument of a hashref: "id" ID or email address of a user other than the authenticated user, in order to retrieve that user's user_timeline. "since" Narrows the returned results to just those statuses created after the specified HTTP-formatted date. "since_id" Narrows the returned results to just those statuses created after the specified ID. "count" Narrows the returned results to a certain number of statuses. This is limited to 200. "page" Gets the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3". "public_timeline()" This returns a hashref containing the public timeline of all twitter users. Returns undef if an error occurs. WARNING: Twitter has removed the optional argument of a status ID limiting responses to only statuses greater than that ID. As of Net::Twitter 1.18 this parameter has been removed. "friends_timeline(...)" Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends. It's also possible to request another user's friends_timeline via the id parameter below. Accepts an optional argument hashref: "id" User id or email address of a user other than the authenticated user, in order to retrieve that user's friends_timeline. "since" Narrows the returned results to just those statuses created after the specified HTTP-formatted date. "since_id" Narrows the returned results to just those statuses created after the specified ID. "count" Narrows the returned results to a certain number of statuses. This is limited to 200. "page" Gets the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3". "replies(...)" Returns the 20 most recent replies (status updates prefixed with @username posted by users who are friends with the user being replied to) to the authenticating user. This method's args changed slightly starting with Net::Twitter 1.18. In 1.17 and back this method took a single argument of a page to retrieve, to retrieve the next 20 most recent statuses. For backwards compatibility, this manner of calling replies is still valid. As of 1.18 Net::Twitter will also accept a hashref containing up to three arguments. "since" OPTIONAL: Narrows the returned results to just those replies created after the specified HTTP-formatted date, up to 24 hours old. "since_id" OPTIONAL: Returns only statuses with an ID greater than (that is, more recent than) the specified ID. "page" OPTIONAL: Gets the 20 next most recent replies. USER METHODS "friends()" This returns a hashref containing the most recent status of those you have marked as friends in twitter. Returns undef if an error occurs. "since" OPTIONAL: Narrows the returned results to just those friendships created after the specified HTTP-formatted date, up to 24 hours old. "id" OPTIONAL: User id or email address of a user other than the authenticated user, in order to retrieve that user's friends. "page" Gets the 100 next most recent friends, eg "page=3". "followers()" This returns a hashref containing the timeline of those who follow your status in twitter. Returns undef if an error occurs. Accepts an optional hashref for arguments: "id" OPTIONAL: The ID or screen name of the user for whom to request a list of followers. "page" Retrieves the next 100 followers. "show_user()" Returns extended information of a single user. The argument is a hashref containing either the user's ID or email address: "id" The ID or screen name of the user. "email" The email address of the user. If "email" is specified, "id" is ignored. If the "twittervision" argument is passed to "new" when the object is created, this method will include the location information for the user from twittervision.com, placing it inside the returned hashref under the key "twittervision". DIRECT MESSAGE METHODS "direct_messages()" Returns a list of the direct messages sent to the authenticating user. Accepts an optional hashref for arguments: "page" Retrieves the 20 next most recent direct messages. "since" Narrows the returned results to just those statuses created after the specified HTTP-formatted date. "since_id" Narrows the returned results to just those statuses created after the specified ID. "sent_direct_messages()" Returns a list of the direct messages sent by the authenticating user. Accepts an optional hashref for arguments: "page" Retrieves the 20 next most recent direct messages. "since" Narrows the returned results to just those statuses created after the specified HTTP-formatted date. "since_id" Narrows the returned results to just those statuses created after the specified ID. "new_direct_message($args)" Sends a new direct message to the specified user from the authenticating user. REQUIRES an argument of a hashref: "user" ID or email address of user to send direct message to. "text" Text of direct message. "destroy_direct_message($id)" Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message. FRIENDSHIP METHODS "create_friend(...)" Befriends the user specified in the id parameter as the authenticating user. Returns the befriended user in the requested format when successful. This method's args changed slightly starting with Net::Twitter 1.18. In 1.17 and back this method took a single argument of id to befriend. For backwards compatibility, this manner of calling update is still valid. As of 1.18 Net::Twitter will also accept a hashref containing one or two arguments. "id" REQUIRED. The ID or screen name of the user to befriend. "follow" OPTIONAL. Enable notifications for the target user in addition to becoming friends. "destroy_friend($id)" Discontinues friendship with the user specified in the ID parameter as the authenticating user. Returns the un-friended user in the requested format when successful. "relationship_exists($user_a, $user_b)" Tests if friendship exists between the two users specified as arguments. ACCOUNT METHODS "verify_credentials()" Returns an HTTP 200 OK response code and a format-specific response if authentication was successful. Use this method to test if supplied user credentials are valid with minimal overhead. "end_session()" Ends the session of the authenticating user, returning a null cookie. Use this method to sign users out of client-facing applications like widgets. "update_location($location)" WARNING: This method has been deprecated in favor of the update_profile method below. It still functions today but will be removed in future versions. Updates the location attribute of the authenticating user, as displayed on the side of their profile and returned in various API methods. "update_delivery_device($device)" Sets which device Twitter delivers updates to for the authenticating user. $device must be one of: "sms", "im", or "none". Sending none as the device parameter will disable IM or SMS updates. "update_profile_colors(...)" Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com. These values are also returned in the show_user method. This method takes a hashref as an argument, with the following optional fields containing a hex color string. "profile_background_color" "profile_text_color" "profile_link_color" "profile_sidebar_fill_color" "profile_sidebar_border_color" "update_profile_image(...)") Updates the authenticating user's profile image. This takes as an argument a GIF, JPG or PNG image, no larger than 700k in size. Expects raw image data, not a pathname or URL to the image. "update_profile_background_image(...)") Updates the authenticating user's profile background image. This takes as an argument a GIF, JPG or PNG image, no larger than 800k in size. Expects raw image data, not a pathname or URL to the image. "rate_limit_status" Returns the remaining number of API requests available to the authenticating user before the API limit is reached for the current hour. Calls to rate_limit_status require authentication, but will not count against the rate limit. "update_profile" Sets values that users are able to set under the "Account" tab of their settings page. Takes as an argument a hashref containing fields to be updated. Only the parameters specified will be updated. For example, to only update the "name" attribute, for example, only include that parameter in the hashref. "name" Twitter user's name. Maximum of 40 characters. "email" Email address. Maximum of 40 characters. Must be a valid email address. "url" Homepage URL. Maximum of 100 characters. Will be prepended with "http://" if not present. "location" Geographic location. Maximum of 30 characters. The contents are not normalized or geocoded in any way. "description" Personal description. Maximum of 160 characters. FAVORITE METHODS "favorites()" Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter. This takes a hashref as an argument: "id" Optional. The ID or screen name of the user for whom to request a list of favorite statuses. "page" OPTIONAL: Gets the 20 next most recent favorite statuses, eg "page=3". "create_favorite()" Sets the specified ID as a favorite for the authenticating user. This takes a hashref as an argument: "id" Required. The ID of the status to favorite. "destroy_favorite()" Removes the specified ID as a favorite for the authenticating user. This takes a hashref as an argument: "id" Required. The ID of the status to un-favorite. NOTIFICATION METHODS "enable_notifications()" Enables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful. This takes a hashref as an argument: "id" Required. The ID or screen name of the user to receive notices from. "disable_notifications()" Disables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful. This takes a hashref as an argument: "id" Required. The ID or screen name of the user to stop receiving notices from. BLOCK METHODS "create_block($id)" Blocks the user specified in the ID parameter as the authenticating user. Returns the blocked user in the requested format when successful. You can find more information about blocking at . "destroy_block($id)" Un-blocks the user specified in the ID parameter as the authenticating user. Returns the un-blocked user in the requested format when successful. HELP METHODS "test()" Returns the string "ok" in the requested format with a 200 OK HTTP status code. "downtime_schedule()" Returns the same text displayed on when a maintenance window is scheduled, in the requested format. CONFIGURATION AND ENVIRONMENT Net::Twitter uses LWP internally. Any environment variables that LWP supports should be supported by Net::Twitter. I hope. DEPENDENCIES LWP::UserAgent JSON::Any Starting with version 1.04, Net::Twitter requires JSON::Any instead of a specific JSON handler module. Net::Twitter currently accepts JSON::Any's default order for loading handlers. HTTP RESPONSE CODES The Twitter API attempts to return appropriate HTTP status codes for every request. 200 OK: everything went awesome. 304 Not Modified: there was no new data to return. 400 Bad Request: your request is invalid, and we'll return an error message that tells you why. This is the status code returned if you've exceeded the rate limit (see below). 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren't valid. 403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying error message should explain why. 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such user). 500 Internal Server Error: we did something wrong. Please post to the group about it and the Twitter team will investigate. 502 Bad Gateway: returned if Twitter is down or being upgraded. 503 Service Unavailable: the Twitter servers are up, but are overloaded with requests. Try again later. You can view the HTTP code and message returned after each request with the "http_code" and "http_message" functions. TWITTER SOURCES All tweets are set with a source, so that setting your status from the web interface would display as "from web", and through an instant messenger would show "from im". It is possible to request a source entry from Twitter which will allow your tweets to show as "from YourWidget". Beginning in Net::Twitter 1.07 you may set this source by passing the "source" parameter to the "new" constructor. See above. Because of this, all statuses set through Net::Twitter 1.07 and above will now show as "from Perl Net::Twitter" instead of "from web". For more information, see "How do I get "from [my_application]" appended to updates sent from my API application?" at: TWITTER TERMINOLOGY CHANGES 1.12 through 1.18 As of July 19th, 2007, the Twitter team has implemented a change in the terminology used for friends and followers to alleviate confusion. Beginning in Net::Twitter 1.12 the methods were renamed, with the old ones listed as DEPRECATED. Beginning with 1.19 these methods have been removed. BUGS AND LIMITATIONS Please report any bugs or feature requests to "bug-net-twitter@rt.cpan.org", or through the web interface at . AUTHOR Chris Thompson The framework of this module is shamelessly stolen from Net::AIML. Big ups to Chris "perigrin" Prather for that. LICENCE AND COPYRIGHT Copyright (c) 2008, Chris Thompson . All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. DISCLAIMER OF WARRANTY BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.