TwitchEventSub

Twitch EventSub for Elixir.

Installation

The package can be installed by adding twitch_eventsub to your list of dependencies in mix.exs:

def deps do
  [
    {:hello_twitch_eventsub, "~> 0.3.0"}
  ]
end

If you are using the websocket eventsub, add:

  {:websockex, "~> 0.4"},

If you are using webhooks with Plug (and you are not already using Phoenix or Plug, add:

  {:plug, "~> 1.15"},

Setup

• You need to create an app on the Twitch Developer Console to get the client_id and client_secret.

Generating the OAuth token

• Add a redirect_uri to your app on the developer console that looks like: http://localhost:42069/oauth/callback
• [Optional] set TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET, and TWITCH_AUTH_SCOPE environment variables. For the auth scope you can use the example in the code block further down this page.
• Run mix help auth.token to see the available options. If you aren't using environment variables, you need to pass the options to the CLI command.
• To use the defaults, run mix twitch.auth --output priv.

Example Scopes

For scopes, I just use all the read scopes except for whisper and stream_key. If you want to do the same, just paste the below into the scopes field on the token generator page:

analytics:read:extensions analytics:read:games bits:read channel:read:ads channel:read:charity channel:read:goals channel:read:guest_star channel:read:hype_train channel:read:polls channel:read:predictions channel:read:redemptions channel:read:subscriptions channel:read:vips moderation:read moderator:read:automod_settings moderator:read:blocked_terms moderator:read:chat_settings moderator:read:chatters moderator:read:followers moderator:read:guest_star moderator:read:shield_mode moderator:read:shoutouts user:read:blocked_users user:read:broadcast user:read:email user:read:follows user:read:subscriptions channel:bot chat:read user:bot user:read:chat

If you want to do moderation things with this token, then you can add the required scopes for your actions found here https://dev.twitch.tv/docs/authentication/scopes.

Config files example (if using .twitch.json for local dev)

# config/runtime.exs

config :my_app,
  event_sub: [
    user_id: "123456",
    channel_ids: ["123456"],
    handler: MyApp.TwitchEvents,
    # Webhook secret is only if you are using webhooks.
    webhook_secret: System.fetch_env!("TWITCH_WEBHOOK_SECRET")
  ]

Config options (EventSub)

• :user_id - The twitch user ID of the user that your token is for.
• :channel_ids - The twitch user ID of the broadcaster channels that you are subscribing to.
• :handler - A module that uses TwitchEventSub and implements the TwitchEventSub.Handler behaviour.
• :subscriptions - Optional. The list of subscriptions to create. See below for more info. Defaults to:

# Default subscriptions.
~w[
  channel.chat.message channel.chat.notification
  channel.ad_break.begin channel.cheer channel.follow channel.subscription.end
  channel.channel_points_custom_reward_redemption.add
  channel.channel_points_custom_reward_redemption.update
  channel.charity_campaign.donate channel.charity_campaign.progress
  channel.goal.begin channel.goal.progress channel.goal.end
  channel.hype_train.begin channel.hype_train.progress channel.hype_train.end
  channel.shoutout.create channel.shoutout.receive
  stream.online stream.offline
]

All of the above subscriptions will work without passing conditions, as long as you provide the broadcaster_user_id and user_id fields to the config.

Other subscriptions require different conditions, so if you add them, you need to add the subscription as a map, and include the condition. Example:

config :my_app,
  event_sub: [
    subscriptions: [
      "channel.chat.message",
      "channel.chat.notification",
      "channel.ad_break.begin",
      "channel.cheer",
      # etc...
      # Add a map of attrs for subscriptions.
      # Required fields are `:name`, and `:condition`.
      # See the Twitch docs for the required and optional conditions.
      %{
        name: "channel.channel_points_custom_reward_redemption.add",
        condition: %{
          broadcaster_user_id: "1337",
          reward_id: "92af127c-7326-4483-a52b-b0da0be61c01"
        }
      }
    ]
  ]

Config options (Websocket-specific)

• :url - Optional. The URL for the Twitch EventSub websocket server. Defaults to Twitch.
• :keepalive_timeout - Optional. The keepalive timeout in seconds. Specifying an invalid, but numeric value will return the nearest acceptable value. Defaults to 10.
• :start? - Optional. A boolean value of whether or not to start the eventsub socket. Defaults to false if there are no event_sub config options.

Config options (Webhook-specific)

• :webhook_secret - The secret to be used when creating and receiving subscriptions.

Handler module

Create a bot module to deal with chat messages or events:

defmodule MyApp.TwitchEvents do
  use TwitchEventSub.Handler

  @impl true
  def handle_event("channel.follow", event) do
    # TODO: Do something when you get a follow?
  end
end

Starting Websocket

Examples of adding Twitch EventSub websocket to your application's supervision tree below.

# lib/my_app/application.ex in `start/2` function:
defmodule MyApp.Application do
  # ...
  def start(_type, _args) do
    children = [
      # ... existing stuff ...
      # Add the bot.
      {TwitchEventSub, Application.fetch_env!(:my_app, :event_sub)}
    ]

    # ...
  end
  # ...
end