Slack.Bot (SlackKit v1.0.0-alpha.0)

View Source

Process that owns a bot's RTM WebSocket connection.

Slack.Bot is the runtime counterpart to the Slack behaviour: it opens the
WebSocket, decodes inbound frames, folds them into a Slack.State, and
dispatches each event to the user-supplied bot_handler module's callbacks.

Lifecycle

start_link/4 performs three steps:

  1. Hits Slack's rtm.start endpoint to fetch a one-shot WebSocket URL plus
    the bot's initial team/identity payload. The module that performs this
    can be overridden via config :slack, :rtm_module, … for tests.
  2. Spawns a Slack.WebSocketClient pointed at that URL with Slack.Bot
    itself as the callback module.
  3. Each inbound text frame is JSON-decoded, atomised, run through
    Slack.State.update/2, and forwarded to the user module's
    handle_event/3.

You generally won't call this module's callbacks directly — they implement the
Slack.WebSocketClient behaviour and exist to glue the socket to your bot.

Summary

Functions

start_link(bot_handler, initial_state, token, options \\ %{})

Connects to Slack and delegates events to bot_handler.

Functions

start_link(bot_handler, initial_state, token, options \\ %{})

Connects to Slack and delegates events to bot_handler.

Arguments

  • bot_handler — module implementing the Slack behaviour (typically a
    module that does use Slack).
  • initial_state — opaque value handed to the first callback invocation
    as the state argument. Threaded through callbacks from then on.
  • token — the Slack API token for this bot.
  • options — map of optional settings (see below).

Options

  • :keepalive — milliseconds between WebSocket keepalive pings. Defaults
    to 10_000.
  • :name — registers the spawned process under the given atom via
    Process.register/2. Defaults to nil (unregistered).
  • :client — module that backs the WebSocket transport. Must implement
    start_link/4 and cast/2. Defaults to Slack.WebSocketClient;
    tests swap in a stub.

Return values

Returns {:ok, pid} on a successful RTM handshake, or {:error, reason} on
failure. Known reasons include:

  • "Timed out while connecting to the Slack RTM API"
  • "Could not connect to the Slack RTM API" — DNS resolution failed
  • "Sent too many connection requests at once to the Slack RTM API." —
    Slack has rate-limited the rtm.start endpoint
  • any other error returned by the underlying HTTP client

Examples

{:ok, pid} = Slack.Bot.start_link(MyBot, [], "xoxb-…", %{name: :my_bot})

:sys.get_state(:my_bot)