twitch.eventsub

Every method of twitch.eventsub, with its parameters, what it returns and the token it needs.

subscribe

twitch.eventsub.subscribe(params, options?): Promise<EventSubSubscription<string, EventSubCondition<T>>>

Creates a subscription by hand. You rarely need it: the listeners returned by websocket, webhook and conduit subscribe for you.

Token: user for the WebSocket transport, app for webhooks and conduits. The scopes depend on the subscription type.

Parameters

Name	Type	Description
type required	T	Subscription type, such as channel.follow.
condition required	EventSubCondition<T>	What to listen to: which channel, which user… Its shape depends on the type.
transport required	EventSubTransportInput	Where Twitch delivers the events.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<EventSubSubscription<string, EventSubCondition<T>>>

Fields of EventSubSubscription

Name	Type	Description
id	string	ID of the subscription.
status	EventSubSubscriptionStatus	Current state. Only enabled subscriptions deliver events.
type	string	Subscription type, such as channel.follow.
version	string	Version of the subscription type.
condition	EventSubCondition<T>	Condition the subscription was created with.
created_at	string	When the subscription was created, as an RFC 3339 timestamp.
transport	EventSubTransport	Where the events are delivered.
cost	number	How much the subscription counts against your cost limit.

Example

await twitch.eventsub.subscribe({
  type: "stream.online",
  condition: { broadcaster_user_id: "141981764" },
  transport: { method: "webhook", callback: "https://example.com/twitch", secret },
});

Twitch reference

unsubscribe

twitch.eventsub.unsubscribe(id, options?): Promise<void>

Deletes a subscription. The app token is used unless you say otherwise: for a subscription created over WebSocket, pass { as: userId } with the user whose token created it.

Token: user for a WebSocket subscription, app otherwise.

Parameters

id: string

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.eventsub.unsubscribe(subscription.id);

Twitch reference

subscriptions

twitch.eventsub.subscriptions(params?, options?): Paginator<EventSubSubscription<string, Record<string, string>>, GetEventSubSubscriptionsBody>

Lists your subscriptions, oldest first. With the app token you get the webhook and conduit ones. Pass { as: userId } to get the WebSocket subscriptions created with that user’s token.

Token: app or user, see above.

Parameters

Name	Type	Description
status	EventSubSubscriptionStatus	Only subscriptions in this state.
type	(string & {}) | keyof EventSubTypes	Only subscriptions of this type.
user_id	string	Only subscriptions whose condition mentions this user.
subscription_id	string	Only the subscription with this ID.
conduit_id	string	Only subscriptions delivered through this conduit.
after	string	Cursor of the next page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<EventSubSubscription<string, Record<string, string>>, GetEventSubSubscriptionsBody>

Fields of EventSubSubscription

Name	Type	Description
id	string	ID of the subscription.
status	EventSubSubscriptionStatus	Current state. Only enabled subscriptions deliver events.
type	string	Subscription type, such as channel.follow.
version	string	Version of the subscription type.
condition	Record<string, string>	Condition the subscription was created with.
created_at	string	When the subscription was created, as an RFC 3339 timestamp.
transport	EventSubTransport	Where the events are delivered.
cost	number	How much the subscription counts against your cost limit.

Example

const page = await twitch.eventsub.subscriptions({ status: "enabled" });
console.log(page.raw.total_cost, "of", page.raw.max_total_cost);

Twitch reference

websocket

twitch.eventsub.websocket(options?): EventSubWebSocket

Opens a WebSocket listener: the simplest way to receive events, with nothing to host. Subscriptions are created with a user token.

Parameters

This method takes no parameters of its own.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

EventSubWebSocket

Fields of EventSubWebSocket

Name	Type	Description
url	string
WebSocket	WebSocketConstructor
#backend	SubscriptionBackend
#strategy	SessionStrategy
#connections	Connection[]
#where	Map<Entry, Connection>
#seen	BoundedMap<string, true>
#lifecycle	Emitter<SocketEvents>
sessionIds	string[]	IDs of the sessions currently established. Empty while disconnected.
connected	boolean	Whether at least one session is established.
entries	Map<string, Entry>
#byId	Map<string, Entry>
#events	Emitter<ListenerEvents>
size	number	Number of active subscriptions.

Example

const events = twitch.eventsub.websocket();
events.on("channel.follow", { broadcaster_user_id: id, moderator_user_id: id }, (event) => {
  console.log(`${event.user_name} followed`);
});

Twitch reference

webhook

twitch.eventsub.webhook(options): EventSubWebhook

Creates a webhook listener, for servers reachable from the internet. Subscriptions are created with the app token and survive restarts.

Parameters

This method takes no parameters of its own.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

EventSubWebhook

Fields of EventSubWebhook

Name	Type	Description
#backend	SubscriptionBackend
#callback	string
#secret	string
#subscribe	boolean
#maxAge	number
#seen	Map<string, number>	Message IDs already handled, with the time each one was seen. Oldest first.
entries	Map<string, Entry>
#byId	Map<string, Entry>
#events	Emitter<ListenerEvents>
size	number	Number of active subscriptions.

Example

const hooks = twitch.eventsub.webhook({ callback: "https://example.com/twitch", secret });
hooks.on("stream.online", { broadcaster_user_id: "141981764" }, (event) => {
  console.log(`${event.broadcaster_user_name} went live`);
});
export default { fetch: (request: Request) => hooks.handle(request) };

Twitch reference

conduit

twitch.eventsub.conduit(options?): EventSubWebSocket

Opens a WebSocket that serves one shard of a conduit. Subscriptions are created with the app token, so one process can follow any number of channels without holding a connection per user, and they survive restarts. Run one process per shard to spread the load.

Parameters

This method takes no parameters of its own.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

EventSubWebSocket

Fields of EventSubWebSocket

Name	Type	Description
url	string
WebSocket	WebSocketConstructor
#backend	SubscriptionBackend
#strategy	SessionStrategy
#connections	Connection[]
#where	Map<Entry, Connection>
#seen	BoundedMap<string, true>
#lifecycle	Emitter<SocketEvents>
sessionIds	string[]	IDs of the sessions currently established. Empty while disconnected.
connected	boolean	Whether at least one session is established.
entries	Map<string, Entry>
#byId	Map<string, Entry>
#events	Emitter<ListenerEvents>
size	number	Number of active subscriptions.

Example

const events = twitch.eventsub.conduit();
events.on("channel.chat.message", { broadcaster_user_id: channelId, user_id: botId }, (event) => {
  console.log(event.message.text);
});

Twitch reference