Web Intents

API version 1API version 1.1
Updated on Thu, 2013-04-18 13:34

By using Web Intents, you agree to the Developer Rules of the Road.

Make it easy to bring interactivity to Tweets that you display on the web.

Web Intents provide popup-optimized flows for working with Tweets & Twitter Users: Tweet, Reply, Retweet, Favorite, and Follow. They make it possible for users to interact with Twitter content in the context of your site, without leaving the page or having to authorize a new app just for the interaction. Web intents are mobile friendly, and super easy to implement.

Working with Web Intents

Web Intents are the simplest way to make the Tweets you display on your website interactive.

Web Intents automatically detect whether the end user is currently logged in to twitter.com and asks for login when necessary. If the user does not yet have a Twitter account, they'll have the opportunity to create one before realizing their original intention. No need to register an application or API key.

Web Intents don't require Javascript, but it makes it easier to pop them up most elegantly. We recommend rendering each Web Intent at 550px by 420px. If you use the provided pop-up Javascript, the heights will be adjusted for you. The pop-up will automatically close after the user has seen their intent to completion and users will be asked to confirm their action before it is executed.

Web Intents are also mobile browsing friendly and ready for use on iOS, Android, and most modern mobile devices. Web Intents are just URLs that are meant to be loaded in a browser window, whether the current window or one popped up via HTML or Javascript. While you can provide links to intents within IFRAMEs and widgets, the resultant pages cannot be loaded in an IFRAME.

Images for Twitter birds, stars for favoriting, icons for replying & retweeting are all available on our Image Resource. Consult our Display Guidelines for tips on rendering Tweets and other Twitter resources.

If your audience speaks a language other than English, we recommend you use localized intents. Consult our International glossary page to get the most accurate translations.

Get Started

Web Intents can be invoked flexibly through a light combination of Javascript and HTML and are meant to be opened in a new window.

The easiest way to use intents is to include this SCRIPT tag on any web page you wish to invoke an intent. If you've already setup the Tweet Button, you're already prepared for Web Intents.

When combined with standard anchor tags and familiar iconography like the examples below, this Javascript will automatically open a window of the appropriate size when clicked. You only need to load platform.twitter.com/widgets.js once.

  1. <script type="text/javascript" src="//platform.twitter.com/widgets.js"></script>
  2. <p><a href="https://twitter.com/intent/tweet?in_reply_to=51113028241989632">Reply</a></p>
  3. <p><a href="https://twitter.com/intent/retweet?tweet_id=51113028241989632">Retweet</a></p>
  4. <p><a href="https://twitter.com/intent/favorite?tweet_id=51113028241989632">Favorite</a></p>

Meet the Web Intents

Tweet or Reply to a Tweet

https://twitter.com/intent/tweet

This intent makes it easy for a user to tweet nearly anything from your site with a stylish #newtwitter-inspired Tweet Composer. Though easy to implement with minimal configuration, you can provide optional parameters to support a variety of scenarios including allowing for careful pre-preparation of Tweet text, replying, @mentioning, link sharing, and more.

The official icon for replying is . Other image resources »

Example retweet

Supported Parameters

  • url

    A fully-qualified HTTP or HTTPS-based URL, URL-encoded. The provided URL will be shortened with t.co and appended to the end of the Tweet.

    Usage Examples

    Trivial:
    Encoding a simple URL
    http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FIn_Watermelon_Sugar

    Complex:
    Encoding a URL with another URL already attached
    http%3A%2F%2Fbookmark.it%2F%3Furl%3Dhttp%253A%252F%252Fdev.twicodeer.com%252Fpages%252Fintents%2523tweet-intent

  • via

    A screen name to associate with the Tweet. The provided screen name will be appended to the end of the tweet with the text: "via @username" "Via" will be translated to the proper locality of the posting user, if supported. Potentially drives new followers to the target account.

    Usage Examples

    twicodeer

  • text

    Pre-prepared, properly UTF-8 & percent-encoded Tweet body text. Users will still be able to edit the pre-prepared text. This field has a potential of 140 characters maximum, but consider the implications of other parameters like url and via.

    Usage Examples

    Trivial: @twitterapi

    Complex: Farsi%20%D9%BE%D8%A7%D8%B1%D8%B3%DB%8C ( "Farsi پارسی" ) Try it

  • in_reply_to

    Associate this Tweet with a specific Tweet by indicating its status ID here. The originating Tweet Author's screen name will be automatically prepended to the reply.

    Usage Examples

    35782000644194304

  • hashtags

    Add context to the pre-prepared status update by appending #hashtags. Omit the "#" symbol and separate multiple hashtags with commas.

    Usage Examples

    twitter,twitterapi

  • related

    Suggest accounts related to the your content or intention by comma-separating a list of screen names. After Tweeting, the user will be encouraged to follow these accounts.

    You can provide a brief description of how the account relates by following the screen_name with a colon and text. Both the colon and the text should be URL-encoded. Usage Examples

    twitterapi,twittermedia,twitter

    twitterapi%3AFor%20platform%20info,twittermedia%3AFor%20great%20tips

