WordPress Plugin: Twitter Stream

/ WordPress Plugins / by Paul Robinson / 445 Comments
This post was published back on December 30, 2009 and may be outdated. Please use caution when following older tutorials or using older code. After reading be sure to check for newer procedures or updates to code.

It’s been just over a year now since I released my first plugin which you may all know is The Attached Image, so I thought it was time I released another plugin. I hadn’t actually gone out on purpose to make this plugin, but a client’s website needed a simple Twitter feed plugin & while there are already WordPress plugins out there that do the job they insisted a custom one be built. So I set about making it & rather than have it sit in my WordPress functions folder doing nothing (other than working on the client’s site, of course) I thought I should release it as a plugin for anyone to use. 🙂

Latest Info – 04/03/2013

If you have updated the plugin to version 2.5 and are having trouble, please make sure to delete the cache. Either manually or using the button on the options page.

What is Twitter Stream?

Twitter Stream is a very simple plugin originally created as a small function for a client’s website. Rather than have it sit doing nothing in my WordPress functions folder I thought I would extend it and make it into a plugin for everyone to use.

It’s functionality is very, very simple. It is designed to simply grab a set amount of status updates from the Twitter user account you request. If there are enough requests I may add some additional features, but for now it is designed to be very simple and run as quickly as possible while using the least amount of resources possible.

What Features Are There?

  1. Connect to Twitter securely using oAuth. (required)
  2. Show the twitter timeline for any public username.
  3. Choose how many tweets to show.
  4. A Widget or template function is available.
  5. File caching to stop API overuse.
  6. Optional date shown in xx ago format, also links to permalink for the tweet. (Requested by Ron)
  7. Customizeable via CSS. (see the ‘Can I Style It?’ section below)
  8. Authentication for better API limiting & ability for protected users to show their tweets.
  9. @replies now link to the user profile of the user you are replying to.
  10. #tags now link to the Twitter search page for that hash tag.
  11. Link to user’s profile, customizable via CSS & via function parameter.
  12. Follower count can now be shown.
  13. Retweets can now be shown with normal tweets.

How Do I Install It?

You can download it from the WordPress repository here, and then install it as you would any old style WordPress plugin, which is as follows:

  1. Download the zip file and unzip it to somewhere, say your desktop.
  2. With any good SFTP client upload the extracted folder to your wp-content/plugins/ folder.
  3. Enable the plugin in the WordPress plugin page.

Of course you can also install it by using the WordPress auto installer.

How Do I Use It?

Due to Twitter not having a solution for open source applications using oAuth yet, you must follow some slightly more complicated instructions to sign in via oAuth. Comprehensive instructions are provided in the plugin but here is a rough overview.

First you need to register a Twitter App, save the consumer keys you are provided with, then sign in with Twitter. As I said more detailed instructions are provided as you set up the plugin, including tips for what to enter when registering you app.

Finally you can show your tweets using a widget. The widget is a WP 2.8 & up compatible widget. If you are using a WP version lower than 2.8 you should really upgrade for security reasons if nothing else.

If you are a good ‘ol fashioned function user then you can call Twitter stream using:

Providing either a keyed array or an argument list. All the parameters available are listed here.

How Do You Get Round The API Limit?

Now that oAuth has been implemented API requests will be counted against your personal account rather than your servers IP address meaning that shared servers should no longer cause a problem. However to reduce the possibility of overusing the API even further caching is still in use.

Sometimes I Get An Error Message!

There is a built in error message that is shown if Twitter fails to provide a vaild XML file. Reasons for this could be that the Twitter API is down (which Twitter claim is highly unlikely), or the plugin failed to read the cache file. If this happens, and you know Twitter is available, try deleting the cache file which is named username.cache. You can do that using the brand new ‘delete cache’ button which is shown on the bottom of the authorization page. Just click ‘Twitter Stream’ under the settings menu to find it.

Sometimes The Date Is -xx Seconds Ago?

This is sometimes difficult to get your head around. Simply put it is caused by your servers clock being faster or slower than Twitters clock. To work out the time ago it takes the timestamp (number of seconds since Unix Epoc) and takes it away from the timestamp at which the tweet was posted. If your servers clock is slower than Twitters, for the first few seconds it ends up giving a negative value therfore seeming as if it was posted in the future. It could be something completely different involving Aliens, badgers and evil pidgeons, but that is the most sensible thing I’ve been able to come up with. If you have a better idea what it is let me know.

Sometimes oAuth Misses The Deny/Accept Page When I Press ‘Sign in with Twitter’?

