slackline

The Slack platform for Gleam: every Web API method, Block Kit, the Events API, interactivity, OAuth and Socket Mode, typed from the official reference at https://docs.slack.dev.

The Web API side does no IO. Each method in slackline/api/* takes its required arguments and returns a Call: an HTTP request plus a decoder for its response. Optional arguments are setters in a module named after the method. Send the call with the HTTP client for your target:

import slackline
import slackline/api/chat
import slackline/api/chat/post_message
import slackline/httpc

pub fn main() {
  let client = slackline.new("xoxb-your-token")
  let assert Ok(posted) =
    chat.post_message(channel: "C123", text: "hi")
    |> post_message.unfurl_links(False)
    |> httpc.send(client)
  posted.ts
}

A Call(method, a) carries its method as a type, such as chat.PostMessage. A setter only accepts calls to its own method.

slackline/httpc sends on Erlang and slackline/fetch sends on JavaScript. For any other client, build the request with request and decode the response with response.

Methods that return pages take a cursor and return response_metadata. next_page gives the call for the next page:

let call = conversations.list()
let assert Ok(page) = httpc.send(call, client)
case slackline.next_page(call, page.response_metadata) {
  Some(next) -> todo as "send next"
  None -> todo as "that was the last page"
}

httpc.fold_pages and fetch.fold_pages do the whole loop.

Types

Call

opaque </>

One Web API method call: its name, its arguments and how to decode a successful response. method names the method as a type, such as chat.PostMessage, and a is the decoded response.

pub opaque type Call(method, a)

Client

opaque </>

The token to call the Web API with, and where to send calls.

pub opaque type Client

Error

</>

Everything that can go wrong calling the Web API.

pub type Error {
  ApiError(error: String, response: value.Value)
  RateLimited(retry_after: Int)
  UnexpectedResponse(status: Int, body: String)
  DecodeError(errors: List(decode.DecodeError), raw: value.Value)
  TransportError(reason: String)
}

Constructors

```
ApiError(error: String, response: value.Value)
```
Slack answered with "ok": false. error is the error code, such as "channel_not_found". response is the whole body, which can carry details such as the needed and provided scopes.
```
RateLimited(retry_after: Int)
```
Slack is rate limiting this method. Wait retry_after seconds.
```
UnexpectedResponse(status: Int, body: String)
```
The response was not the json Slack normally sends.
```
DecodeError(errors: List(decode.DecodeError), raw: value.Value)
```
The response was ok but did not match slackline’s types. raw holds the data. Report the mismatch as a bug.
```
TransportError(reason: String)
```
The HTTP client failed before getting a response.

FileUpload

</>

File contents a call sends as a multipart/form-data part, such as the image of users.setPhoto. For ordinary file sharing use files.getUploadURLExternal instead, which takes plain bytes.

pub type FileUpload {
  FileUpload(
    filename: String,
    content_type: String,
    contents: BitArray,
  )
}

Constructors

```
FileUpload(
  filename: String,
  content_type: String,
  contents: BitArray,
)
```
Arguments

filename

The name Slack shows for the file, such as "avatar.png".

content_type

The media type, such as "image/png".

Raw

</>

The method type of calls built with raw.

pub type Raw

ResponseMetadata

</>

Pagination and warning details Slack attaches to many responses.

pub type ResponseMetadata {
  ResponseMetadata(
    next_cursor: option.Option(String),
    warnings: option.Option(List(String)),
    messages: option.Option(List(String)),
  )
}

Constructors

```
ResponseMetadata(
  next_cursor: option.Option(String),
  warnings: option.Option(List(String)),
  messages: option.Option(List(String)),
)
```
Arguments

next_cursor

Pass this as cursor to fetch the next page. Empty on the last page.

warnings

Warning codes, such as missing_charset.

messages

Human-readable details about warnings or errors.

Values

anonymous

</>

pub fn anonymous() -> Client

A client without a token, for methods such as oauth.v2.access that authenticate with client credentials instead.

decode_with

</>

pub fn decode_with(
  call: Call(m, a),
  decoder: decode.Decoder(b),
) -> Call(m, b)

Replaces the response decoder.

describe_error

</>

pub fn describe_error(error: Error) -> String

Describes an error for logs.

files

</>

pub fn files(call: Call(m, a)) -> List(#(String, FileUpload))

The file arguments a call will send.

gov_slack_api_url

</>

pub const gov_slack_api_url: String

The Web API base url for GovSlack workspaces.

map

</>

pub fn map(
  call: Call(m, a),
  with transform: fn(a) -> b,
) -> Call(m, b)

Transforms the decoded response.

method

</>

pub fn method(call: Call(m, a)) -> String

The Web API method a call will invoke, such as "chat.postMessage".

new

</>

pub fn new(token: String) -> Client

A client that authenticates with a bot (xoxb-), user (xoxp-) or app-level (xapp-) token.

next_page

</>

pub fn next_page(
  call: Call(m, a),
  metadata: option.Option(ResponseMetadata),
) -> option.Option(Call(m, a))

The call for the next page, or None after the last page. Pass the response_metadata from the response to call. The next call is the same call with cursor set to next_cursor.

params

</>

pub fn params(call: Call(m, a)) -> List(#(String, String))

The form-encoded arguments a call will send.

raw

</>

pub fn raw(
  method: String,
  params: List(#(String, String)),
) -> Call(Raw, value.Value)

Calls any Web API method, returning its whole response as json.

request

</>

pub fn request(
  call: Call(m, a),
  client: Client,
) -> request.Request(BitArray)

The HTTP request for a call. Calls without files are a urlencoded form; calls with files are multipart/form-data.

response

</>

pub fn response(
  call: Call(m, a),
  response: response.Response(String),
) -> Result(a, Error)

Decodes the HTTP response for a call.

response_metadata_decoder

</>

pub fn response_metadata_decoder() -> decode.Decoder(
  ResponseMetadata,
)

Decodes ResponseMetadata from json.

response_metadata_to_json

</>

pub fn response_metadata_to_json(
  metadata: ResponseMetadata,
) -> json.Json

Encodes ResponseMetadata as json.

slack_api_url

</>

pub const slack_api_url: String

The default Web API base url.

upload_request

</>

pub fn upload_request(
  upload_url: String,
  contents: BitArray,
) -> Result(request.Request(BitArray), Nil)

The request for step two of Slack’s file upload flow. It posts the raw bytes to the upload_url from files.getUploadURLExternal. Step three is files.completeUploadExternal. See https://docs.slack.dev/messaging/working-with-files.

upload_response

</>

pub fn upload_response(
  response: response.Response(String),
) -> Result(Nil, Error)

Checks the response to an upload_request. Slack answers 200 and a short text body such as OK - 12.

webhook_request

</>

pub fn webhook_request(
  url: String,
  body: json.Json,
) -> Result(request.Request(String), Nil)

The request that posts a message to an incoming webhook or to a response_url from a slash command or interaction. Build the body with interaction.response_message_to_json, or send any json to an incoming webhook. See https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks.

webhook_response

</>

pub fn webhook_response(
  response: response.Response(String),
) -> Result(Nil, Error)

Checks the response to a webhook_request. On success, webhooks answer 200 and the text ok. On failure, they answer with a status code and an error code such as invalid_payload as plain text.

with_base_url

</>

pub fn with_base_url(
  client: Client,
  url: String,
) -> Result(Client, Nil)

Points a client at a different Web API base url, such as gov_slack_api_url or a local mock server.

with_file

</>

pub fn with_file(
  call: Call(m, a),
  key: String,
  file: FileUpload,
) -> Call(m, a)

Adds or replaces a file argument. A call with files is sent as multipart/form-data instead of a urlencoded form.

with_header

</>

pub fn with_header(
  client: Client,
  name: String,
  value: String,
) -> Client

Adds a header to every request, such as a custom user-agent.

with_param

</>

pub fn with_param(
  call: Call(m, a),
  key: String,
  value: String,
) -> Call(m, a)

Adds or replaces an argument, such as one the docs do not list yet or team_id on an org-wide app.

with_token

</>

pub fn with_token(client: Client, token: String) -> Client

Swaps the token a client sends.

Constructors

Constructors

Arguments

Constructors

Arguments