go-twitch/api/chat/get_channel_emotes.go

package chat

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"

	"go.fifitido.net/twitch/api/endpoint"
)

type GetChannelEmotesResponse struct {
	// The list of emotes that the specified broadcaster created.
	// If the broadcaster hasn't created custom emotes, the list is empty.
	Data []ChannelEmote `json:"data"`

	// A templated URL. Use the values from the id, format, scale, and theme_mode fields to replace the like-named placeholder strings
	// in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote.
	// For information about what the template looks like and how to use it to fetch emotes.
	// See Emote CDN URL format: https://dev.twitch.tv/docs/irc/emotes#cdn-template
	// You should use this template instead of using the URLs in the images object.
	Template string `json:"template"`
}

type ChannelEmote struct {
	// An ID that identifies this emote.
	ID string `json:"id"`

	// 	The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
	Name string `json:"name"`

	// The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background.
	//
	// NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs.
	Images EmoteImages `json:"images"`

	// The subscriber tier at which the emote is unlocked.
	// This field contains the tier information only if emote_type is set to subscriptions, otherwise, it's an empty string.
	Tier string `json:"tier"`

	// The type of emote. The possible values are:
	//
	// bitstier — A custom Bits tier emote.
	//
	// follower — A custom follower emote.
	//
	// subscriptions — A custom subscriber emote.
	EmoteType string `json:"emote_type"`

	// An ID that identifies the emote set that the emote belongs to.
	EmoteSetID string `json:"emote_set_id"`

	// The formats that the emote is available in.
	// For example, if the emote is available only as a static PNG, the array contains only static.
	// But if the emote is available as a static PNG and an animated GIF, the array contains static and animated.
	// The possible formats are:
	//
	// animated — An animated GIF is available for this emote.
	//
	// static — A static PNG file is available for this emote.
	Formats []EmoteFormat `json:"format"`

	// The sizes that the emote is available in.
	// For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0.
	// Possible sizes are:
	//
	// 1.0 — A small version (28px x 28px) is available.
	//
	// 2.0 — A medium version (56px x 56px) is available.
	//
	// 3.0 — A large version (112px x 112px) is available.
	Scales []EmoteScale `json:"scale"`

	// The background themes that the emote is available in. Possible themes are:
	//
	// dark, light
	ThemeMode []EmoteThemeMode `json:"theme_mode"`
}

// Gets the broadcaster’s list of custom emotes.
// Broadcasters create these custom emotes for users who subscribe to or follow the channel or cheer Bits in the channel’s chat window.
// Learn More: https://dev.twitch.tv/docs/irc/emotes
//
// For information about the custom emotes
// see subscriber emotes: https://help.twitch.tv/s/article/subscriber-emote-guide,
// Bits tier emotes: https://help.twitch.tv/s/article/custom-bit-badges-guide?language=bg#slots,
// and follower emotes: https://blog.twitch.tv/en/2021/06/04/kicking-off-10-years-with-our-biggest-emote-update-ever/
//
// NOTE: With the exception of custom follower emotes, users may use custom emotes in any Twitch chat.
//
// Requires an app access token or user access token.
func (c *Chat) GetChannelEmotes(ctx context.Context, broadcasterID string) (*GetChannelEmotesResponse, error) {
	v := url.Values{"broadcaster_id": {broadcasterID}}

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.Make(c.baseUrl, "chat/emotes", v), nil)
	if err != nil {
		return nil, err
	}

	res, err := c.client.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	statusOK := res.StatusCode >= 200 && res.StatusCode < 300
	if !statusOK {
		return nil, fmt.Errorf("failed to get channel emotes (%d)", res.StatusCode)
	}

	var response GetChannelEmotesResponse
	if err := json.NewDecoder(res.Body).Decode(&response); err != nil {
		return nil, err
	}

	return &response, nil
}