This happens if you have already authorized Twitter Stream to be used with your Twitter account. Until you press the sign in button the plugin can’t tell if you have already given authorization or not. This generally happens if you have more than one blog using Twitter Stream with the same Twitter account. It’s perfectly normal though.

Can I Style It?

You can. I haven’t added any styles so I could keep the plugin on one file & keep it free of clutter. The available CSS classes are:

  1. .at-reply for @replys.
  2. .hash-tag for #tags.
  3. a.twitter-link for autolinked URL’s within the timeline.
  4. a:hover.twitter-link for autolinked URL’s within the timeline when they are hovered over.
  5. a.twitter-date for the date permalink.
  6. a:hover.twitter-date for the date permalink when it’s hovered over.
  7. .profile-link for the newly added link to user profile.
  8. .follower-count for the newly added follower count.

Can I Have A Options List?

Sure. The basic usage for in the template is this.

Here is the info for each parameter.

  • username should be a string and is the username of the Twitter timeline you want to return. No longer required. If omitted will show the user who authorized Twitter Stream’s timeline.
  • count should be a string and is how many tweets to return. Default ’10’.
  • date bool or string. If set to TRUE it will show the time ago with a hyphen as a default separator. If it is a string of anything other than ‘TRUE’, ‘true’ or ‘1’ it will use that as a separator.
  • profile_link a string. Allows you to customize what the link to your Twitter profile (shown at the bottom of the tweets) says. ‘Visit My Profile’ by default. Use a space, like this ‘ ‘, to show nothing.
  • retweets bool, true or false. Shows retweets with normal tweets.
  • show_followers bool, true or false. Shows the number of followers.
  • cache_time Set the length of time tweets are cached for.
  • echo Controls if the tweets should be echoed out to the page or returned as a SimpleXMLObject for manipulation via PHP. Defaults to TRUE, meaning echo tweets to page.

Here is an example using all parameters.

I Need A Translation!

You can download translations files for the plugin here. These are .po & .mo files in a zip for the languages available. For the translation to work you only need the .mo file placed in the same folder as the plugin.

I have provided the .po file for those who would like to amend or alter anything. Should you do that please send me a copy of the amended .po file so I can update the files here. If you would like to translate Twitter Stream into a language not available here you can download a blank .po file here. Once you’ve done the translation send it to me at admin [at] return-true [dot] com.

A huge thank you to those who have translated so far & a big thank you to anyone who may help in the future.

I Have A Feature Request! / I’ve Found A Bug!

You can report all bugs via the comments which I read as soon as I can, or you can send me an email via the contact page. Either way I promise to try and get back to you as soon as possible.

I Want To See A Working Demo?

Okay. Well the Twitter timeline here on Return True (on the right) is created using Twitter Stream. You can also see it on Medibolism & on Lisa Marie Art’s website.

Where Do I Get It Again?

Once again you can download it from the WordPress plugin repository here, or you can install it via the WordPress auto installer in your blog admin.

I Love It, Can I Give You Some Love?

Wait… What?!! Oh you mean that sort of love. Sure. 😛 You can help out in one of three ways. You can donate to help cover server costs & the cost of the coffee that keeps me coding. You can do that by clicking the button below.

You can buy me a present from my Amazon Wish List which would be very much appreated, or you can simply spread the word about Twitter Stream & The Attached Image.

Well that’s about it if you find any bugs or have any requests let me know.

Note: Twitter bird artwork in header image created by lisa-marieart.com. Used with permission.


Author’s gravatar

Hi Paul,

I try do customize the CSS for my website, but i’m not an expert. I want to do someting like you did, very easy to read. But i don’t know how to work with those class.

Can you feed me some code to more understand how this work. I do the one in previous comment to add bottom line, but can do more 🙁

thanks for your help, keep good work !!

Author’s gravatar author

Hi David,

I’d love to give you the code, but I don’t have time to write it out for you. Your best bet would be to try learning some CSS basics so that you can create your own designs with ease.

If you wanted to be brave you could also learn a compiled CSS language such as LESS or SASS along side CSS as they are extremely powerful & popular and it would be easier for you to learn them as you haven’t learnt the habits I have that make LESS & SASS harder for me to learn now.

I’m sorry I’m not able to help more but please try out CSS, you don’t even need a website or localhost to try it out on. Just create an HTML file & open it in your browser (CTRL+O) it will render no problem.

Author’s gravatar

Hello Paul,

