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:
-
Returns details about emotes that a channel owner created.
-
Returns details about emotes that Twitch created.
-
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 casestatic
since it’s the only supported value). - The {{theme_mode}} placeholder with one of the themes in the
theme_mode
field (in this caselight
). - The {{scale}} placeholder with one of the image sizes in the
scale
field (in this case1.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.