Overview
The Embedded Tweet feature allows websites to generate copy and paste-able HTML markup to render a Tweet on any third-party website. This markup presents a Tweet in an attractive (and display guidelines compliant) way, and automatically sets up Web Intents so that viewers of the Tweet may retweet, reply, favorite, and follow easily from the rendered view.
Search API will now always return "real" Twitter user IDs. The with_twitter_user_id parameter is no longer necessary. An era has ended. ^TS
— Twitter API (@twitterapi) November7, 2011
Copy & paste code
The easiest way to embed a Tweet is to visit the details page for the Tweet you wish to embed (for example, this Tweet) and click the Embed link, as highlighted in this image:
The resulting dialog will give you some customization options, as well as embeddable markup which you should copy and paste into the page you wish to embed the Tweet into:
The copy & paste code can be rendered in the following formats:
| HTML | Markup which may be copied and pasted directly into an HTML page to render the embedded Tweet. For example:
|
|---|---|
| Shortcodes | A shorthand notation for rendering the embedded Tweet on platforms which support Tweet shortcodes, such as wordpress.com. For example:
|
| Link | The URL of the Tweet. For example:
|
Twitter's oEmbed endpoint
While the copy and paste code is useful for content authors, some applications may wish to render these embedded Tweets dynamically. Fortunately, Twitter now supports an oEmbed endpoint which makes this possible.
To render a Tweet using oEmbed, the embedding site must:
- Obtain an URL to or ID number of the Tweet it wants to render.
- Make a request to the GET statuses/oembed endpoint, passing the Tweet URL or ID as a query parameter.
- Render the html property of the response, as well as a <script> element pointing to //platform.twitter.com/widgets.js, if needed.
The oEmbed standard allows a website to embed a representation of the contents of an URL into its own markup. The specification supports representing an URL as an image, a video, or even a snippet of rich HTML content. Twitter's implementation uses the rich HTML functionality to render a widget view of a Tweet.
Obtaining an URL to a Tweet and requesting Twitter's oEmbed endpoint are straightforward. Your code must pass either an ID or URL for the Tweet it wishes to embed to GET statuses/oembed, along with any additional querystring parameters it needs to render the Tweet appropriately. The response will encode enough data to embed the Tweet. For example, the response to https://api.twitter.com/1/statuses/oembed.json?id=133640144317198338&align=center is:
{"type": "rich",
"author_name": "Twitter API",
"cache_age": "31536000000",
"height": null,
"html": "<blockquote class=\"twitter-tweet tw-align-center\"><p>Search API will now always return \"real\" Twitter user IDs. The with_twitter_user_id parameter is no longer necessary. An era has ended. ^TS</p>— Twitter API (@twitterapi) <a href=\"https://twitter.com/twitterapi/status/133640144317198338\" data-datetime=\"2011-11-07T20:21:07+00:00\">November7, 2011</a></blockquote>\n<script src=\"//platform.twitter.com/widgets.js\" charset=\"utf-8\"></script>",
"author_url": "https://twitter.com/twitterapi",
"provider_name": "Twitter",
"version": "1.0",
"provider_url": "http://twitter.com",
"url": "https://twitter.com/twitterapi/status/133640144317198338",
"width": 550
}
Keep in mind that since the oEmbed endpoint is rate limited, you should cache this response and use the cached data instead of making a request per page load.
The response contains HTML markup which, when rendered along with the //platform.twitter.com/widgets.js script, will produce the embedded Tweet widget in your website. To do this, output the html portion of the response into your site template. If you are using a templating library, make sure to disable HTML entity encoding and sanitization for this piece of output, or else the HTML may not render correctly.
widgets.js
The HTML content from the copy & paste dialog or the oEmbed endpoint contains a <script> tag pointing to widgets.js. For example, from https://api.twitter.com/1/statuses/oembed.json?id=133640144317198338
<blockquote class="twitter-tweet"><p>Search API will now always return "real" Twitter user IDs. The with_twitter_user_id parameter is no longer necessary. An era has ended. ^TS</p>— Twitter API (@twitterapi) <a href="https://twitter.com/twitterapi/status/133640144317198338" data-datetime="2011-11-07T20:21:07+00:00">November 7, 2011</a></blockquote>
<script src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
Only one copy of widgets.js needs to be included per rendered page. If you already include a copy (for a Tweet button, for example) or need to render more than one Tweet, you can opt to remove the script reference from the oEmbed response by including the omit_script=true querystring parameter. The example URL becomes https://api.twitter.com/1/statuses/oembed.json?id=133640144317198338&omit_script=true, with the following response:
<blockquote class="twitter-tweet"><p>Search API will now always return "real" Twitter user IDs. The with_twitter_user_id parameter is no longer necessary. An era has ended. ^TS</p>— Twitter API (@twitterapi) <a href="https://twitter.com/twitterapi/status/133640144317198338" data-datetime="2011-11-07T20:21:07+00:00">November 7, 2011</a></blockquote>
To remove the script reference from the copy & paste code, just delete the <script> tag by hand.
Rendering a Tweet
The placeholder HTML has the benefit of still containing Tweet content even if users have Javascript disabled. This means that for web crawlers and screen readers, the Tweet content is still considered part of your page. An example of what this might look like is:
Most users will have Javascript enabled, though. They will see the fully rendered embedded Tweet, which contains Web Intents which enable taking actions such as replying, retweeting, and following directly from the embedded Tweet: 
Best practices
Cache the oEmbed response on your server. The oEmbed endpoint is rate-limited, so make sure you are not fetching it for every pageview you render.
Assume the embed HTML format will change. The HTML markup for the embed may change over time, so don't assume classnames or the DOM layout will stay the same. If you need to style the embedded HTML, wrap it in a parent element and style the parent.