oEmbed

What is oEmbed in WordPress?

oEmbed in WordPress is a protocol that lets you embed content from another website by pasting a link into your post or page. WordPress connects to the source site, collects the needed details, and adds the media to your content using this protocol.

What oEmbed Is

oEmbed is an open format created in 2008. Its main purpose is to make embedding content easier and safer. Instead of copying and pasting full HTML from another site, you only need a link. WordPress handles the rest behind the scenes.

How oEmbed Works in WordPress

There are two sides to oEmbed: the consumer and the provider.
– The consumer is the site where you want to display the content. In this case, WordPress is the consumer.
– The provider is the site hosting the original content, such as YouTube or Flickr.

When you paste a supported link into WordPress, it sends an HTTP request to the provider’s oEmbed API. The provider replies with information as a small JSON object with details like title, content type, width, height, and a link to the media. WordPress then uses this data to show the content as an embedded block instead of a link.

Example of a request sent to Flickr’s oEmbed endpoint:

http://www.flickr.com/services/oembed/?format=json&url=http%3A//www.flickr.com/photos/bees/2341623661/

Example JSON response from Flickr’s oEmbed:

json
{
    "version": "1.0",
    "type": "photo",
    "width": 240,
    "height": 160,
    "title": "ZB8T0193",
    "url": "http://farm4.static.flickr.com/3123/2341623661_7c99f48bbf_m.jpg",
    "author_name": "Bees",
    "author_url": "http://www.flickr.com/photos/bees/",
    "provider_name": "Flickr",
    "provider_url": "http://www.flickr.com/"
}

WordPress reads this response and creates the correct HTML to embed the image.

Supported Content Types

oEmbed works with content such as:
– Videos (YouTube, Vimeo)
– Images (Flickr, Imgur)
– Text and other resources

This lets you include many kinds of media from sites that support this protocol.

Default Whitelist and Security

WordPress includes a security whitelist for embedded content. Only links from approved providers will automatically embed. The goal is to stop untrusted sites or malicious code from being embedded in your posts. WordPress core keeps a list of trusted providers, which includes popular sites like YouTube, Twitter, and Flickr.

You can add new providers to this internal list or remove ones you do not want.

Adding oEmbed Providers in WordPress

To add a site that supports oEmbed to the list, use the function wp_oembed_add_provider().

Here is how you can add support for Flickr:

php
wp_oembed_add_provider( 'http://www.flickr.com/*', 'http://www.flickr.com/services/oembed/' );

his registers the URL pattern and the endpoint. Now, links from Flickr matching this pattern will be able to embed through oEmbed.

Adding Support for Sites Without oEmbed

Some sites do not use the oEmbed protocol. To support them, use the wp_embed_register_handler() function and supply a custom callback.

Here is an example:

php
wp_embed_register_handler( 'example', 'http://example.com/*', 'example_embed_handler' );
function example_embed_handler( $url, $attr, $post_ID ) {
    return '';
}

This registers a handler for links from example.com and sets up a function to generate the correct embed HTML.

Removing oEmbed Providers

You can remove an oEmbed provider with the function wp_oembed_remove_provider().

For example, to remove Flickr:

php
wp_oembed_remove_provider( 'http://www.flickr.com/*' );

This will stop WordPress from embedding content from Flickr links.

Common Use Cases

You can use oEmbed to include content from:
– Videos from YouTube in your posts
– Tweets from Twitter
– Photos from Imgur or Flickr

Many platforms, such as Medium and other blogging tools, use a similar method to embed outside content.

Typical Issues and Troubleshooting

You may find that some links do not embed if:
– The site is not in the WordPress whitelist
– The site does not support oEmbed
– There is a network error or bad response from the provider

If you need to add support for a site or fix an issue, you must register the provider or a custom handler as shown above.

oEmbed Protocol and WordPress Updates

The way to add, change, or remove oEmbed providers in WordPress still uses the functions described above. There are no big changes to how oEmbed is handled in recent versions of WordPress.

Usage Example

To embed a supported media link in WordPress:
1. Copy the link from the provider (such as YouTube)
2. Paste the link into your post or page, on its own line
3. WordPress fetches the embed code and inserts the media

This requires no manual HTML editing.