Getting Twitch Emotes

Emotes are emoticons that users can use in Twitch chat. When users type the emote’s name in the chat window, Twitch replaces the name with the emoticon (PNG or animated GIF).

If you want to display emotes in your application, Twitch offers three APIs to get them:

Get Channel Emotes

Returns details about emotes that a channel owner created.
Get Global Emotes

Returns details about emotes that Twitch created.
Get Emote Sets

Returns details about emotes that have a similar context. For example, all subscriber emotes that a channel created.

These APIs return information about an emote. For details about how to use the information to fetch an emote, see Using the CDN URL template to create an image URL.

Getting channel emotes

Twitch lets channel owners create their own emotes. These emotes are available to users who subscribe to or follow the channel, or cheer Bits in the channel’s chat window.

To get a list of the emotes that a channel created, send a GET request to the /chat/emotes endpoint. Use the broadcaster_id query parameter to specify the channel’s owner. For example, to get the emotes that the TwitchDev (141981764) channel created, send the following cURL request:

curl -X GET 'https://api.twitch.tv/helix/chat/emotes?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

And here’s what the response looks like:

{
  "data": [
    {
      "id": "emotesv2_4c3b4ed516de493bbcd2df2f5d450f49",
      "name": "twitchdevHyperPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/3.0"
      },
      "tier": "1000",
      "emote_type": "subscriptions",
      "emote_set_id": "318939165",
      "format": [
        "static",
        "animated"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    . . .
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

The name field contains the name that the user types in the chat window to get the emoticon to display. The emote_type field identifies what the user has to do to get the emote. In this case, the user gets the emote if they buy a tier 1 subscription. You can use the ID in the emote_set_id field to call the /chat/emotes/set endpoint to get related emotes (see Getting emote sets).

For information about how to use the id, format, scale, theme_mode, and template fields to fetch the emote, see Using the CDN URL template to create an image URL.

For more information about the response, see the Get Channel Emotes reference content.

Getting global emotes

Twitch creates a number of emotes that any user can use in any Twitch chat.

To get a list of emotes that Twitch created, send a GET request to the /chat/emotes/global endpoint.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

And here’s what the response looks like:

{
  "data": [
    {
      "id": "emotesv2_89f3f0761c7b4f708061e9e4be3b7d17",
      "name": "FamilyMan",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_89f3f0761c7b4f708061e9e4be3b7d17/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_89f3f0761c7b4f708061e9e4be3b7d17/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_89f3f0761c7b4f708061e9e4be3b7d17/static/light/3.0"
      },
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    . . .
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}    

The name field contains the name that the user types in the chat window to get the emoticon to display. For information about how to use the id, format, scale, theme_mode, and template fields to fetch the emote, see Using the CDN URL template to create an image URL.

For more information about the response, see the Get Global Emotes reference content.

Getting emote sets

Twitch groups emotes that have a similar context. For example, all subscriber emotes.

To get a list of emotes in an emote set, send a GET request to the /chat/emotes/set endpoint. Use the emote_set_id query parameter to specify the emote set to get. The Get Channel Emotes response contains the set’s ID.

You can specify up to 25 set IDs in one request. To get multiple sets, include the parameter for each emote set you want to get. For example, emote_set_id=1234&emote_set_id=5678.

The following cURL example returns emotes from emote set 301590448.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes/set?emote_set_id=301590448' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

And here’s what the response looks like:

{
  "data": [
    {
      "id": "304456832",
      "name": "twitchdevPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
      },
      "emote_type": "subscriptions",
      "emote_set_id": "301590448",
      "owner_id": "141981764",
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    . . .
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}    

The name field contains the name that the user types in the chat window to get the emoticon to display. The emote_type field identifies what the user has to do to get the emote. In this case, they’d have to subscribe to the channel. You can use the ID in the owner_id field to call the /chat/emotes endpoint to see what other emotes the channel offers (see Getting channel emotes).

For information about how to use the id, format, scale, theme_mode, and template fields to fetch the emote, see Using the CDN URL template to create an image URL.

For more information about the response, see the Get Emote Sets reference content.

Using the CDN URL template to create an image URL

Twitch stores emotes in a Content Delivery Network (CDN). Twitch uses the following standardized URL format to identify emotes in the CDN.

https://static-cdn.jtvnw.net/emoticons/v2/<id>/<format>/<theme_mode>/<scale>

The following table describes the placeholders specified in the standardized URL:

URL Option	Description	Valid Values
`id`	The emote’s ID.	Get the ID from the `id` field of the API response.
`format`	The format of the image to get. For example, a static PNG or animated GIF. Use `default` if you want the server to return an animated GIF if it exists, otherwise, a static PNG.	`static`, `animated`
`theme_mode`	The background theme of the emote.	`light`, `dark`
`scale`	The size of the emote.	`1.0` (small), `2.0` (medium), `3.0` (large)

NOTE: Although you may use the image URLs from the Images object, you are strongly encouraged to instead use the template to create the URL used to fetch the image.

Getting the values to use from the API response

Each emote API response contains the information you need to populate the template. The response contains information about only those emotes that are available to fetch. For example, in the following response, only static PNG emotes are available to fetch (see the format field).

      {
        "data": [
          {
            "id": "196892",
            "name": "TwitchUnity",
            "images": {
              "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/1.0",
              "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/2.0",
              "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/3.0"
            },
            "format": [
              "static"
            ],
            "scale": [
              "1.0",
              "2.0",
              "3.0"
            ],
            "theme_mode": [
              "light",
              "dark"
            ]
          },
          ...
        ],
        "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
      }

Based on the above response, you can form a URL that fetches a small, static PNG emote with a light background theme. To form the URL, replace:

The {{id}} placeholder with the ID in the id field.
The {{format}} placeholder with one of the formats in the format array (in this case static since it’s the only supported value).
The {{theme_mode}} placeholder with one of the themes in the theme_mode field (in this case light).
The {{scale}} placeholder with one of the image sizes in the scale field (in this case 1.0).

The well formed URL looks like:

https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/1.0

If you specify values that are not included in the response, the server returns 404 not found. For example, if you specify animated in the {{format}} placeholder but the emote doesn’t support animation, the request fails with 404.

TIP: Create URLs for all supported sizes and use resolution switching to let the browser select the correct one. Learn More

Example URLs and how they render

The following examples show using different image URL values and how they render.

Emote Image URL	Emote Image Rendered
https://static-cdn.jtvnw.net/emoticons/v2/304456827/static/light/3.0
https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/animated/dark/1.0
https://static-cdn.jtvnw.net/emoticons/v2/304456803/static/bright/1.0	This returns a 404 error because `bright` is not a valid theme.

NOTE: The third example perfectly illustrates why you should not form the URL without using the template and the list of supported values from the API response.