Thank you very much for your twitter stream. I am trying to customize the widget but don’t really know where to find the CSS classes you mention (there is no css associated with this plugin). Shall we edit “style.css” from the theme?

Thanks for your support!


Author’s gravatar author

Hello Nico,

The plugin was designed so that it comes with no CSS at all. The classes I mention in the post are the classes that have been used in the HTML so that you can apply the CSS you wish.

Yes, your best bet would be to add the styles to your theme, unless you are using a theme that is updated regularly. Then you would be best off creating a child theme so that your additions are not wiped when you next update your theme.

Author’s gravatar

Paul-Just wanted to say thanks for your twitter stream. Its the only reliable twitter feed I have come across, is clean, well-documented and a pleasure to use. Thanks for a great contibution and keep up the good work!

Author’s gravatar author

Hi Sarah,

Thank you for the kind words Sarah. Glad you like the plugin. 🙂

Author’s gravatar

after entering the Consumer Key and Secret. It requests that I sign into twitter.
When doing so I get this error…

Could not connect to Twitter. Refresh the page or try again later. Code:401
Warning: Cannot modify header information – headers already sent by (output started at /home/feather1/public_html/wp-content/plugins/twitter-stream/redirect.php:25) in /home/feather1/public_html/wp-content/themes/complete-wp/_admin/functions-options.php on line 300

Warning: Cannot modify header information – headers already sent by (output started at /home/feather1/public_html/wp-content/plugins/twitter-stream/redirect.php:25) in /home/feather1/public_html/wp-content/themes/complete-wp/_admin/functions-options.php on line 301

Any help is greatly appreciated.

Author’s gravatar

I get the same problem as many others:

Could not connect to Twitter. Refresh the page or try again later. Code:401

I’m with HostGator (respected), I deleted the cache although that always fails, and have followed the instructions to a tee. Any guidance would be greatly appreciated!


Author’s gravatar author

Hi Jason & Larry (above),

A 401 error is returned by Twitter when it was unable to verify the oAuth request sent to their servers. This can occur for a few reasons and unfortunately most are caused by the host.

The first is that a PHP extension such as Suhosin is culling some of the data that is generated & sent over to Twitter, this is quite rare as Suhosin would have to be set to a very, very low number on POST & GET data to have this happen, but it has happened to me once with a client.

The second is that your server’s IP has been blacklisted by Twitter. This can happen on shared hosts as a lot of people share the same IP and it only takes one of those people to abuse the API for you all to be blocked.

The best thing to do, if possible, is to make sure your server is able to access Twitter via SSH using cURL if possible. The command to run via shell is:

curl --verbose "https://api.twitter.com/1/help/test.json"

If you see a bunch of output that looks like the pastebin here http://pastebin.com/vreUzBpE then you are connected successfully & there is no blacklisting problem.

That would point to it being a problem with the server not being able to connect to Twitter via PHP for some reason. If it a problem connecting & not blacklisting, it does seem to be a common problem & I’m not sure what the cause is. I’ve been unable to replicate it on any of my servers (I have a home server & this one that I host Return True on) as both access Twitter through Twitter Stream without any problems.

There are other ways to debug the problem, but they involve adding debug code to the oAuth library used in the plugin. If you would like me to guide you through how to do that please drop me an email via the contact form & I’ll let you know how.

Apologies for the problem, and I wish there was more I could do to help. 🙁

Author’s gravatar

I too was getting the 401 error. I *fixed* the issue by disabling ‘maintenance mode’. I was really surprised this made a difference, but it did, coincidence i don’t know, but it worked. Try it.

Author’s gravatar

I always get “Rate limit exceeded. Clients may not make more than 150 requests per hour.” how can i get rid of it? thanks ^^

Author’s gravatar

This is our website creditscoreresource.com and we always get “Rate limit exceeded. Clients may not make more than 150 requests per hour.” hope you can help me out fixing this thanks ^^

Author’s gravatar

Installed this on WP 3.3.1 and used the function call to try to display tweets. Settings page says “Twitter Stream Authorized!” So far so good. But I when I drop the twitter_stream(…) onto the page, I get “Sorry, that page does not exist” as the only thing echoed out. Hoping there’s an obvious issue…

Author’s gravatar author

Hi Derek,

Could you elaborate on this a little. ‘Sorry, that page does not exist’ is a error/message returned by your Theme or WordPress rather than Twitter Stream.

Author’s gravatar

Hi! Same issue here, using

in theme and after update to 2.4.1 “Sorry, that page does not exist”. Rolled back to 2.4 for the time being.

