Troubleshooting link previews on Facebook and Twitter social shares

Facebook and Twitter allow you to decide what links to your action will look like. Here's what you need to know to get them looking just right on both platforms.

What are link previews?

How are link previews created?

How can you update link previews?

Troubleshooting a Facebook link preview

Troubleshooting a Twitter link preview (Twitter Card)

What are link previews?

When you post a link on Twitter or Facebook, a rectangular box with a few details about the web page you're linking to (like the page's title, description, and an image) will appear. That box is called a link preview (or a Card when it's on Twitter), and it can be a major factor in helping people decide to open a link.

This is an example of a link preview on Twitter for one of our blog posts:

And here's what that same link looks like on Facebook:

How are link previews created?

Both Facebook and Twitter have developed their own tags to identify what should be included in a link preview. These tags can be added in the underlying HTML code of a web page to give each social network specific instructions.

Below is an example of what some of these tags look like. (The first two lines are Facebook tags for page description and title, and the last two are the Twitter tags for the same).

When you post a link to a web page on Facebook or Twitter, the social network checks the underlying code of the page you're linking to for these tags.

If it finds those tags, it follows those instructions to put together the link preview.
If it doesn't find any specific tags, it relies on general HTML tags to make an educated guess about what the link preview should look like.

How can you update link previews?

The best way to update link previews is to edit the instructive tags that social networks use to create them, then prompt each social network to follow the new instructions.

The process varies a bit depending on the social network and on where your action is embedded, so read on for specific steps!

Troubleshooting a Facebook link preview

1. Start by registering as a Facebook/Meta Developer following this guide. (All you need is a Facebook account, no actual development expertise required!)

2. After you have made your Facebook account a Developer account, log into Facebook as you would normally. You now have access to Facebook's Sharing Debugger tool, which lets you see exactly what Facebook sees when it looks at your web page to create a link preview for it.

Start by entering the URL of the web page where your action is embedded and click on the 'Debug' button:

3. The next page is where you can see the results of that Debugging process. It's divided in four sections, and we'll focus on the second and third ones.

If you've already made changes to the web page that hosts your action you can go ahead and use that 'Scrape Again' button to bring those changes to the Facebook Link Preview.
If you're not sure how to make the changes required, read on.

When and how we last scraped the URL: this is where you can see when the last time that Facebook looked at the web page for link preview instructions was (including the super handy 'Scrape Again' button to ask them to take another look), the web page's URL, and what the link preview looks like currently.

Based on the raw tags, we constructed the following Open Graph properties: this section shows you any Open Graph tags on the web page instructing Facebook what to use for each part of the link preview (title, description, image, and alternative text for the image).

4. Check the 'Based on the raw tags...' section and take note of the specific parts of the link preview that aren't what you'd like them to be along with their respective tags.

If your action is embedded on a New/Mode action page, you don't need to edit the tags directly! Instead, you can update the link preview by following the steps described in our How to Set Up Social Cards for your Action Page guide.
If your action is embedded on another web page, use the Open Graph Markup guide from Facebook to add or edit existing tags in your web page.

5. Once you've completed the changes (either on the 'Social cards' tab of your New/Mode action page or on the tags in your web page), enter your web page's URL into Facebook's Sharing Debugger tool again, click the 'Debug' button to run the process, then click the 'Scrape Again' button.

This will prompt Facebook to take another look at your page, where it will find the updated information and use it to generate the link preview that you want. Success!

Troubleshooting a Twitter link preview (Twitter Card)

1. Log into your Twitter account and paste the URL of your action page into a new tweet (no need to post it!). Twitter will check the link and generate a Twitter Card for it.

2. To change the Twitter Card you'll need to make changes to the action page itself:

If your action is embedded on a New/Mode action page, you don't need to edit the tags Twitter uses directly! Instead, you can update the link preview by following the steps described in our How to Set Up Social Cards for your Action Page guide.
If your action is embedded on another web page, follow Twitter's Summary Card with Large Image guide to add any missing tags to your web page or to edit existing tags.

3. After completing the changes (either on the 'Social cards' tab of your New/Mode action page or on the tags in your web page), paste the link into a new tweet like you did in the first step to prompt Twitter to check the link again. You may need to do this a few times to get Twitter to pick up on the new tags but in the end you'll have an updated link preview :)

After a few minutes, Twitter should also update the Twitter Cards for that link on any existing tweets. If that doesn't happen, try following their instructions to refresh the Card.

Last updated: May 13, 2024