Settings View Source TMI (Twitch Messaging Interface) for Elixir

Connect to Twitch chat with Elixir.

installation

Installation

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

def deps do
  [
    {:tmi, "~> 0.5.2"},
  ]
end

Documentation can be found at https://hexdocs.pm/tmi/readme.html.

usage

Usage

You can use your own Twitch username, but it is recommended to make a new twitch account just for your bot. You'll also need an OAuth token for the password.

The simplest method to get an OAuth token (while logged in to the account your bot will use), use the Twitch Chat OAuth Password Generator.

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

defmodule MyBot do
  use TMI

  @impl TMI.Handler
  def handle_message("!" <> command, sender, chat) do
    case command do
      "dice" ->
        say(chat, Enum.random(~w(⚀ ⚁ ⚂ ⚃ ⚄ ⚅)))

      "echo " <> rest ->
        say(chat, rest)

      "dance" ->
        me(chat, "dances for #{sender}")

      _ ->
        say(chat, "unrecognized command")
    end
  end

  def handle_message(message, sender, chat) do
    Logger.debug("Message in #{chat} from #{sender}: #{message}")
  end
end

Available handler callbacks:

handle_connected(server, port)
handle_logged_in()
handle_login_failed(reason)
handle_disconnected()
handle_join(chat)
handle_join(chat, user)
handle_part(chat)
handle_part(chat, user)
handle_kick(chat, kicker)
handle_kick(chat, user, kicker)
handle_whisper(message, sender)
handle_whisper(message, sender, tags)
handle_message(message, sender, chat)
handle_message(message, sender, chat, tags)
handle_mention(message, sender, chat)
handle_action(message, sender, chat)
handle_unrecognized(msg)
handle_unrecognized(msg, tags)

starting

Starting

First we need to go over the config options.

Config options

• :bot - The module that uses TMI and implements the TMI.Handler behaviour.
• :user - Twitch username of your bot user (lowercase).
• :pass - OAuth token to use as a password, prefixed with oauth:.
• :channels - The list of channels to join (lowercase).
• :capabilities - An optional list of :tmi capabilities, defined here. Can be any of: "membership", "tags", and "commands". Defaults to ['membership'] (lowercase).

Capabilities

• membership - Shows JOINs and PARTs, so you can see when a user joins or leaves chat. docs
• tags - Will give you a bunch of additional channel and user state data (badges, etc). docs
• commands - Gives you some Twitch-specific commands. If your bot plans to read commands, it must also use the tags capability because most commands are less useful or even meaningless without tags. docs

Example config

config :my_app,
  bots: [
    [
      bot: MyApp.Bot,
      user: "myappbot",
      pass: "oauth:myappbotpassword",
      channels: ["mychannel"],
      debug: false
    ]
  ]

add-to-your-supervision-tree

Add to your supervision tree

Single bot example:

[bot_config] = Application.fetch_env!(:my_app, :bots)

children = [
  # If you have existing children, e.g.:
  Existing.Worker,
  {Another.Existing.Supervisor, []},
  # Add the bot.
  {TMI.Supervisor, bot_config}
]

Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)

Multiple bots example:

bots = Application.fetch_env!(:my_app, :bots)
bot_children = for bot_config <- bots, do: {TMI.Supervisor, bot_config}

children = [
  # If you have existing children, e.g.:
  Existing.Worker,
  {Another.Existing.Supervisor, []}
  # Add the bot children.
  | bot_children
]

Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)

to-get-your-bot-verified

To get your bot verified:

Visit https://dev.twitch.tv/limit-increase/ and have a good reason prepared.