Chat Reference

While you can migrate from v3 to v5, know that v5 is deprecated and will be shutdown in the future. We prefer that you migrated directly to the new Twitch API.

Endpoint	Description
Get Chat Badges by Channel	Gets a list of badges that can be used in chat for a specified channel.
Get Chat Emoticons by Set	Gets all chat emoticons (not including their images) in one or more specified sets. If no set is specified, all chat emoticons are returned.
Get All Chat Emoticons	Gets all chat emoticons (including their images).
Get Chat Rooms by Channel	Gets the chat rooms in a specified channel that are visible to the specified user (identified by an OAuth token). For each chat room, a UUID is returned, which is unique across all of Twitch. The rooms returned depend on the user’s role with respect to the specified channel. For example, if the channel has general, moderator-only, and subscriber-only chat rooms, and the specified user is neither a moderator nor a subscriber for the channel, only information about the general chat room is returned.

Get Chat Badges by Channel

✎

Gets a list of badges that can be used in chat for a specified channel.

Authentication

None

URL

GET https://api.twitch.tv/kraken/chat/<channel ID>/badges

Optional Query String Parameters

None

Example Request

This gets a list of chat badges for channel 44322889.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/chat/44322889/badges'

Example Response

{
   "admin": {
      "alpha": "https://static-cdn.jtvnw.net/chat-badges/admin-alpha.png",
      "image": "https://static-cdn.jtvnw.net/chat-badges/admin.png",
      "svg": "https://static-cdn.jtvnw.net/chat-badges/admin.svg"
   },
   "broadcaster": {
      "alpha": "https://static-cdn.jtvnw.net/chat-badges/broadcaster-alpha.png",
      "image": "https://static-cdn.jtvnw.net/chat-badges/broadcaster.png",
      "svg": "https://static-cdn.jtvnw.net/chat-badges/broadcaster.svg"
   },
   "global_mod": {
      "alpha": "https://static-cdn.jtvnw.net/chat-badges/globalmod-alpha.png",
      "image": "https://static-cdn.jtvnw.net/chat-badges/globalmod.png",
      "svg": "https://static-cdn.jtvnw.net/chat-badges/globalmod.svg"
   },
   "mod": {
      "alpha": "https://static-cdn.jtvnw.net/chat-badges/mod-alpha.png",
      "image": "https://static-cdn.jtvnw.net/chat-badges/mod.png",
      "svg": "https://static-cdn.jtvnw.net/chat-badges/mod.svg"
   },
   "staff": {
      "alpha": "https://static-cdn.jtvnw.net/chat-badges/staff-alpha.png",
      "image": "https://static-cdn.jtvnw.net/chat-badges/staff.png",
      "svg": "https://static-cdn.jtvnw.net/chat-badges/staff.svg"
   },
   "subscriber": null,
   "turbo": {
      "alpha": "https://static-cdn.jtvnw.net/chat-badges/turbo-alpha.png",
      "image": "https://static-cdn.jtvnw.net/chat-badges/turbo.png",
      "svg": "https://static-cdn.jtvnw.net/chat-badges/turbo.svg"
   }
}

Get Chat Emoticons by Set

✎

Gets all chat emoticons (not including their images) in one or more specified sets.

Caution: When not specifying the emotesets parameter, this endpoint returns a large amount of data.

Authentication

None

URL

GET https://api.twitch.tv/kraken/chat/emoticon_images

Optional Query String Parameter

Name	Type	Description
`emotesets`	list of integers	Specifies the set(s) of emoticons to retrieve. If no set is specified, all chat emoticons are returned.

Example Request

This gets a list of emoticons in set 19151.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/chat/emoticon_images?emotesets=19151'

Example Response with Emotesets

{
   "emoticon_sets": {
      "19151": [{
         "code": "TwitchLit",
         "id": 115390
      }]
   }
}

Example Request

This gets a list of all emoticons.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/chat/emoticon_images'

Example Response without Emotesets

{
   "emoticons": [
      ...
      {
         "code": "TwitchLit",
         "emoticon_set": 19151,
         "id": 115390
      },
      ...
   ]
}

Get All Chat Emoticons

✎

Gets all chat emoticons (including their images).

Caution: This endpoint returns a large amount of data.

Authentication

None

URL

GET https://api.twitch.tv/kraken/chat/emoticons

Optional Query String Parameters

None

Example Request

This gets a list of all emoticons.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/chat/emoticons'

Example Response

{
   "_links": {
      "self": "http://api.twitch.tv/kraken/chat/emoticons"
   },
   "emoticons": [
      {
         "id": 115390,
         "regex": "TwitchLit",
         "images": [
            {
               "width": 28,
               "height": 28,
               "url": "https://static-cdn.jtvnw.net/jtv_user_pictures/emoticon-115390-src-b577ded8522fc1a1-28x28.png",
               "emoticon_set": 19151
            }
         ]
      },
      {
         "id": 80393,
         "regex": "Kappa",
         "images": [
            {
               "width": 28,
               "height": 28,
               "url": "https://static-cdn.jtvnw.net/jtv_user_pictures/emoticon-80393-src-cf7c8d03a4c5cb75-28x28.png",
               "emoticon_set": 15940
            }
         ]
      }
      ...
   ]
}

Get Chat Rooms by Channel

✎

Gets the chat rooms in a specified channel that are visible to the specified user (identified by an OAuth token). For each chat room, a UUID is returned, which is unique across all of Twitch.

The rooms returned depend on the user’s role with respect to the specified channel. For example, if the channel has general, moderator-only, and subscriber-only chat rooms, and the specified user is neither a moderator nor a subscriber for the channel, only information about the general chat room is returned.

If the user is a:	These types of chat rooms can be returned:
Moderator	moderator, subscriber, general
Subscriber	subscriber, general
General user (neither a moderator nor a subscriber)	general

Authentication

Required scope: any

URL

GET https://api.twitch.tv/kraken/chat/<channel ID>/rooms

Optional Query String Parameters

None

Example Request

This gets the chat rooms in channel 44322889 that are visible to the user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512y.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/chat/44322889/rooms'

Example Response

{
    "_total": 3,
    "rooms": [
        {
            "_id": "7596b8d6-3eca-4d73-8d0d-c82cc562b8dc",
            "owner_id": "44322889",
            "name": "subscribers",
            "topic": "subscribers only chat",
            "is_previewable": true,
            "minimum_allowed_role": "SUBSCRIBER"
        },
        {
            "_id": "04e762ec-ce8f-4cbc-b6a3-ffc871ab53da",
            "owner_id": "44322889",
            "name": "general-chat",
            "topic": "general chat",
            "is_previewable": true,
            "minimum_allowed_role": "EVERYONE"
        },
        {
            "_id": "7b039890-12ed-4102-b460-16638b3dc0f9",
            "owner_id": "44322889",
            "name": "mods-only",
            "topic": "private room for mods",
            "is_previewable": false,
            "minimum_allowed_role": "MODERATOR"
        }
    ]
}