Author’s gravatar author


From what I can see all the oAuth end points in the plugin are correct, but rest assured I’m working on this and hope to have a fix out by the end of today.

Apologies for the inconvenience and thank you for your patience.

Author’s gravatar author

Thank you for your patience.

This should now be fixed in the update I’ve just committed to the SVN server. That would be version 2.5.

The errors were due to the fact Twitter (fairly silently) removed support for XML, which Twitter Stream used, in the new v1.1 API.

Author’s gravatar

Hi Paul,

Is there a way to filter the twitter feed which is displayed on a wordpress site using hashtags or keywords? IE: so only my tweets that relate to a specific topic are displayed?

Cheers and great plugin.


Author’s gravatar

Well, I found out it needs a module called curl. Otherwise I get a 500 server-error when trying to authorize.

Under Ubuntu you could use:
apt-get install php5-curl

Author’s gravatar

Hi there,

Is there a way to implement the twitter feed in my own custom html? Say if I wanted to wrap all the hashtags in a div, or throw in a small icon next to each tweet, would that be possible?

Also, since I have my Twitter account and Instagram account synced, it would be really cool if I could show the images posted with tweets, instead of just a link to the image. Would that be possible?



Author’s gravatar author

Hi Rasmus,

There are tags pre-wrapped around hashtags and each tweet is wrapped in a paragraph tag, so using a bit of CSS you should be able to do those things. Unfortunately without hacking the plugin you can’t alter the HTML at this point. It may be something I’d add in the future, but I’ve got so much work to do outside of my plugins that I can only maintain & help at the moment.

Unfortunately not, again it might be possible for me to add it in the future, but again work is preventing me from having time spare to add new features.


Author’s gravatar

Hi Paul,

Thank you for your reply! I would definitely love to see the ability to customize the HTML and also to display images from Twitter or Instagram. Hope you get some time in the future to implement that!

I can do some CSS styling, but for instance I’d like to display the date of the tweet as the first thing, before the actual tweet. For that, the best thing would be to alter the HTML.

Meanwhile, I have another question:

How do I use the “echo” parameter? As per your documentation, it “controls if the tweets should be echoed out to the page or returned as a SimpleXMLObject for manipulation via PHP”. Does this mean that if I set it to false, I should be able to interact with a SimpleXMLObject? What kind of manipulating would it be possible to do, and could you possibly point me in the right direction on how to do that?

Sorry for all the questions. I am obviously not a PHP wiz. I appreciate you taking the time!


Author’s gravatar author


No problem. As much as I’m limited on time I try my best to reply to any comments or fix any problems as soon as I can. 😉

That is actually one way you can do it. Using the ‘echo’ parameter. If you set it to false then it will return a JSON object. It used to be a SimpleXMLObject, but Twitter recently changed their format to JSON only when they upgraded their API. I just haven’t had a chance to change the docs yet.

With the JSON object you’d have access to all the data I use in the plugin so you could make your own HTML template. If you use:

The variable $response will contain the raw data returned from Twitter. This is a object that contains all the Tweets. To do something with it you can dome something like:

Hopefully that makes a little sense. If you are wondering where the twitter_stream_time_ago() function comes from. Well it’s a function I use in the plugin and since it is a global function you should be able to call it too.

I know this can seem complicated, but if you can afford to spend the time it can be very rewarding to get something like this working. If you do it this way, even if I update the plugin this code is very unlikely to break.

If you have any trouble then please do let me know & if you need more help than feasible here in the comments drop me an email either via the contact form or via my portfolio site and I’ll help out however I can.

Author’s gravatar


Awesome! Thank you so much! I will give it a go as soon as I get some more time to look at it. I will let you know how it works out or ask, if I get stuck.

Thanks again! 🙂

Author’s gravatar author

Not a problem. That’s probably the best way to customize the HTML, I hadn’t thought about it until you mentioned it, but it should allow you to change the HTML as you want and survive through any updates.

Please do just shout if you have any problems, or if you manage to get it working I’d love to hear from you. If everything goes well I’ll see if I can add a small tutorial to this post to help anyone else who wants to customize the HTML too. 🙂

Author’s gravatar

You may have to replace $tweet->id to $tweet-id_str on line 391 in the twitter-stream.php file. $tweet->id was returning some ridiculous number. Cool plugin! Thanks!

Author’s gravatar

Thank you a lot for this amazing wp-plugin! It’s just what I was looking for.

Author’s gravatar

