monkehTweets update – now supports Twitter API v1.1

Last week I committed quite a substantial update to the monkehTweets library on Github (also available via

For those who don’t know, Twitter have been working to update their API in the first big update since it’s launch, and v1.1 is the result of their work.

How Long Do I Have Left?

For all developers and applications currently using the previous versions of monkehTweets (and Twitter API v1 as a result) you have a rather generous amount of time to update your code and make the transition to the new API. Version 1 will be closed off and no longer available from the start of March 5th, 2013. (source:

The pre-v1.1 implementation of monkehTweets is still available via Github in it’s own branch, which is available here should you need it:


There have been a number of changes to the API, including revised endpoints to reflect the new API version number (1.1), but most of these should fall under the radar of users and implementors of the monkehTweets library as it will manage these for you.

The biggest changes to the API update are as follows:

  • All calls to the API require authentication (oauth)
  • All requests and responses will be in JSON format

It is important to note at this stage that the instantiation and use of monkehTweets itself has not changed. It was developed to be easy to use and to open up the detailed API for all CFML developers without having to instantiate Java classes. This has not changed and you can still get up and running in seconds. The example code in the project download will help you get your application set up and posting tweets very quickly.

How has monkehTweets dealt with these changes?

The authentication process was easy to manage. For the small number of methods that were making un-authenticated method calls, these were amended to run through the function dealing with the OAuth authentication. From a user point of view, this will have little to no impact on your existing code. As the application / user needs to be authenticated and those details are stored in the monkehTweets object, this will be handled invisibly for you.

The formatting was a little more detailed to change. All of the methods in monkehTweets used to have an argument called ‘format’ which used to default to XML. This allowed users to select the response format of the data to process in their preferred manner. The format arguments have now been stripped from all method calls, and the remote URL endpoints for each method have been forced to use JSON. If you are using XML responses you WILL need to amend your code to handle the new return format.

Method Changes

The following functions have been removed from monkehTweets as they were no longer supported in the v1.1 API:

  • addNotification
  • blockExists
  • endSession
  • friendshipExists
  • getAccountTotals
  • getDailyTrends
  • getLists
  • getNoRetweetIDs
  • getPublicTimeline
  • getRetweetedToUser
  • getRetweetsByMe
  • getRetweetsByUser
  • getRetweetsOfMe
  • getRetweetsToMe
  • getUserProfileImage
  • getWeeklyTrends
  • oauthRateLimitStatus
  • rateLimitStatus
  • removeNotification
  • retweetedBy
  • retweetedByIDs
  • test

If your application uses any of the above methods, you will need to revise the code to remove them and amend any functionality that depends on them.

The following functions have been added to monkehTweets as new additions in the v1.1 API:

  • closestTrends
  • getApplicationRateLimitStatus

All other methods remain active and current. Any changes made to existing methods in the monkehTweets library have been done as quietly as possible so as not to impact the code and therefore the implementation of the code. Method names have not been changed where possible to make the transition easier for you to manage.

Error Handling

One of the biggest issues I had with the ever-evolving Twitter API and method parameters was managing the error handling, certainly when trying to accomodate for a number of response formats.

In the previous version of the package, the requested format was passed through to the sub-methods along with the response to correctly format the data and attempt to check for any error codes before returning to the user. The Twitter API error processing changed and the code was unstable, certainly when dealing with XML responses.

Whilst my original intention was to trap any errors and return a user-friendly error message back to the user / developer, in the latest release I have completely dropped this functionality. This was done primarily for two reasons:

  1. It was unstable due to numerous changes from Twitter and I feared that if they changed their error handling again it would cause more errors.
  2. Having just one response format now made this easier. JSON will be returned regardless of whether the request was a success or failure.

This now means that users and developers will need to catch any errors from the API themselves. To help with this, Twitter have a fairly detailed list of error response codes to watch out for:

The example used on the site shows the error response in JSON format, and is a clear indication of what to watch out for:

More Information

For more information and clarification on the official changes to the Twitter API introduced in v1.1, please check out the API overview on the official documentation page:

Use monkehTweets?

Do you use monkehTweets? Has it saved you time, money, pain and stress? Let me know. I always look forward to seeing how people are using it in their applications.

If it really helped you, feel free to visit my Amazon wishlist and say thanks :)


  • Puc Covelli

    Hi Matt,

    I’ve been using your CF Twitter API for a few years now and its brilliant, thanks.

    I’ve just downloaded this latest version and I’ve noticed that the time taken to call getUserTimeline() has now doubled from around 0.5 second to nearly 1 second. Any reason for this?

  • Matt

    Hi Puc

    Thanks for the comment and for being a long-term monkehTweets user.
    I must admit that I haven’t noticed any speed or performance issues when running the unit tests. The getUserTimeline() method itself hasn’t changed from the previous code release. I’ll run some more tests to make sure nothing out of the ordinary is happening and let you know what I find.

  • Mark

    Hi Matt,
    I’m looking forward to implementing MonkehTweets vs. creating my own oAuth integration on 1.1. That said, I’m really struggling with getting the basic install working. I have unzipped and dropped package contents into htdocs, per the install instructions. I then instantiate a cffunction example based on the example in your readme (passing in my app consumer_key and consumer_secret).

    No matter what I do, however, I keep getting the error “Element OBJMONKEHTWEET is undefined in a Java object of type class [Ljava.lang.String” To be honest, the install instructions are not overly detailed for an oAuth/API noob like me. I’d be glad to beef up your install guide for use among a broader audience of technical experience if you can help me get this thing going.

    My app is a background process that will auth into Twitter via my account only (no multi-account support needed). On successful auth, I will call the user_timeline command. Return data will persist in my dB which the website/mobile web will access for content.

    I’m working out of htdocs/monkeh as a test location (where index, authorize, application.cfc are located) and the CFCs are in htdocs/monkeh/com/coldfumonkeh. I have maintained the exact directory structure of the unzipped package.

    What am I doing wrong?

    • mike

      I’m having the same issue as mark. I was using version 1.2 and just updated to 1.4. Now i’m recieving..
      Element OBJMONKEHTWEET is undefined in a Java object of type class [Ljava.lang.String;.
      The error occurred in C:/wamp/www/ip/twitter/index7.cfm: line 41
      41 : authStruct = application.objMonkehTweet.getAuthorisation(callbackURL=’http://XXXXXXXXXX’);

      • mike

        fixed my issue. i had to move location of Application.cfm

  • kartogram

    Hi Matt, API is really the best out there, so massive thanks for creating and maintaining it to date! One problem I’ve experienced today though – availableTrends function works, but trendByLocation doesn’t. Regardless if I pass ‘1’ or any other WOEID, it always returns error code 32 – Could not authenticate you. Any thoughts? I’ve checked your code comparing it to the official API documentation and it seems correct and all. Let me know whether you’re experiencing the same issue. BTW I’m using the latest version of it running through 1.1 endpoint.

  • Craig328

    Hi Matt:

    I’ve run into an issue where I’m unable to connect with an account I know is authorized and works. In order to check though I needed to be able to get a pass/fail response on the setFinalAccessDetails method of MonkehTweets.

    Is there a way to see if Twitter accepted the account token and secret for a particular account name? Your own examples have you attempting to post a tweet…but in my case, I don’t want that tweet to go through…I just need to be able to see if the user’s token and secret are still good and if not, give them the option to re-authorize my app.

    In short, is there a way to see if a setFinalAccessDetails call succeeds without trying to post something to the user’s account?

  • Simon

    Hi Matt, great work on the API. I’m using it on few projects for a while now. Recently we ran into a problem though. It seems that the getAccessToken call in the authorize.cfm file started to return ‘success:false’. The initial app authorisation in the index.cfm file goes through nicely though. It’s the next step that fails. Tried it on the existing app and a brand new one with exact same results. Any thoughts on that?

    • Matt

      Hi Simon, and thanks for your comment.

      I havent experienced that issue and hadnt noticed it yesterday when I pushed an updated version out to Github.
      I’ll run my unit tests on the library this evening to see if anything is happening. It _could_ be somethin on Twitter’s end (they have a habit of changing the API) but I’ll rule out my code first.

      I’ll let you know how I get on.

      Many thanks

      • Simon

        oh cheers for that! Waiting for the test results

      • Simon

        You know I’m starting to see that problem may not be with your code at all. Once I authorise the app as a user it returns me to the callback URL. However at this point the newly authorised app does not appear in the list of my apps in the Twitter settings. This way if my website is trying to perform the next step, which is to get user’s access token and secret, it gets a false response as Twitter doesn’t see the app in the user authorised apps list. Or am I missing something here?
        It’s really weird, as I even tried creating a completely new twitter app on a separate account, just to check whether I didn’t get blocked or something, and came to exact same result.

        • Matt

          Hi Simon.

          That does sound strange. Are the application permissions set up properly in the Twitter dev account area?

          • Simon

            Well, it turns out it’s a bit of my daftness mixed with the lack of research on the updates performed by Twitter. The SSL requirement was the thing that was missing. In other words, I’ve seen you had a post advising users to updated the authorisation endpoints to the https, and thought I did so. Turns out one of them was left as a plain connection, hence all the struggle.
            At least we now know what is the response from Twitter end when http is being used. It may help to someone else in the future.

            Also, it’s worth noting that if you use monkehTweets for multiple users and they were already authorised previously, Twitter continues to work. It’s when you try to add a new one and go over the authorisation process that it all breaks.

  • Simon

    It seems like. All those apps I’ve tested are set to the ‘Read, Write and Access direct messages’, which is the full scope.

  • Sn3akyP3t3

    Any known pros and cons of using MonkehTweets over the JavaScript Interfaces for Twitter for Websites solution provided by Twitter?