The whole Twitch API, typed.

01

Call a method, get typed data

No token to fetch, no header to set, no cursor to carry around. Pick an example and run it: on the left the program, on the right what the library does for it. In the chat example, type a message and the bot answers.

Look upEvery pageChat botGo live

const twitch = new Twitch({ clientId, clientSecret });

const user = await twitch.users.getByLogin("twitchdev");
if (!user) throw new Error("No such user");

const [channel] = await twitch.channels.get({
  broadcaster_id: user.id,
});
const followers = await twitch.channels
  .followers({ broadcaster_id: user.id })
  .total();

console.log(channel?.title, followers);

Simulated outputRun again

1. No token yet: one is requested, once.
2. POSTid.twitch.tv/oauth2/token200
3. GET/users?login=twitchdev200
4. GET/channels?broadcaster_id=141981764200
5. GET/channels/followers?broadcaster_id=141981764&first=1200
6. "Building the next thing" 2841907

// 250 streams: three requests, one array.
const top = await twitch.streams.get({ language: "fr" }).take(250);

for (const stream of top.slice(0, 3)) {
  console.log(stream.user_name, stream.viewer_count);
}

// Or walk every page without holding them all in memory.
for await (const stream of twitch.streams.get({ language: "fr" })) {
  if (stream.viewer_count < 1000) break;
}

Simulated outputRun again

1. GET/streams?language=fr&first=100200
2. GET/streams?language=fr&first=100&after=eyJiIjp7Ik9m...200
3. GET/streams?language=fr&first=100&after=eyJiIjp7IkN1...200
4. 250 collected, the rest of the third page is dropped.
5. nuit_blanche 18204
6. atelier_pixel 9311
7. LeGrandFroid 7754

const events = twitch.eventsub.websocket();

events.on(
  "channel.chat.message",
  { broadcaster_user_id: channel, user_id: bot },
  async (event) => {
    if (event.message.text !== "!ping") return;
    await twitch.chat.send({
      broadcaster_id: channel,
      message: "pong",
      reply_parent_message_id: event.message_id,
    });
  },
);

Simulated outputRun again

1. WebSocket open, session welcomed.
2. POST/eventsub/subscriptions202
3. margueritehello everyone
4. kowalczyk_devis the bot awake?
5. kowalczyk_dev!ping
6. POST/chat/messages200
7. your_botbotpong

Say something in chatSend

const hooks = twitch.eventsub.webhook({ callback, secret });

hooks.on(
  "stream.online",
  { broadcaster_user_id: "141981764" },
  (event) => {
    notify(`${event.broadcaster_user_name} is live`);
  },
);

// Signatures are verified before your handler runs.
export default {
  fetch: (request: Request) => hooks.handle(request),
};

Simulated outputRun again

1. POST/eventsub/subscriptions202
2. Twitch checks the callback: challenge answered.
3. stream.onlineTwitchDev
4. Signature valid, not a replay, not a duplicate.
5. notify: TwitchDev is live

02

Find your endpoint

Type what you want to do. Every method and every event type is here, with the token it needs, and each one links to its parameters, its return type and an example.

Search the API

• twitch.users.getByLogin()Gets one user by login name, or null when there is no such user.app or user token
• twitch.streams.get()Lists live streams, most viewers first.app or user token
• twitch.chat.send()Sends a message to a channel's chat.app or user token
• twitch.moderation.ban()Bans a user from a channel's chat.app or user token
• twitch.channels.followers()Lists the followers of a channel, most recent first.app or user token
• twitch.clips.create()Clips the last seconds of a live stream.user token
• channel.chat.messageA user sent a message in the chat room.event
• stream.onlineThe broadcaster started a stream.event

155 methods and 83 event typesBrowse the groups

03

What you stop writing

• Token plumbing

  The app token is requested when a call needs it. User tokens are refreshed before they expire, validated every hour as Twitch requires, and saved where you choose.

• Which token goes with which call

  Each endpoint knows whether it wants the app token or a user’s, and whose. moderator_id, broadcaster_id and sender_id default to whoever is acting.

• Cursors and page sizes

  await a list for one page, for await it for every item. Lists of more than 100 IDs are split, fetched in parallel and merged.

• Handling 429

  The rate limit headers are followed for each token, so requests wait their turn instead of failing. What is safe to retry is retried.

• Reconnect logic

  WebSocket, webhooks and conduits share one typed on(). Reconnects, resubscriptions, signature checks and duplicate deliveries are handled.

• Guessing at shapes

  Every parameter, response and event is typed. Events that come in several shapes narrow when you check their discriminator.

04

Three ways to receive events

The same on() on all three. Pick by where your code runs.

	WebSocket	Webhooks	Conduits
You need	Nothing to host	A public HTTPS URL	One process per shard
Subscribes with	A user token	The app token	The app token
Survives a restart	No, it subscribes again	Yes	Yes
Good for	Bots, desktop apps, a few channels	Servers and serverless functions	Many channels, scaled across processes

05

Where to go next

• 01
  Quick startInstall, create an application on Twitch, make your first call.
• 02
  Acting as a userSend chat messages, moderate, run polls: how user tokens are chosen for you.
• 03
  EventsChat messages, follows, subscriptions, streams going live, as they happen.
• 04
  RecipesComplete programs to copy: a chat bot, go-live alerts, moderation tools.
• 05
  ReferenceEvery method, every event type, every scope, every error.
• 06
  Coming from version 1What changed, and the new name of each old method.

twitch.api is an independent open source project. It is not affiliated with or endorsed by Twitch Interactive, Inc.