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

View Source

Translates between Slack's IDs and human-friendly names.

Slack's RTM events almost always carry IDs ("U…", "C…", "G…", "D…",
"B…") rather than display names; these helpers resolve them either
direction against the live Slack.State your bot holds. All functions are
imported into modules that use Slack, so you can call them unqualified
from within callbacks.

The functions that accept "@USER_NAME" / "#CHANNEL_NAME" strings are
convenient but slow (linear scan over slack.users or slack.channels).
Prefer raw IDs in hot paths.

Username references are deprecated

Slack deprecated @username references in 2017; see the
changelog.
Functions that accept them log a warning on each call and may be removed
in a future major version.

Summary

Types

slack()

Functions

lookup_channel_id(arg, slack)

Resolves a "#CHANNEL_NAME" string to its ID.

lookup_channel_name(channel_id, slack)

Resolves a Slack channel ID to a "#CHANNEL_NAME" string.

lookup_direct_message_id(user, slack)

Resolves a user reference to its DM channel ID ("D…").

lookup_user_id(arg, slack)

Resolves a "@USER_NAME" string to a user ID ("U…").

lookup_user_name(direct_message_id, slack)

Resolves a Slack ID to a "@USER_NAME" string.

Types

slack()

@type slack() :: Slack.State.t()

Functions

lookup_channel_id(arg, slack)

@spec lookup_channel_id(String.t(), slack()) :: String.t() | nil

Resolves a "#CHANNEL_NAME" string to its ID.

Returns the channel's ID as "C…" for a public channel or "G…" for a
private channel/group. Returns nil if no channel with that name is known
to slack.

lookup_channel_name(channel_id, slack)

@spec lookup_channel_name(String.t(), slack()) :: String.t()

Resolves a Slack channel ID to a "#CHANNEL_NAME" string.

Accepts a public channel ID ("C…") or a private channel ID ("G…").
Returns the name prefixed with #.

lookup_direct_message_id(user, slack)

@spec lookup_direct_message_id(String.t(), slack()) :: String.t() | nil

Resolves a user reference to its DM channel ID ("D…").

Accepts either a user ID ("U…") or a "@USER_NAME" string (deprecated).
Returns nil if a DM channel with that user has not been opened yet —
Slack.Sends.send_message/3 will open one transparently in that case.

lookup_user_id(arg, slack)

@spec lookup_user_id(String.t(), slack()) :: String.t() | nil

Resolves a "@USER_NAME" string to a user ID ("U…").

Returns nil if no user with that name is present in slack.users.
Deprecated; see the module docs.

lookup_user_name(direct_message_id, slack)

@spec lookup_user_name(String.t(), slack()) :: String.t()

Resolves a Slack ID to a "@USER_NAME" string.

Accepts a user ID ("U…" or "W…"), a DM channel ID ("D…" — looked up
via the user on the other side of the DM), or a bot ID ("B…"). Returns
the name prefixed with @. Deprecated; see the module docs.