Chat Reference

Twitch API v5 is deprecated and will be removed on 12/31/18. The new Twitch API is live and we are actively adding new functionality to it.

Code samples are available on the Get Started page of the Twitch dev site.

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"
        }
    ]
}