Instagram Shortcode in Hugo

Hugo it self has built-in Instagram shortcode supports, but for some reason it can’t be used anymore. In this article i will write about how to solve this problem in your Hugo environment.

Messages from Facebook
Facebook announced v11.0 of the Graph API and Marketing APIs. With this update, there are new requirements to be able to access oEmbed APIs. To continue accessing the oEmbed APIs, you will have to submit your app for review by September 6th, 2021. If you want to request new access to the oEmbed APIs, you will also need to submit your app(s) for review.

Instagram Shortcode

Hugo version 0.84.0-DEV now requires Facebook access token to accesing Instagram oEmbed according to this commit. But, they are still using deprecated Facebook APIs v8.0.

If you are using Instagram shortcode in Hugo and having an issue with it, you are not the only one. Using Instagram shortcode with {{< instagram "BWNjjyYFxVx" "hidecaption" >}} will generate an error like this:

Failed to get JSON resource "": Failed to retrieve remote file: Bad Request

At the moment, Hugo using deprecated oEmbed-legacy linked API endpoint. Those deprecated API causes an error when Hugo retrieving the data. This is also happen with the Hugo Continuous Integration build which force Erik to allow getJSON errors to be ignored with this commit.

Problem Solving

Facebook Developers lead us to use the newest Instagram oEmbed endpoint instead. This topic is being discused in #7879. Using the newest API is required to create a Facebook App to generate App ID and Client Token.

Facebook App Configuration

  1. Create an app in Facebook Developers Page
  2. Add Instagram Graph API and oEmbed to your facebook app
  3. Don’t forget to activate oEmbed plugin
    Instagram Graph Api and oEmbed Plugins
  4. Find and copy App ID in top left corner and use it for .Site.Params.oembed.appId
  5. Go to Settings > Advanced > Security
  6. Copy Client Token and use it for .Site.Params.oembed.clientToken
    Facebook App ID and Client Token

Theme Configuration

After you get both App ID and _Client Token, follow these instruction below:

  1. Create an oembed.html in YourProject/layouts/shortcodes

    At this point we will integrate url query string parameter both Instagram Post and TV. The $type parameter with p will stand for Instagram Post and tv for Instagram TV. The ig parameter will confirm that the oEmbed used is for Instagram.

    {{- $oe := .Site.Params.oembed -}}
    {{- $appId := $oe.appId -}}
    {{- $clientToken := $oe.clientToken -}}
    {{- if not $oe.privacy -}}
    {{ $host := .Get 0 }}
    {{ $type := .Get 1 }}
    {{ $id := .Get 2 }}
    {{ $hideCaption := cond (eq (.Get 3) "hidecaption") "1" "0" }}
    {{ with getJSON "" $type "/" $id "/&hidecaption=" $hideCaption "&access_token=" $appId "|" $clientToken }}{{ .html | safeHTML }}{{ end }}
    {{- end -}}
  2. Add front matter in config.toml:

      appId = "YourAppId"
      clientToken = "YourClientToken"
      privacy = false
  3. Create an example instagram input in your markdown:

a. Sample input of Instagram Post

{{< oembed "ig" "p" "BWNjjyYFxVx" "hidecaption" >}}

b. Sample input of Instagram TV

{{< oembed "ig" "tv" "BkQUbR8h1sp" "hidecaption" >}}
  1. The rendered output will be like this:
Update May 2023
Sample output may not work because Facebook API has been deactivated

a. Sample output of Instagram Post

b. Sample output of Instagram TV

At last, you can enjoy to use Instagram shortcode in Hugo without any problems. Have a good day! 😉