Retweet a Tweet

https://twitter.com/intent/retweet

Retweets are a powerful way to enable your users to share your content with their followers.

The official icon for retweeting is . Other image resources »

Example retweet

Supported Parameters

  • tweet_id

    Every Tweet is identified by an ID. You can find this value from the API or by viewing the permalink page for any Tweet, usually accessible by clicking on the "published at" date of a tweet.

    Usage Examples

    36287294927413248

  • related

    Suggest accounts related to the your content or intention by comma-separating a list of screen names. After Tweeting, the user will be encouraged to follow these accounts.

    You can provide a brief description of how the account relates by following the screen_name with a colon and text. Both the colon and the text should be URL-encoded. Usage Examples

    twitterapi,twittermedia,twitter

    twitterapi%3AFor%20platform%20info,twittermedia%3AFor%20great%20tips

Favorite a Tweet

https://twitter.com/intent/favorite

Users favorite for a variety of reasons: when they love a Tweet, when they want to save it for later, or to offer a signal of thanks. The favorite intent allows you to provide this Tweet Action and follow up with relevant suggested accounts for the user to follow.

The official icon for favoriting is . Other image resources »

Example favorite

Supported Parameters

  • tweet_id

    Every Tweet is identified by an ID. You can find this value from the API or by viewing the permalink page for any Tweet, usually accessible by clicking on the "published at" date of a tweet.

    Usage Examples

    35782000644194304

  • related

    Suggest accounts related to the your content or intention by comma-separating a list of screen names. After Tweeting, the user will be encouraged to follow these accounts.

    You can provide a brief description of how the account relates by following the screen_name with a colon and text. Both the colon and the text should be URL-encoded. Usage Examples

    twitterapi,twittermedia,twitter

    twitterapi%3AFor%20platform%20info,twittermedia%3AFor%20great%20tips

Follow and Mini-Profile

https://twitter.com/intent/user

This Intent provides an unobtrusive way to link names of people, companies, and services to their Twitter accounts. The resultant popup prominently features the account's profile picture, bio, summary statistics, noteworthy followers, recent tweets and an easy-to-use Follow button.

A Twitter bird is an easy way to denote this intent. . More birds & other image resources »

Example follow

Supported Parameters

  • screen_name

    Every Twitter user has a screen name, but they are subject to change. We recommend using user_id whenever possible.

    Usage Examples

    biz

  • user_id

    Twitter User IDs are available from the API and uniquely identify a user.

    Usage Examples

    3308337

Localization

If you want to ensure that the Web Intent you're rendering is displayed in a specific language, you can pass a lang parameter to any Intent URL.

Supported Languages

Optimization

Re-evaluating content

If you've dynamically changed content on your page and want to re-evaluate anchor tags matching a.twitter-share-button or a.twitter-follow-button, you can execute the following on snippet of Javascript:

  1.  twttr.widgets.load();

Limited Dependencies

Some sites may prefer to embed the unobtrusive Web Intents pop-up Javascript inline or without a dependency to platform.twitter.com. The snippet below will offer the equivalent functionality without the external dependency.

  1. (function() {
  2.   if (window.__twitterIntentHandler) return;
  3.   var intentRegex = /twitter\.com(\:\d{2,4})?\/intent\/(\w+)/,
  4.       windowOptions = 'scrollbars=yes,resizable=yes,toolbar=no,location=yes',
  5.       width = 550,
  6.       height = 420,
  7.       winHeight = screen.height,
  8.       winWidth = screen.width;
  9.  
  10.   function handleIntent(e) {
  11.     e = e || window.event;
  12.     var target = e.target || e.srcElement,
  13.         m, left, top;
  14.  
  15.     while (target && target.nodeName.toLowerCase() !== 'a') {
  16.       target = target.parentNode;
  17.     }
  18.  
  19.     if (target && target.nodeName.toLowerCase() === 'a' && target.href) {
  20.       m = target.href.match(intentRegex);
  21.       if (m) {
  22.         left = Math.round((winWidth / 2) - (width / 2));
  23.         top = 0;
  24.  
  25.         if (winHeight > height) {
  26.           top = Math.round((winHeight / 2) - (height / 2));
  27.         }
  28.  
  29.         window.open(target.href, 'intent', windowOptions + ',width=' + width +
  30.                                            ',height=' + height + ',left=' + left + ',top=' + top);
  31.         e.returnValue = false;
  32.         e.preventDefault && e.preventDefault();
  33.       }
  34.     }
  35.   }
  36.  
  37.   if (document.addEventListener) {
  38.     document.addEventListener('click', handleIntent, false);
  39.   } else if (document.attachEvent) {
  40.     document.attachEvent('onclick', handleIntent);
  41.   }
  42.   window.__twitterIntentHandler = true;
  43. }());

How to Render a Tweet

Consult our Display Guidelines for more information »

Useful Resources

Implementation Examples