Linking to content within Tweets

We recommend the following when rendering links within Tweets:

• Use the “url” value of a URL entity for the href attribute of an anchor tag.
• Use the “expanded_url” value of a URL entity for the title attribute of an anchor tag, so that when users hover over the link they see the fully expanded URL.
• Use the “display_url” value of a URL entity for the displayed text between opening & closing anchor tags. If you prefer not to display the truncated format, use the full “expanded_url” instead.
• Non-HTML based environments obviously require more creative approaches, but the spirit of t.co should be kept in mind. Display as appropriate for your environment.
• When a disruption in the ability to resolve t.co links occurs, it’s recommended to display t.co links unless you already have a resolution for the URL. t.co’s redirection and malware protection capabilities are fully intact when these disruptions occur.
   

Working with Tweet input text

• Request GET help / configuration once daily in your application and cache the “short_url_length_https” (the maximum length for HTTPS-based t.co links) for 24 hours.
• If you offer a “remaining character count” feature in a Tweet entry input field, consider URLs detected in user input with twitter-text as being equal in length to the current “short_url_length_https” value.
   

When are links wrapped with t.co? Do I need to make an extra API call?

Links will be wrapped when Twitter receives a Tweet using POST statuses/update or a direct message using POST direct_messages/new. The wrapped link will be contained in the response to a successful request. There is no need to make any extra API calls.
 

Will t.co-wrapped links always be the same length?

The maximum length of t.co URLs changes over time. Issue a request daily to GET help/configuration and examine the fields short_url_length and short_url_length_https to determine the current maximum length of wrapped URLs. These values do not change often.

It is important to note that it is not necessarily possible to know the length of a t.co URL before posting. Consider the short_url_length field a maximum possible length for a t.co-wrapped link. When designing a Tweet entry box, consider all URLs as equalling the maximum possible short_url_length.
 

How is it possible to calculate whether a Tweet with a link is going to be over the maximum character length?

Counting characters in Tweets remains mostly the same.

• If you are not using the opt-in features, only links shorter in length than a t.co URL will be wrapped by t.co. All links t.co-length or longer should be considered as t.co’s maximum length. For example, if help/configuration reports 20 characters as the maximum length, and a user posts a link that is 125 characters long, it should be considered as 20 characters long instead. If they post a link that is 18 characters long, it’s still only 18 characters long.
• If you are using the opt-in features, all URLs regardless of length should be considered to be the maximum length reported to you by help/configuration.

HTTPS-based URLs take an additional character for the additional “s” in the protocol aspect of the URL. You can better control the link tweeting experience by using the opt-in features offered today. Always use the values in GET help/configuration for best results.
 

My application or users already use URL shorteners. Will this break URL shortening and can my users opt-out?

URL shorteners will continue working with Twitter. Users will not be able to opt-out of using t.co, but developer use of Tweet Entities ensures that users always see links with more meaningful semantics.
 

How do I render links so that my users don’t have to see t.co everywhere?

Use Tweet Entities, which are included by default on API responses, to detect the character position of URLs relative to Tweet text, unwrapped URLs, and a suggested shortened display (like that used on Twitter.com). See this example from tmhOAuth for an example of consuming Tweet Entities in PHP.
 

Will my application break if I do nothing?

No. If you have not implemented entities support, your users may see only t.co links instead of more descriptive indications. Taking advantage of the opt-in features today insures protection against future changes.
 

Will there be a URL shortening or resolution API?

There is no resolution API (although Twitter's enterprise products provide URL expansion enrichments). URLs are wrapped automatically at time of Tweet or Direct Message submission. Resolved URLs are only available in the context of Tweet or Direct Message content as part of the entities response.
 

How are HTTPS links handled with t.co?

When a HTTPS-based URL is passed while link wrapping is enabled, a HTTPS-based t.co link will be produced. HTTPS-based t.co links are one character longer than standard t.co links to account for the protocol change. GET help/configuration will indicate the current length of both HTTPS and non-HTTPS t.co URLs.
 

Need help parsing Tweet text?