t.co links

Tens of millions of links are tweeted on Twitter each day. Wrapping these shared links helps Twitter protect users from malicious content while offering useful insights on engagement. All links submitted within tweets and direct messages, regardless of length, will eventually be wrapped with t.co.

How Twitter wraps URLs

Twitter uses twitter-text to parse status bodies and extract the entities, including URLs, that are returned with tweet responses.

At this time, the general rule of thumb as to which URLs will be wrapped in t.co:

Trailing periods and commas, unless URL-encoded, are ignored and not considered part of a URL. Two URLs connected by a period or comma will not be parsed.

The URL should not include login information. ( https://user:password@twitter.com/ will not be wrapped )

We’re frequently making improvements to our parsing engine and because twitter-text is hosted on Github, you’re welcome to submit pull requests for bug fixes or parsing improvements.

Best Practices

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 our 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 ability to resolve t.co links occur, 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 in tact when these disruptions occur.

Working with tweet input text

Request GET help / configuration once daily in your application and cache the “short_url_length” (t.co’s current maximum length value) for 24 hours. Cache “short_url_length_https” (the maximum length for HTTPS-based t.co links) and use it as the length of HTTPS-based URLs.

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” value.

FAQ

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. You don’t need to make any extra API calls.

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

The maximum length of t.co URLs will change 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. We do not expect these values to change often.

It is important to note that you won’t necessarily 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, it’s best to consider all URLs as equalling the maximum possible short_url_length.

How do I calculate if a Tweet with a link is going to be over 140 characters or not?

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 as they always have. While users won’t be able to opt-out of using t.co, developer use of Tweet Entities insures 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?

Not at this time. 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 accompanying the content.

How long are t.co links?

At the time of writing, HTTP-based t.co links are 22 chars long. This will increase with time. Be sure to check the GET help/configuration endpoint to get the current max t.co link length.

How do I provide my users with analytics about the links they share on Twitter?

Link wrapping provides an opportunity to learn how users engage with links contained in tweets. In the future, we may offer a set of APIs that developers can leverage to enrich their applications with gathered data.

How are HTTPS links handled with t.co?

When a HTTPS-based URL is passed while link wrapping is enabled using POST statuses/update or POST direct_messages/new, 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.

Why did help/configuration begin returning 23 character lengths but t.co still wraps at 22?

The lengths reported by GET help / configuration as maximums. It’s possible you can get a t.co link that is less characters long than the maximum.

Need help parsing tweet text?

Take a look on the Twitter text processing library we’re using for auto linking and extraction of usernames, lists & hashtags.