Hi Paul,
First, thanks for the awesome plugin.
Second, is there a way to somehow wrap the plug-in’s widget into a scrollable box? What I am trying to do is to have a fixed height for the area the widget will display.. and if the tweets in the widget are longer than the fixed height there would be a scroll bar to thr right side allowing users to scroll downward to see the rest of the tweets.
I hope that makes sense.. let me know,

Author’s gravatar author

Hi Steve,

The plugin automatically generates a division (div) element around the tweets with the class of twitter-stream. You can use that as a scrollable element by using CSS to set a height for that class & then set the overflow to auto, if that doesn’t work you can try setting overflow-y to scroll.

Author’s gravatar

Thank you so much.. worked great!

Author’s gravatar

Hi Paul,

when I try to connect to my twitter account using the “/wp-admin/options-general.php?page=twitterstreamauth&wptwit-page=redirect” I get an 504 gateway timeout after 60 seconds.
Any idea why?

Thanks a lot!

Best regards,

Author’s gravatar author


A 504 is an unusual error to get in this case. It is most commonly an error returned when the server cannot contact the server-side language parser. It is most common on Nginx + PHP installs when PHP dies and cannot be contacted by Nginx. In this case it could be that either your server is, for some reason, having trouble completing the redirect request (which sends you to Twitter to authorize the plugin) or that you hit a time when Twitter’s servers were unavailable.

Do you still get this error now when you try? If so I would ask your hosting support if they can shed any light on the issue as it could be a problem or side-effect with/from the way PHP is setup.

Author’s gravatar

Hi and thanks for a very nice and simple Twitter Stream for WordPress! It works just fine for me displaying the tweets in my footer. Though there is some strange issue with the permalinks in the timestamps of the tweets. The links are broken and typically end with 4.5967329801276E+17 in stead of 459717020226191361 which is the correct id. Should I try to deauthorize the app and re-add it? Another question: All links to Twitter are in http-form, is it easy to change that to https?

Author’s gravatar author


I apologise for taking such a long time to reply. The site got hit badly with spam & trying to clean it up has been a nightmare.

I’m not sure what is happening there, the links are grabbed straight from the result supplied by Twitter. Is this still occurring for you? I’m not seeing it on my install, but I’m happy to take a look if you are still seeing the problem.

Author’s gravatar

Hello, thanks for this great plugin. I would like have the twitter feed appear on one page only so have tried using the shortcode. I tried a variety of things including

where I put in username keeping the quotes, and also tried without the quotes. I pasted this in the “Text” part, not “Visual” part. When I try to update the page WordPress (.org) deletes this line. I was able to get it to display properly with the widget, but I want it on only one page and not in a footer and sidebar but on the page, so I would like to use the code. Do you know what is causing this deletion to occur?


Author’s gravatar author

Hi Catherine,

Oh. I see what your issue is. There currently isn’t a shortcode available for Twitter Stream. The options are either the widget, or a PHP function that can be used in your theme files. That is why WordPress is stripping it as it is a PHP function call not a shortcode.

If you wish to use it you will either need to place it in template in your theme, or you can install a plugin that allows you to use PHP in your posts/pages. While I would not advise the latter, it is one way to get it working.

I am currently in the process improving Twitter Stream by rebuilding it using more modern coding standards as I’ve improved in my coding a lot since I first started writing this plugin. I will be sure to include a Shortcode in that version.

Author’s gravatar

Thanks for a brilliant plugin. Is there any way to hide replies? I’ve had a poke around in the code, but to no avail so far..

Author’s gravatar author

Hi Alex,

That option is available via the Twitter API, but sadly it wasn’t something I integrated into the plugin.

I can’t remember if it is because it wasn’t a popular idea or if it was actually because the API didn’t originally support it, but either way it isn’t available via the plugin at the moment.

I was doing an overhaul of the plugin to use the new API features and include a much more efficient caching system. However the UKs rising prices at the moment means I’ve been focusing on work so I can keep a roof over my head.

I can however tell you that if you want to add it manually you can find the code on line 278 of the main plugin file (twitter-stream.php). It looks like:

$content = $connection->get('statuses/user_timeline', array('screen_name' => $r['username'], 'count' => $r['count'], 'include_rts' => $r['retweets']));

Just add in the array key exclude_replies and set it to true. Just remember that the count option may not be accurately reflected as Twitter retrieve the tweets before filtering (their words, not mine).

Apologies for not being able to help by adding this into the plugin yet, but hopefully this helps you out a little.

Newer Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

I'll keep your WordPress site up-to-date and working to its best.

Find out more