DEV Community: Kazuhiro "Kaz" Sera

OpenAI Agents SDK + Multiple MCP Servers

Kazuhiro "Kaz" Sera — Thu, 27 Mar 2025 18:46:30 +0000

OpenAI Agents SDK (Python) now supports Model Context Protocol (MCP) servers as tools!

// Detect dark theme var iframe = document.getElementById('tweet-1904957755829481737-876'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1904957755829481737&theme=dark" }

The examples in the Agents SDK repository do not yet include one that runs multiple MCP servers at a time, so let's walk through a simple code demonstration of how to do that. In this quick guide, we'll use two MCP servers:

Filesystem MCP Server: allows the agent to interact with your local file system.
Slack MCP Server: enables the agent to interact with your Slack workspace.

Python and Node

First, ensure you have the required dependencies:

pip install -U openai-agents
npm install -g npx

Slack App

Also, if you try the Slack MCP server out, you need to create a Slack app (=Slack integration) and pass its bot token and installed workspace's team ID.

Step 1: Head to https://api.slack.com/apps, click "Create New App", select "From a manifest", select your workspace, switch to YAML, and then past the following YAML data (you can change the app name if you want):

display_information:
  name: Test MCP Connector
features:
  bot_user:
    display_name: Test MCP Connector
oauth_config:
  scopes:
    bot:
      - channels:history
      - channels:read
      - chat:write
      - reactions:write
      - users:read

Step 2: Go to Settings > Install App; click the "Install to (workspace name)" button to enable the app in your Slack workspace and then set the following two variables on the terminal to run your agent app:

# Settings > Install App > Bot User OAuth Token
export SLACK_BOT_TOKEN=xoxb-....

# You can find this by running the following API call:
# curl -s -XPOST https://slack.com/api/auth.test -H"Authorization: Bearer ${SLACK_BOT_TOKEN}" | jq .team_id
export SLACK_TEAM_ID=T....

Step 3: Invite "Test MCP Connector" to the channels you want to read/write via MCP

Now, you're ready for your first agentic workflow with multiple MCP servers!

Python Demo Script

Here is a complete Python code to run. You can create a Python script named app.py and then run python app.py. Please note that pip install -U openai-agents and npm install -g npx should be done beforehand.

#
# Demo: OpenAI Agents SDK + MCP Servers
#
# How to run this app:
# $ pip install -U openai-agents
# $ python app.py
#
# See also:
#  - https://openai.github.io/openai-agents-python/mcp/
#  - https://github.com/openai/openai-agents-python/tree/main/examples/mcp
#  - https://github.com/modelcontextprotocol/servers/tree/main/src/

import asyncio

import os
import shutil
import logging

from agents import Agent, Runner, gen_trace_id, trace
from agents.mcp import MCPServerStdio


logging.basicConfig(level=logging.WARNING)

# If you want to see more logs, enable the following lines:
# logging.basicConfig(level=logging.INFO)
# logging.getLogger("openai.agents").setLevel(logging.DEBUG)


async def main():

    # ----------------------------------------------------
    # Filesystem MCP Server
    # ----------------------------------------------------
    # How to enable this server:
    # Step 1: Set the directory you wish to allow access
    path_to_allow_access = os.path.dirname(os.path.abspath(__file__))
    fs_command = f"npx -y @modelcontextprotocol/server-filesystem {path_to_allow_access}"
    fs_server = MCPServerStdio(
        name="FS MCP Server",
        params={"command": fs_command.split(" ")[0], "args": fs_command.split(" ")[1:]},
    )

    # ----------------------------------------------------
    # Slack MCP Server
    # ----------------------------------------------------
    # How to enable this server:
    # Step 1: Head to https://api.slack.com/apps and then create a new app using the following YAML:
    """
display_information:
  name: Test MCP Connector
features:
  bot_user:
    display_name: Test MCP Connector
oauth_config:
  scopes:
    bot:
      - channels:history
      - channels:read
      - chat:write
      - reactions:write
      - users:read
    """
    # Step 2: Install the app into your Slack workspace and then set the following two variables:
    # export SLACK_BOT_TOKEN=xoxb-....
    # export SLACK_TEAM_ID=T....
    # Step 3: Invite "Test MCP Connector" to the channels you want to read/write via MCP
    slack_command = "npx -y @modelcontextprotocol/server-slack"
    slack_server = MCPServerStdio(
        name="Slack MCP Server",
        params={
            "command": slack_command.split(" ")[0],
            "args": slack_command.split(" ")[1:],
            "env": {
                "SLACK_BOT_TOKEN": os.environ["SLACK_BOT_TOKEN"],
                "SLACK_TEAM_ID": os.environ["SLACK_TEAM_ID"],
            },
        },
    )

    # ----------------------------------------------------
    # Run the agentic workflow with these two MCP servers
    # ----------------------------------------------------
    async with fs_server as fs, slack_server as slack:
        trace_id = gen_trace_id()
        print(f"View trace: https://platform.openai.com/traces/{trace_id}\n")

        with trace(workflow_name="Multi-MCP Server Demo Workflow", trace_id=trace_id):
            agent = Agent(
                name="OpenAI Agent w/ MCP Servers",
                instructions="Use the tools to access the filesystem and slack workspaces.",
                mcp_servers=[fs, slack],
            )
            prompt = input("Enter a prompt (MCP servers (fs, slack) are available): ")
            result = await Runner.run(starting_agent=agent, input=prompt)
            print(result.final_output)


if __name__ == "__main__":
    if not shutil.which("npx"):
        error = "npx is not installed. Please install it with `npm install -g npx`."
        raise RuntimeError(error)

    asyncio.run(main())

If everything works fine, you will see the output like below. I tested with "Can you help me find where app.py is, and also let me know the summary of the last 10 hours in #cat-lovers (C06CS8GRPC2)?" . You can use either of the two MCP servers for a prompt or both.

$ python app.py

Secure MCP Filesystem Server running on stdio
Allowed directories: [ '/Users/seratch/tmp/mcp-sample' ]
Starting Slack MCP Server...
Connecting server to transport...
Slack MCP Server running on stdio
View trace: https://platform.openai.com/traces/trace_*****************

Enter a prompt (MCP servers (fs, slack) are available): Can you help me find where app.py is, and also let me know the summary of the last 10 hours in #cat-lovers (C06CS8GRPC2)?

Received ListToolsRequest

Received CallToolRequest: {
  method: 'tools/call',
  params: {
    name: 'slack_get_channel_history',
    arguments: { channel_id: 'C06CS8GRPC2', limit: 100 }
  }
}

The `app.py` file is located at:

- `/Users/seratch/tmp/app.py`

### Summary from #cat-lovers in the last 10 hours:

1. **User <@U08KR020GLA> joined the channel.**

2. **User <@U03E94MK0> shared:**
   - Tried doing yoga, but the cat assumed it was “attack the moving limbs” hour 🧘‍♂️🧶
   - Mentioned their cat zooming around the house like she’s late for a nap 🐈💨
   - Reminded everyone that every keyboard serves as a cat bed, intended or not 🐾🧶⌨️

Feel free to ask if you need more information or any further assistance!

If you're curious, the reason I included the channel ID is that when there are many channels in a workspace, the default MCP server seems unable to identify a channel without an ID. If you implement your own MCP server that uses API response pagination, it should be able to find a channel just by its name, although it may take longer.

Tracing feature is enabled by default when you use Agents SDK! So, you will be able to check detailed tracing of the workflow execution like below:

Wrap up

I hope this post was helpful to you. Using MCP servers can enable your agentic workflows to have more capabilities without implementing a lot on your own. Enjoy coding your agents to interact with MCP servers!

Additional Notes on Responses API and Agents SDK

Kazuhiro "Kaz" Sera — Fri, 14 Mar 2025 06:10:20 +0000

Hello! I'm Kaz (@seratch), and I recently joined the Developer Experience team at OpenAI. Previously at Slack, I worked on official SDKs and Developer Relations. At OpenAI, I'll continue to support developers in various ways—looking forward to collaborating with you!

OpenAI announced a new set of APIs and the Agents SDK designed for building agentic applications this week:

I wanted to share a collection of useful links to know more about the new tools.

Responses API

Combines the simplicity of Chat Completions with the tool support of Assistants (beta)
Manages conversation state for you
Supports referencing PDFs, in addition to image files
Works with all currently available and upcoming built-in tools
Includes access to the request log dashboard by default
A full superset of Chat Completions—use Responses for new projects
- Chat Completions will remain supported, including with compatible models
- Assistants (beta) is scheduled to sunset in mid-2026 (migration guides to come)
Try it in the Playground or with the Next.js sample app

Built-in Tools

Web search
- Available as a tool in Responses (gpt-4o / gpt-4o-mini only)
- Available as a model only in Chat Completions
- Pricing here
File search (Vector Store)
- Graduated from Assistants (beta) with new features like metadata filtering
- Upload via Files API and add to a Vector Store
- Pricing here
Computer use
- Powered by the Computer-Using Agent (CUA) model (used in Operator)
- Initially available to developers in Tiers 3–5
- Sample apps using Playwright, Docker, Browserbase, and Scrapybara
- For non-browser use cases, human oversight is recommended
- Pricing here
Planned: Code Interpreter
You can also use Function Calling alongside built-in tools

Agents SDK

Built from lessons learned with the experimental Swarm SDK
Orchestrate everything from simple agents to multi-agent systems
Supports handoffs, guardrails, and tool execution
Includes a new tracing UI
Internally uses Responses API, but you can also integrate external Chat Completions-compatible services
Available in Python now; Node.js support is planned

Observability Tools

Track and visualize agent workflows
Tracing UI available by default when using the Agents SDK
Request log dashboard available for direct API usage
Add custom spans in code with tracing APIs
Supports integration with external tools

As a reminder, the official blog post is a comprehensive reference, so definitely check that out too.

Enjoy trying the latest tools and looking forward to seeing what you build!

Building Slack Platform Expert AI

Kazuhiro "Kaz" Sera — Thu, 13 Feb 2025 04:50:53 +0000

For almost 6 years, I’ve helped Slack app developers build their Slack apps, and I’ve loved answering their technical questions day in and day out.

But with a new chapter on the horizon —and the inevitable departure from my current role— I wanted to create something that could keep the conversation going.

That’s why I built an AI service that answers Slack platform specific questions on my behalf. You can try it out at what-would-kaz-say.fly.dev.

If you are a current or former member of the technical staff at Slack, you might know why I named it this way. I hope Cal will like it, but ... what would he say?

This project is a RAG (Retrieval-Augmented Generation)-based AI service that combines generative AI with document and Q&A data retrieval related to the Slack platform to ensure answers are both accurate and context-aware. It was my first in-depth exploration into building RAG with a substantial dataset, and the journey has been full of learning and joy.

In this article, I will share the details of what I've built and how it works.

Key System Components

Here is the list of the key components of the system:

Streamlit powers the web interface, giving the app a dynamic, user-friendly feel.
Chroma is used for semantic search.
SQLite3 with BM25 ranking algorithm handles keyword queries.
OpenAI API (chat.completions, moderations) drives the generation of responses.
GitHub API provides publicly available quality content for Q&A.
Docker ensures a consistent environment for the app.
Fly.io manages deployment and scale adjustments.
Langfuse monitors and analyzes the LLM performance.
Sentry monitors and logs errors for continuous improvement.

Every component has been chosen to balance quality, performance, cost efficiency, and ease of development.

I initially considered using cloud services for the datastore, but I found that it could cost more than expected for this hobby project, and I didn't need many functionalities this time. Additionally, I wanted to quickly build something that just works while learning the fundamental aspects of RAG engineering with the simplest tools. For these reasons, I decided to build it this way.

Now, let me walk you through the key features.

Keeping the AI Grounded

To reduce the chance of hallucinations as much as possible, the system prompt explicitly instructs the AI to base its answers solely on retrieved documents and the session’s past messages. For example, the system prompt includes:

Your answer must consider only the # Context section data and the past messages in the same session. Please be particularly precise when discussing code related to SDKs. You must not respond with any speculations like suggesting any classes and methods that are not mentioned in the # Context section.

Then, the user’s question is formatted like this:

user_message =f"""
# Question
{unified_question} You must answer this question in {detected_language}

# Context
This prompt provides {num_of_context_documents} documents as context for this question:

{context}
"""

You should be interested in unified_question, detected_language, and context in the code above. They are:

unified_question: I will explain this in detail in the next section, but it is a single unified question that considers previous questions in the same session.
detected_language: As a non-native English speaker, I wanted to support any language for asking questions; one of the preprocessing steps detects the language and translates the question into English for better search results.
context: A large text dataset that includes all the documents and Q&As found in the hybrid retriever's search (also, num_of_context_documents is the number of documents in this context).

This has worked well for many basic questions, but I found that the system still lacks some commonsense knowledge about Slack platform, such as what a team_id is (it's an ID for a workspace). So, I’ve enhanced the system prompt to include this kind of universal Slack knowledge to help the AI more easily and consistently align with the fundamental concepts of the Slack platform.

Hybrid Retriever Architecture

To retrieve the most relevant documents for each question, I implemented two search layers and combined them with my own ranking logic:

Chroma handles semantic search.
SQLite3 (using BM25 ranking algorithm) manages traditional keyword searches.

As mentioned earlier, I recognize there might be even better solutions out there, but I went with these two simple solutions to quickly create something functional and to learn with the most straightforward solutions first.

The entire process of building the search index involves these steps:

Fetch publicly available documents, Q&A, code examples, and unit tests from GitHub.
Optimize some of the data and store everything in a single JSON data file (source_data.json).
Insert all the data into Chroma and SQLite3 as part of the Docker image.

I will elaborate on steps 1 and 2 in the next section. In this part, I will focus on the process of building the Docker image.

Building Search Index within Docker Image

Both search systems run locally within the Docker container, ensuring low latency and cost efficiency. The databases are built when the Docker image is created. Here’s the relevant excerpt from the Dockerfile:

# copy the python scripts
COPY *.py /app/
# copy the source JSON data files
COPY source_data.json /app/source_data.json
# run the scripts to set up the databases
RUN python keyword_search.py build
RUN python chroma_search.py build
# delete the JSON file to reduce the image size a little bit
RUN rm source_data.json

As of today, the source data file is approximately 13MB in total, with around 6,000 text entries (the optimization I will mention later reduced this file size by 50%). The keyword search SQLite3 database is 23MB, and Chroma database is 83MB. Considering these relatively small data sizes, this setup works well for both performance and cost.

I chose python:3.12-slim-bookworm as the base image (Python 3.13 fails to function for some of the dependencies, so I chose 3.12 for the time being), and the current image size is about 480MB.

Hybrid Search & Ranking

I started with only Chroma's semantic search, but I soon realized that for certain questions a simple semantic search wasn’t enough.

To resolve the issue, I integrated a BM25-based keyword search through SQLite3. With this enhancement, I observed that the relevance of the retrieved documents significantly improved. The process is as follows:

Use LLM to detect the language of the question (and translate if necessary).
Merge previous questions in the same session (if exists) into the current question using LLM (=making the unified question)
Run semantic search with the unified question in Chroma.
Extract a few sets of keywords from the unified question using LLM.
Run a few SQLite3 BM25-based keyword searches on the extracted keyword sets.
Rank the results by document appearance frequency + weights to determine the final document set.

Although this process requires three OpenAI API calls, using a lean model (gpt-4o-mini) allows the steps to complete fast and cost-effectively. Most of the processing time comes from the final OpenAI call that generates the answer with retrieved documents.

Regarding the SQLite3 database table, you can execute the following DDL:

cursor = conn.cursor()
cursor.execute("CREATE VIRTUAL TABLE IF NOT EXISTS source_content_files USING fts5(id, content, last_updated);")

After that, you can insert rows like this:

cursor.execute(
    "INSERT INTO source_content_files (id, content, last_updated) VALUES (?, ?, ?)",
    (key, content, last_updated)
)

With the above setup, you can now run the following query:

cursor.execute(f"""
SELECT
    content
FROM
    source_content_files
WHERE
    source_content_files MATCH ?
ORDER BY 
    -- lower scores indicate better matches.
    bm25(source_content_files) ASC,
    last_updated DESC
LIMIT
    {limit}
""",
    [condition],
)
return list(map(lambda row: row[0], cursor.fetchall()))

The condition can include a few keywords to match with the "OR" condition.

In an effort to improve the quality of search results and the final output, I explored some additional approaches, such as rule-based document attachments and naive model distillation. Unfortunately, none of these methods were successful. I will continue to explore further ideas.

When reflecting on the result evaluation process, I manually assessed the quality by running several queries. The approach worked for this app due to the small dataset and my familiarity with the topic. However, to ensure rapid and continuous improvement, I'll need to evaluate the quality using a dedicated dataset along with reliable tools like Ragas and ideally automate the process.

Source Document Data Pipeline

I slightly mentioned the optimization of the source data in the previous section. Now, I will share the details.

Let's start by explaining what source data this system collects. The quality and breadth of the documents are critical, so I gathered data from multiple sources:

GitHub: Issues and their comments, SDK documents (markdown), code examples, and unit tests.
My own content: Blog posts (markdown) and library code in TypeScript.
Hand-written notes: Additional documents curated specifically for this app.

A significant effort was spent summarizing lengthy GitHub issues and unit test code. I used OpenAI API to summarize the text data to be even more efficient. For example, one GitHub issue (#1026) was condensed to capture its essence, highlighting key points about modal submissions, API errors, and the proper usage of ack() and client.views_update(). The summary retained important error messages, links to official documentation, and included a useful code snippet as well.

Title:
Issue in modal submission (We had some trouble connecting.Try again ?)

Summary:
The GitHub issue discusses procedural issues with triggering modals in a Slack app using Python's Socket Mode. The process involves three stages:

1. A modal is triggered through a slash command with an input field for a GitHub issue ID.
2. Upon submission, the data is parsed, and if valid, a second modal with multiple input fields is updated.
3. The final submission retrieves values to update the issue body.

During the interaction, the following error message has been reported:

Failed to run listener function (error: The request to the Slack API failed. (url: https://www.slack.com/api/views.update)
The server responded with: {'ok': False, 'error': 'not_found'})

Key points raised include:

- There were issues with using `ack()` and `client.views_update()` calls simultaneously. The recommendation is to utilize `ack(response_action="update", view= updated_view)` to handle modal updates properly, as `ack()` will close the current modal.
- Using `ack(response_action="update")` should allow for updating the view without closing it unexpectedly, provided the view structure includes all necessary properties (like the title).
- The Slack API does not permit reopening a modal with `views.open` if one is already open; instead, modals should be updated using `views.update`.
- Proper usage of the `view_id` in the `views.update` API call was emphasized.

A code example that aligns with the discussion was provided for better clarity, ensuring proper modal manipulation using `ack()` and enhancing user experience by preventing premature closure of modals. The example demonstrates an effective approach to update modals asynchronously and correctly. The discussion concludes by suggesting that unresolved issues can be addressed in new issue threads, and the current one may be closed for inactivity.

For more information, refer to the following documentation:
- [Updating View Modals](https://api.slack.com/surfaces/modals#updating_views)
- [Slack API Error Handling](https://api.slack.com/developer-tools)

Here's a snippet reflecting the corrected modal management:

@app.view("submit_ticket")
def handle_ticket_submission(ack, body, client):
    errors = {}
    if len(errors) > 0:
        ack(response_action="errors", errors=errors)
    else:
        ack(response_action="update", view=updated_view)

This ensures that user interactions proceed without unnecessary closures or errors.

For generating this output from lengthy GitHub issue discussion text, I used the following prompt:

You'll be responsible for summarizing a GitHub issue, ensuring all crucial details from the discussion are preserved. You may exclude irrelevant parts such as template phrases. While there's no need to drastically shorten the text, you should refine it to remain clear and helpful for Slack app developers.

Maintain any working code examples in the summary. Include any mentioned error messages or codes. If there are valuable links to official documentation, those should also be part of the summary.

Provide only the summary in your response.

In another instance, I used OpenAI to convert unit test code into a practical example script, which is ready to use without any testing framework requirements. This approach was primarily utilized to enhance data quality, making it much more accessible for both retrievers and generative AI.

Here is an example. The AuthorizeUrlGenerator unit tests were converted into the following code snippet with sufficient comments. These comments are very useful for both document search quality and helping generative AI understand the code better.

# This script demonstrates how to use the AuthorizeUrlGenerator and OpenIDConnectAuthorizeUrlGenerator
# classes from the Slack SDK to generate various OAuth authorization URLs.

from slack_sdk.oauth import AuthorizeUrlGenerator, OpenIDConnectAuthorizeUrlGenerator

# Using AuthorizeUrlGenerator to create OAuth URLs
def generate_authorize_urls():
    # Initialize the AuthorizeUrlGenerator with necessary parameters
    generator = AuthorizeUrlGenerator(
        client_id="111.222",              # The client ID for your Slack app
        scopes=["chat:write", "commands"], # The permissions your app is requesting
        user_scopes=["search:read"],       # The user-level permissions your app is requesting
    )

    # Generate the default OAuth URL
    url_default = generator.generate("state-value")
    print("Default URL:", url_default)
    # Expected URL:
    # https://slack.com/oauth/v2/authorize?state=state-value&client_id=111.222&scope=chat:write,commands&user_scope=search:read

    # Generate the OAuth URL with a custom authorization URL
    generator_with_base_url = AuthorizeUrlGenerator(
        client_id="111.222",
        scopes=["chat:write", "commands"],
        user_scopes=["search:read"],
        authorization_url="https://www.example.com/authorize" # Custom base URL
    )
    url_base = generator_with_base_url.generate("state-value")
    print("Base URL:", url_base)
    # Expected URL:
    # https://www.example.com/authorize?state=state-value&client_id=111.222&scope=chat:write,commands&user_scope=search:read

    # Generate the OAuth URL including team information
    url_team = generator.generate(state="state-value", team="T12345")
    print("Team URL:", url_team)
    # Expected URL:
    # https://slack.com/oauth/v2/authorize?state=state-value&client_id=111.222&scope=chat:write,commands&user_scope=search:read&team=T12345

# Using OpenIDConnectAuthorizeUrlGenerator to create OpenID Connect URLs
def generate_openid_urls():
    # Initialize the OpenIDConnectAuthorizeUrlGenerator
    oidc_generator = OpenIDConnectAuthorizeUrlGenerator(
        client_id="111.222",
        redirect_uri="https://www.example.com/oidc/callback", # Where to redirect after authorization
        scopes=["openid"],                                  # OpenID scope
    )

    # Generate the OpenID Connect authorization URL
    url_oidc = oidc_generator.generate(state="state-value", nonce="nnn", team="T12345")
    print("OpenID Connect URL:", url_oidc)
    # Expected URL:
    # https://slack.com/openid/connect/authorize?response_type=code&state=state-value&client_id=111.222&scope=openid&redirect_uri=https://www.example.com/oidc/callback&team=T12345&nonce=nnn

# Execute the functions to generate and print the URLs
generate_authorize_urls()
generate_openid_urls()

For generating this output, I came up with the following system prompt:

You are tasked with generating useful code examples from either unit test code or example code found in Slack's official SDK repositories.

If the provided text is unit test code for an SDK, you will create a single script that executes a set of operations tested by the unit test. This involves extracting the method executions/invocations of the test target, along with their required initialization processes, such as class instantiation or setting necessary variables. You should include detailed comments on what each part of the code accomplishes in the output script. Converting the assertions in the test code isn't needed, but if the details of a returned value are informative, you should include them as comments in the code as well.

Provide only the generated script code in your response.

The entire process of fetching public data and optimizing the text is idempotent, so I plan to run it periodically to keep the source data up to date.

Streamlit UI Optimization

When I started working on this project, it was a tiny CLI tool for my own use.

The code was something like this (off topic, but if you're looking for a great solution for daily use, take a look at ShellGPT):

# pip install openai rich prompt_toolkit
# export OPENAI_API_KEY=sk-....
# python cli.py

import os
import logging
import traceback

# OpenAI API client
from openai import OpenAI, Stream
from openai.types.chat import ChatCompletionChunk
from main_prompt_builder import build_new_messages
from configuration import load_openai_api_key, load_openai_model

# To render markdown text data nicely
from rich.console import Console
from rich.markdown import Markdown
from rich.live import Live

# To store command history
from prompt_toolkit import PromptSession
from prompt_toolkit.history import FileHistory

prompt_session_history_filepath = os.path.expanduser("~/.my-openai-cli")
prompt_session = PromptSession(history=FileHistory(prompt_session_history_filepath))

# Initialize OpenAI client and model
openai_client = OpenAI(api_key=load_openai_api_key())
openai_model = load_openai_model()

# stdout
console = Console()

def p(output):
    console.print(output, end="")

def main():
    p(f"\nConnected to OpenAI (model: {openai_model})\n\n")
    messages = build_new_messages()
    while True:
        prompt: str = ""
        try:
            prompt = prompt_session.prompt("> ")
        except (EOFError, KeyboardInterrupt):  # ctrl+D, ctrl+C
            p("\n")
            exit(0)

        if not prompt.strip():
            continue

        try:
            prepare_messages_with_latest_prompt_content(openai_client, messages, prompt)

            p("\n")
            stream: Stream[ChatCompletionChunk] = openai_client.chat.completions.create(
                model=openai_model,
                messages=messages,
                temperature=0.1,
                stream=True,
            )
            reply: str = ""
            with Live(refresh_per_second=6) as live:
                for chunk in stream:
                    item = chunk.choices[0].model_dump()
                    if item.get("finish_reason") is not None:
                        break
                    chunk_text = item.get("delta", {}).get("content")
                    if chunk_text:
                        reply += chunk_text
                        live.update(Markdown(reply))

            p("\n")
            messages.pop()  # remove the lengthy user message with retrieved documents
            messages.append({"role": "user", "content": prompt})
            messages.append({"role": "assistant", "content": reply})

        except KeyboardInterrupt:  # ctrl+D
            p("\n")
            continue
        except EOFError:  # ctrl+C
            p("\n")
            exit(0)
        except Exception as e:
            p(f"\n[bold red] Error: {e}[/bold red]\n")
            print(traceback.format_exc())
            continue

if __name__ == "__main__":
    main()

The app then evolved into a web UI, making it accessible to anyone. Streamlit made it easy to focus on the core logic instead of spending too much time on the interface. Here are a few standout enhancements I added:

Dynamic “Kaz is thinking …” Indicator

To tell a user that the system is now working on their question, I initially displayed static text saying "Kaz is thinking..." on the UI until the stream rendering began.

Then, to make the interaction more lively, I replaced the static text with a dynamic indicator. This indicator refreshes every 1.5 seconds while a background thread is working on the OpenAI call, ensuring the user is consistently aware that the system is actively processing the passed query.

The actual code is a bit more complex, but the core logic is illustrated below:

# the area to display the assistant's reply
response_placeholder = st.empty()
# the textarea to enter the user's question
current_question = st.text_area("Enter your question:", key="user_input", height=120)
# the button to send right after the textarea
submit_button = st.button("Send", disabled=st.session_state.button_disabled)

if submit_button and current_question.strip():
    # when the "Send" button is clicked
    st.session_state.button_disabled = True
    st.session_state.now_answering = False

    # run this function in a different thread
    def answer_question():
        try:
            assistant_reply = ""

            # make a deep copy of the messages to avoid displaying
            # the actual long prompt with retrieved documents on the UI
            messages = st.session_state.messages.copy()

            # this internal function updates the messages
            # with retrieved documents retrieved from the retriever system
            # also, streamlines the prompt to consider the older user questions in the same session
            update_messages_with_latest_prompt_content(
                client=client,
                collection=collection,
                messages=messages,
                prompt=current_question,
            )

            # update the UI with the streaming response from OpenAI
            for chunk in stream_openai_response(client, openai_model, messages):
                if st.session_state.now_answering is False:
                    st.session_state.now_answering = True
                assistant_reply += chunk
                response_placeholder.markdown(assistant_reply)

            # append the user's input rather than the actual long prompt with retrieved documents
            st.session_state.messages.append({"role": "user", "content": current_question})
            st.session_state.messages.append({"role": "assistant", "content": assistant_reply})

            # delete the input in the textarea to enable the user to immediately enter a new question
            if "user_input" in st.session_state:
                del st.session_state.user_input
            st.session_state.button_disabled = False
            # All the things for this question are done, so rerun the app to refresh the whole UI
            st.rerun()

        except Exception as e:
            print(traceback.format_exc())
            st.error(f"An error occurred: {e}")

    # start a new thread to call OpenAI's API and reflect the streaming response on the UI
    t = threading.Thread(target=answer_question, daemon=True)

    # note that this is crucial to use these functions before simply starting a thread
    add_script_run_ctx(t, get_script_run_ctx())
    t.start()

    # display lively updated "Kaz is thinking ..." indicator
    count = 2
    while t.is_alive() and st.session_state.now_answering is False and count < 30:
        dots = "." * count
        now_loading = f"**Hold on, Kaz is thinking {dots} 🤔**"
        response_placeholder.markdown(now_loading)
        time.sleep(1.5)
        count += 1

    # If the AI is still thinking for a while, encourage the user to try again
    if count >= 30:
        st.error("It seems Kaz is a bit busy right now ... 😔 Please try again later.")
        st.stop()

    # wait for the thread to finish
    st.session_state.now_answering = False
    t.join()

Note: The call to add_script_run_ctx(t, get_script_run_ctx()) is required before starting the thread; otherwise, your code within the thread will fail to access Streamlit's session and other data.

This seems to be a common need, but I couldn't find direct answers on how to implement it properly. So, I thought sharing this might be helpful to someone else. This is a small customization of the Streamlit UI, but I believe it makes the user experience more pleasant.

Simple Abuse Prevention & Cached Responses

While not foolproof, a simple rate-limiting mechanism may help prevent abuse of the system.

Using a local SQLite3 database to track request frequency, the app can temporarily block users who send too many requests in a short time. Here’s a simplified code snippet of the abuse prevention logic:

# If block_again is true, it means the remaining block duration will be extended.
# The flag can be set to false when a user simply visits the website.
# Contrarily, it is true when a user submits a query that incurs a cost to the system.

def detect_frequent_requests(ip_address: str, block_again: bool = True):
    last_accessed, last_blocked = get_last_accessed(ip_address)
    if is_this_user_blocked(last_accessed, last_blocked):
        if block_again is True:
            save_as_blocked(ip_address)
        st.error("👋 Thanks for asking questions! but I'm unable to answer many questions at once. Please try again later.")
        st.stop()

When scaling the service out, this local SQLite3 database within a container doesn't work well for this purpose. So, if this service receives far more traffic than I expect, I'll consider switching to a more robust solution. But for now, it should be better than nothing.

In connection with this, for cost efficiency on the system side, I've added a simple cache layer. The suggested prompts you'll see when visiting the website have cached responses, so the system mimics the stream rendering (Sorry about that! but it's an actual response from the system I've captured in advance). This approach helps reduce system load and minimizes unnecessary costs associated with AI retrieval and the CPU time consumption on fly.io, especially for results that are mostly repetitive.

Sign in with Google

Although the authentication isn't fully utilized yet, the idea is to allow only logged-in users to perform resource-intensive generation tasks, which helps manage costs and prevent system abuse.

Here is the code to check if a user is logged in and to display the login/logout link on the right side of the header. The is_logged_in() function is also used when handling the frequency of the user's requests.

# added the following dependencies to the requirements.txt
# streamlit==1.42.0
# Authlib==1.4.1

def is_logged_in() -> bool:
    return st.experimental_user and st.experimental_user.is_logged_in

def logged_in_user_name() -> Optional[str]:
    if st.experimental_user and "name" in st.experimental_user:
        return st.experimental_user.name
    return None

# place the login/logout link on the right side of the header
col_left, col_right = st.columns([6, 1])
col_left.header("🤔 What would Kaz say❓")
if is_logged_in():
    # pass "tertiary" type to make it look like a link
    if col_right.button("Log Out", type="tertiary"):
        st.logout()
else:
    if col_right.button("Log In", type="tertiary"):
        st.login()

The current implementation supports only Google accounts, but you can easily add more authentication providers: https://docs.streamlit.io/develop/concepts/connections/authentication

Moving Forward

Considering I spent just a few days on development, I'm quite happy with what the system can do—but I'm well aware it's far from perfect. Here are some improvements I'm planning:

I can't wait to see the results with o3-mini or even newer models once they come to my tier.
I've added all the documents that I could think of, but there may be more documents that could be added to cover broader topics.
The conversion of GitHub issues and unit tests worked well, but there may be more areas to apply similar techniques.
I understand that my search and ranking system can be improved; I will continue exploring other available solutions for even better service quality.
@what-would-kaz-say bot in Slack workspaces should make sense because this is about Slack platform!
Providing APIs or webhooks should be a good idea too; other apps/platforms can leverage this service's outputs.

Building this Slack platform expert AI was a great self-learning opportunity for me. I hope this blog article will be helpful to someone else, and that the webapp will assist future Slack app developers in creating amazing integrations.

Please feel free to comment on this post, and thanks for reading!

Easier TypeScript API Testing with Vitest + MSW

Kazuhiro "Kaz" Sera — Thu, 25 Apr 2024 08:56:48 +0000

Introduction

Recently, I took time to write unit tests to ensure if my Slack Web API client library works as expected.

As someone who has developed web services for a long time, I've often found mocking HTTP requests in test scenarios to be bothersome and less flexible than I would prefer.

The Game Changer

However, I discovered a great combination that transformed my API call testing in TypeScript: Vitest and Mock Service Worker (MSW). Their well-crafted design makes them incredibly easy to use, enhancing the overall testing experience.

How It Works

For those eager to see the actual code, you can find it here: https://github.com/seratch/slack-web-api-client/blob/main/test/retry-handler.test.ts

Here’s a step-by-step guide to setting up a new project and writing effective tests:

Setting Up New Project:

Let's start by creating a new project and install the required dependences:

mkdir my-test-app
cd my-test-app
npm init -y
npm i slack-web-api-client
npm i --save-dev typescript vitest msw

Configuring TypeScript:

Add a basic tsconfig.json for writing in TypeScript (note that you don't need to use exactly the same one):

{
  "compilerOptions": {
    "outDir": "./dist",
    "target": "es2021",
    "noImplicitAny": true,
    "module": "commonjs",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "allowJs": false
  },
  "include": ["src/**/*"]
}

Start Writing Test Code:

Start by setting up Vist and MSW in a new test source file under the ./test directory:

import { setupServer } from "msw/node";
import { HttpResponse, http } from "msw";
import { afterAll, afterEach, beforeAll, describe, test, expect } from "vitest";

const server = setupServer();
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterAll(() => server.close());
afterEach(() => server.resetHandlers());

Just by including these lines of code, you're ready to capture all outgoing HTTP requests via the fetch function and reproduce any scenario you'd like!

Now, let's add our first simple test:

import { SlackAPIClient } from "slack-web-api-client";

describe("Slack API client", async () => {
  test("can perform api.test API call", async () => {
    server.use(
      http.post("https://slack.com/api/api.test", () => {
        return HttpResponse.json({ ok: true });
      }),
    );
    const client = new SlackAPIClient();
    const response = await client.api.test();
    expect(response.ok).true;
  });
});

Run this test using npx vitest and check the output. If you see the following output on your terminal, congratulations! You've successfully run your first test using MSW!

$ npx vitest

 DEV  v1.5.1 /new-app

 ✓ test/sample.test.ts (1)
   ✓ Slack API client (1)
     ✓ can perform api.test API call

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  17:18:37
   Duration  653ms (transform 87ms, setup 0ms, collect 256ms, tests 39ms, environment 0ms, prepare 101ms)

 PASS  Waiting for file changes...
       press h to show help, press q to quit

When you modify the server.use(...) section as shown below,

    server.use(
      http.post("https://slack.com/api/api.test", () => {
        return HttpResponse.text("ratelimited", { status: 429, headers: { "Retry-After": "1" } });
      }),
    );

the same test should then start to fail:

 ❯ test/sample.test.ts (1) 1048ms
   ❯ Slack API client (1) 1047ms
     × can perform api.test API call 1045ms

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

 FAIL  test/sample.test.ts > Slack API client > can perform api.test API call
SlackAPIConnectionError: Failed to call api.test (cause: SlackAPIConnectionError: Failed to call api.test (status: 429, body: "ratelimited"))
 ❯ SlackAPIClient.call node_modules/slack-web-api-client/src/client/api-client.ts:581:21
 ❯ test/sample.test.ts:24:22
     22|     );
     23|     const client = new SlackAPIClient();
     24|     const response = await client.api.test();
       |                      ^
     25|     expect(response.ok).true;
     26|   });

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
Serialized Error: { apiName: 'api.test', status: -1, body: '', headers: undefined }
Caused by: SlackAPIConnectionError: Failed to call api.test (status: 429, body: "ratelimited")
 ❯ SlackAPIClient.call node_modules/slack-web-api-client/src/client/api-client.ts:602:13
 ❯ SlackAPIClient.call node_modules/slack-web-api-client/src/client/api-client.ts:577:18
 ❯ test/sample.test.ts:24:22

However, this library attempts a retry when it receives a rate-limited error response from Slack. Therefore, after adjusting the scenario to be more realistic,

    const responses = [
      HttpResponse.text("ratelimited", { status: 429, headers: { "Retry-After": "1" } }),
      HttpResponse.json({ ok: true }),
    ];
    server.use(
      http.post("https://slack.com/api/api.test", () => {
        return responses.shift();
      }),
    );

or using one-time handlers works well too:

    server.use(
      http.post("https://slack.com/api/api.test", () => HttpResponse.text("ratelimited", { status: 429, headers: { "Retry-After": "1" } }), { once: true }),
      http.post("https://slack.com/api/api.test", () => HttpResponse.json({ ok: true })),
    );

the test will start passing again!

 RERUN  test/sample.test.ts x3

 ✓ test/sample.test.ts (1) 1044ms
   ✓ Slack API client (1) 1042ms
     ✓ can perform api.test API call 1041ms

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  17:28:21
   Duration  1.21s

 PASS  Waiting for file changes...

The interaction here is very smooth. Every time you save a change to the test code, the test is immediately executed again. Additionally, the outputs from the Vitest framework are so easy to understand that you won't be confused about what to do next.

Wrap Up

For me, using Vitest and MSW has significantly changed the testing experience for SDK development. I highly recommend trying these tools!

Further Tips on Slack's files.upload Deprecation

Kazuhiro "Kaz" Sera — Fri, 19 Apr 2024 06:12:46 +0000

As you might already know, the deprecation of Slack's files.upload API and its migration guide to a newer method were announced recently:

https://api.slack.com/changelog/2024-04-a-better-way-to-upload-files-is-here-to-stay

In this article, I'll share some additional tips that you may find useful about the announcement.

So, what exactly sets this new way apart from the prior method? The biggest difference is that, even when your code receives a response from files.completeUploadExternal API endpoint, processing such as security scan is still asynchronously ongoing on the Slack server side. As a result, sharing the uploaded files in a channel could take some time. This behavior change is a compromise intended to resolve the performance issue that the former files.upload API had, particularly with larger files.

This might necessitate some changes to your custom code, especially if you have subsequent operations that rely on a channel message sharing the uploaded files.

If you have such subsequent processing triggered by file share completion, there are two potential approaches:

Regularly poll the files.info API and delay until the file metadata is updated
Respond to the Event API's file_shared event delivery with a different event listener code

Lastly, the v2 method of the official SDKs should function almost seamlessly by just switching the method to call. However, there are still a few differences to keep in mind:

It is now possible to upload several files in one message (yeah, great enhancement!)
The parameter to set the channel to share the files has been changed from channels to channel_id, and you can no longer specify multiple channels or specify a channel by name
As mentioned above, since the new upload process is asynchronous, when having any subsequent processing that needs to occur synchronously, polling the files.info API or utilizing Events API would be required

That's it! I hope you find this article helpful 👋

Slack Automation: No More Hardcoding channel_ids for Event Triggers!

Kazuhiro "Kaz" Sera — Wed, 17 Apr 2024 04:40:51 +0000

We're excited to share a significant improvement to event triggers on Slack's automation platform has been deployed!

What's the Slack Automation Platform?

For those who may be asking, "What's the Slack Automation Platform?" please start here:

The official documents: https://api.slack.com/automation
Tutorials I wrote: https://dev.to/seratch/series/21161

Among the numerous ways to invoke workflows on this platform, one is known as "Event Triggers." This article elaborates on the most recent updates to these triggers.

Types of Event Triggers

There are two types of event triggers available:

(A) Events that occur within an existing channel
(B) Events not tied to a specific existing channel

For (A), examples include events like message_posted, which is triggered by a new message posting, and reaction_added, which occurs when a reaction is added to a message.

For (B), examples include user_joined_team, which is triggered when a new member joins the workspace, and channel_created, which occurs when a new channel is created.

For a tutorial on setting up the simplest event triggers, I would recommend reading the following article, particularly if you're new to this concept:

https://dev.to/seratch/slack-next-gen-platform-reactionadded-event-trigger-54i

What Has Changed?

For (A), it used to be required to hard-code an array of channel IDs where the workflow will be enabled within the trigger's definition, as demonstrated below:

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
export const workflow = DefineWorkflow({
  callback_id: "example-workflow",
  ...
});

import { Trigger } from "deno-slack-api/types.ts";

const trigger: Trigger<typeof workflow.definition> = {
  type: "event",
  name: "A sample trigger",
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  event: {
    event_type: "slack#/events/reaction_added",
    channel_ids: ["C12345", "C23456"], // This was mandatory!
    filter: { version: 1, root: { statement: "{{data.reaction}} == eyes" } },
  },
  inputs: {
    channel_id: { value: "{{data.channel_id}}" },
    user_id: { value: "{{data.user_id}}" },
    message_ts: { value: "{{data.message_ts}}" },
  },
};
export default trigger;

The part to highlight here is:

    channel_ids: ["C12345", "C23456"], // This was mandatory!

This requirement has been posing challenges for users seeking to enable workflows in various channels. To update the list of channels, a developer had to delete the existing trigger by slack trigger delete first, then edit event.channel_ids within the code and create the trigger again with slack trigger create. Alternatively, a fresh trigger definition could be created and added using slack trigger create.

As a workaround to this issue, I've invented a little creative approach to have a separate workflow for configuring event triggers within the same app. This entails having a primary workflow requiring an event trigger and an associated sub workflow. The sub workflow helps an end-user to easily configure channel_ids through modal dialog interactions, and the sub workflow invites the bot user to those channels.

Here are the links to examples of the implementation:

This approach is widely used not only in the above-mentioned deno-message-translator but also in many sample apps under https://github.com/slack-samples and in custom app codes developed by our customers.

Nonetheless, if it's possible to avoid writing such code, it would indeed be more advantageous...

No Need for `channel_ids` with `all_resources: true`!

With deno-slack-sdk 2.10.0 / deno-slack-api v2.4.0 or newer, event.channel_ids has become unnecessary (of course, it's still available for backward compatibility!). Please make sure to update your import_map.json to these versions or a later one:

{
  "imports": {
    "deno-slack-sdk/": "https://deno.land/x/deno_slack_sdk@2.10.0/",
    "deno-slack-api/": "https://deno.land/x/deno_slack_api@2.4.0/"
  }
}

The newly added option is all_resources: boolean. When you set the flag to true, the channel_ids are no longer needed.

const trigger: Trigger<typeof workflow.definition> = {
  type: "event",
  name: "A sample trigger",
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  event: {
    event_type: "slack#/events/reaction_added",
    all_resources: true, // Just this!
    filter: { version: 1, root: { statement: "{{data.reaction}} == eyes" } },
  },
  inputs: {
    channel_id: { value: "{{data.channel_id}}" },
    user_id: { value: "{{data.user_id}}" },
    message_ts: { value: "{{data.message_ts}}" },
  },
};
export default trigger;

When creating an event trigger using this option, there is no need to maintain the trigger definition afterward. The subsequent step is simply to invite the bot user to the channels where you want this workflow to be triggered.

In the example above, once the bot user is invited to a channel, the workflow will start invoke the workflow whenever a message in the channel receives an :eyes: reaction.

Migrating Existing Workflows

Existing triggers can be deleted using the following steps:

Display a list of configured triggers for the target app with slack trigger list.
Remove unnecessary triggers by executing slack trigger delete --trigger-id (ID starting with Ft).

Next, run slack trigger create --trigger-def (path to source file) to create a new trigger with all_resources: true.

Usually, the bot user should already be invited to the relevant channels. If this isn't the case, please proceed to manually invite the bot as necessary. After this, the triggers should respond to events as intended.

Reminder: Make Sure Your import_map.json Settings Are Correct!

As a reminder, the all_resources option will not work unless the versions of deno-slack-sdk / deno-slack-api specified in import_map.json are as follows or newer:

{
  "imports": {
    "deno-slack-sdk/": "https://deno.land/x/deno_slack_sdk@2.10.0/",
    "deno-slack-api/": "https://deno.land/x/deno_slack_api@2.4.0/"
  }
}

Always update to the latest versions, which can also be done using the slack upgrade command.

Wrap Up

We've finally streamlined a more user-friendly setup process! If you've tried it before and found it challenging, we encourage you to give it another try!

Rapid Bolt app development w/ Slack CLI and sandboxes

Kazuhiro "Kaz" Sera — Mon, 08 Apr 2024 06:44:46 +0000

This blog post guides you on how to rapidly develop a Slack Bolt app using Slack CLI and sandbox organizations/workspaces.

Slack's Developer Program

At TrailblazerDX held in San Francisco on March 6th, new valuable features for Slack app developers were announced:

https://slack.com/blog/developers/developer-program-launch

Utilizing Enterprise Grid sandboxes for local development simplifies your Bolt app development like never before! This article provides a guide on the minimum steps to get started.

What's exciting about this?

Prior to the Developer Program, developing Slack apps required the following steps:

Accessing https://api.slack.com/apps to configure the app
Installing the app being developed into the Slack workspace
Specifying the obtained access token as an environment variable
Finally launching the app

However, with the combination of the newly available Slack CLI and sandboxes by Developer Program, the process has become extremely simple. In fact, all you need to do are creating a sandbox, connecting the CLI to it, and then slack run to start your app.

"... Wait, isn't Slack CLI only usable for the Deno thing?"

Yes, indeed, initially it was provided as a tool exclusively for Deno apps. However, from now on, it will also be available for Bolt app development too!

Now, let's get right to the point.

Create your first sandbox

First, access the developer portal:

https://api.slack.com/developer-program

If you haven't registered yet, create a new account first.

Provisioning a sandbox requires a workspace with a paid plan or registering a credit card, but there is no cost for creating a sandbox or testing the functionality of an app.

However, for executing custom workflow functions, excess usage beyond a certain free quota will be billed based on the number of workflow executions, in the same manner with the production environment. For more details, please refer to this help page.

Once you've set up your account, go ahead and create a sandbox. If everything goes well, you should see a screen similar to the one below.

What's Enterprise Grid?

By the way, you may not be familiar with Enterprise Grid, so let me provide a brief explanation about the "Org" within a sandbox.

In plans other than Enterprise Grid, which most people are familiar with, you can only use one workspace. However, Enterprise Grid has the concept of an "organization" above workspaces, allowing you to create multiple workspaces within an org.

Since the sandbox environment provided by the Developer Program is for Grid, the process involves creating an org first and then creating workspaces. At this point, it'd be enough if you understand this as "that's how it works."

For general information about Enterprise Grid, please refer to the following help page and official guides:

https://slack.com/help/articles/115005481226-Enterprise-Grid-launch-guide

Set up Slack CLI

Once you have provisioned a sandbox, the next step is to install Slack CLI. Please refer to the following page for installation instructions for each platform. You only need to complete the steps before running slack login:

https://api.slack.com/automation/quickstart

After installing the slack command, execute slack login in your terminal. You should see a screen like this:

$ slack login

📋 Run the following slash command in any Slack channel or DM
   This will open a modal with user permissions for you to approve
   Once approved, a challege code will be generated in Slack

/slackauthticket MGIwNTczNzktYWQ5Y***********************************

? Enter challenge code

Copy the part /slackauthticket MGIwN...., and execute it in the message composer in the Slack workspace you created earlier for the sandbox.

A modal dialog like the following will appear:

Press the "Confirm" button, and you will see the "Challenge Code" displayed as follows:

Copy that string and paste it into your terminal to complete the setup.

The result of this integration is saved in a file called $HOME/.slack/credentials.json. If you want to revoke the authentication, you can run slack logout comamnd.

OK, now you're all set!

Create a Python app

Let's start by connecting the simplest Python app to your sandbox org.

Set up Python venv and libraries

You can use Poetry or any other method you prefer, but set up your Python environment and install the necessary dependencies (just two!) as follows:

# Set up Python environment (you can use Poetry or any other tool)
python3 -m venv .venv
source .venv/bin/activate

# Install the necessary dependencies, just these two for now
pip install slack-bolt slack-cli-hooks

Place required files for CLI

For Slack CLI to work with Python, it expects at least the following files:

File name	Description
`slack.json`	Configuration required for CLI to run locally
`manifest.json`	App settings (automatically synchronized with Slack when running `slack run`)
`app.py`	Code to execute the app (file name can be changed)

For slack.json, save the following content as it is:

{
  "hooks": {
    "get-hooks": "python3 -m slack_cli_hooks.hooks.get_hooks"
  }
}

Next is manifest.json, which is a file that you can modify as needed. For this demo, please copy and paste it as is.

{
  "display_information": {
    "name": "Hello",
    "description": "You can update this later",
    "background_color": "#4361ba",
    "long_description": ""
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": false,
      "messages_tab_read_only_enabled": true
    },
    "bot_user": {
      "display_name": "Hello Bot",
      "always_online": true
    },
    "slash_commands": [
      {
        "command": "/hello-sandbox",
        "description": "Say hello to sandbox",
        "usage_hint": "",
        "should_escape": true
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": ["commands"]
    }
  },
  "settings": {
    "interactivity": { "is_enabled": true },
    "org_deploy_enabled": true,
    "socket_mode_enabled": true
  },
  "outgoing_domains": []
}

Finally, place app.py with the following content:

import os
import logging
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

logging.basicConfig(level=logging.DEBUG)

app = App(token=os.environ["SLACK_BOT_TOKEN"])

# Add your code here


if __name__ == "__main__":
    SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start()

Start your app

Now that the preparation is complete, please try launching the app with slack run. If there are no apparent errors, then everything should be fine.

At this stage, the slash command /hello-sandbox should already be available in your workspace. Please try executing it.

While you may encounter an error on the UI, in the terminal, you should see warnings similar to the following. These are suggestions provided by Bolt for Python to guide your implementation.

WARNING:slack_bolt.App:Unhandled request ({'type': None, 'command': '/hello-sandbox'})
---
[Suggestion] You can handle this type of event with the following listener function:

@app.command("/hello-sandbox")
def handle_some_command(ack, body, logger):
    ack()
    logger.info(body)

Let's add code to pass "Hello!" to ack() method call. Please add this before the line if __name__ == "__main__":.

@app.command("/hello-sandbox")
def handle_some_command(ack, body, logger):
    ack("Hello!")
    logger.info(body)

At the time of posting this article, Python CLI support does not have automatic code reloading. Please relaunch slack run whenever you make changes to the code.

To avoid selecting the workspace every time, you might find it convenient to specify the displayed App ID like slack run -a A06P0E7LY48.

With the updated code, you should not encounter execution errors on the UI, and the bot should respond with 'Hello!' 🎉

Create a Node.js app

Let's do the same thing with Node.js. There's no need to change manifest.json. Modify slack.json as follows:

{
  "hooks": {
    "get-hooks": "npx -q --no-install -p @slack/cli-hooks slack-cli-get-hooks",
    "start": "npm start"
  }
}

Let's add package.json and app.js as well.

npm init -y
npm i @slack/bolt
npm i --save-dev @slack/cli-hooks nodemon

Next, update the "scripts" in package.json as follows. If you want a name other than npm start, please name it in line with slack.json.

  "scripts": {
    "start": "nodemon --watch '*.js' --exec node app.js"
  },

Finally, save app.js with the following content:

const { App, LogLevel } = require('@slack/bolt');

const app = new App({
  socketMode: true,
  token: process.env.SLACK_BOT_TOKEN,
  appToken: process.env.SLACK_APP_TOKEN,
  logLevel: LogLevel.DEBUG,
});

app.command("/hello-sandbox", async ({ ack }) => {
  await ack("Hello!");
});

;(async () => {
  await app.start();
  console.log("⚡️ Bolt app is running!");
})();

Try launching it with slack run. Is it working properly?

In this example, nodemon automatically detects file changes. Thus, you'll be able to smoothly develop without restarting the server each time.

Create a TypeScript + Node.js app

Lastly, let's set up the Node.js app in TypeScript.

First, add a tsconfig.json file. The following is just an example, so feel free to adjust the details according to your preferences.

{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs",
    "lib": ["es2022", "dom"],
    "outDir": "lib",
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

Next, install additional dependencies:

npm i --save-dev typescript ts-node @types/node

Then, update the command in package.json to "start": "nodemon --watch 'src/**/*.ts' --exec \"ts-node\" src/app.ts".

Finally, save src/app.ts with the following content:

import { App, LogLevel } from "@slack/bolt";

const app = new App({
  socketMode: true,
  token: process.env.SLACK_BOT_TOKEN,
  appToken: process.env.SLACK_APP_TOKEN,
  logLevel: LogLevel.DEBUG,
});

app.command("/hello-sandbox", async ({ ack }) => {
  await ack("Hello!");
});

;(async () => {
  await app.start();
  console.log("⚡️ Bolt app is running!");
})();

If configured correctly, it should work similarly. Also, try changing the code and verifying that it gets reflected.

Benefits of using CLI + sandboxes

The real joy of using Slack CLI begins here.

No longer do you need to access https://api.slack.com/apps, make app configuration changes, reinstall, and go through that hassle.

Let's rewrite and save manifest.json with the following content:

{
  "display_information": {
    "name": "Hello",
    "description": "You can update this later",
    "background_color": "#4361ba",
    "long_description": ""
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": false,
      "messages_tab_read_only_enabled": true
    },
    "bot_user": {
      "display_name": "Hello Bot",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": ["commands", "chat:write", "app_mentions:read"]
    }
  },
  "settings": {
    "interactivity": { "is_enabled": true },
    "event_subscriptions": {
      "bot_events": ["app_mention"]
    },
    "org_deploy_enabled": true,
    "socket_mode_enabled": true
  },
  "outgoing_domains": []
}

When you save the file, Slack CLI will automatically reflect these changes in the metadata managed by Slack's servers.

The slash command you were using earlier will disappear from the workspace, and instead, this app will be able to receive events, which can be delivered when a user mentions your app's bot.

Please add the following code to the src/app.ts file that you added earlier. This change should also be automatically reflected by nodemon.

app.event("app_mention", async ({ say }) => {
  await say("Hi!");
});

For testing, invite @Hello Bot (local) to a channel and mention it. If you receive a response saying "Hi!", then it's successful! 🎉

Wrap up

You should now understand how easy it is to get started and develop smoothly.

For production, if you're using Socket Mode, it's a good idea to prepare a Dockerfile for deployment (you won't need nodemon in that case).

For setting up manifest.json, please refer to the following page. Note that if it's in YAML format, it won't be loaded with CLI integration, so be sure to specify it in JSON format.

https://api.slack.com/reference/manifests

You might wonder, "Can I use this with runtimes/languages other than Node.js or Python?" Technically, it's possible, but it might require a bit more effort to get it up and running. I hope to cover this in another article someday.

That's all for now!

Slack's remote functions on Cloudflare Workers

Kazuhiro "Kaz" Sera — Sat, 25 Nov 2023 02:25:28 +0000

This article guides you on how to build a remote function for Slack's automation platform on Cloudflare Workers. The slack-cloudflare-workers library provides the toolset for swiftly creating such an app in TypeScript.

Clone the example project

git clone git@github.com:seratch/slack-remote-functions-on-cloudflare.git
cd slack-remote-functions-on-cloudflare/

Create a new remote-funtion app

As of November 2023, you need to utilize either Slack CLI commands or apps.manifest.create API when initiating the development of a new Slack app that provides remote functions. This guide shows how to perform the API call without installing Slack CLI.

Create Cloudflare Tunnel for local development

In this guide, you will first confirm whether the app functions as anticipated on your local machine, before deploying the app on Cloudflare Workers. To accomplish this smoothly, you'll need to amend the app's manifest data to utilize the public URLs of the local app.

Start by initiating a new tunnel for local development. You can do this by executing the following command:

# For other platforms: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel --url http://localhost:3000

Then, you will see the outputs like this:

$ cloudflared tunnel --url http://localhost:3000
2023-11-23T08:33:52Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to experiment and try it out. However, be aware that these account-less Tunnels have no uptime guarantee. If you intend to use Tunnels in production you should use a pre-created named tunnel by following: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
2023-11-23T08:33:52Z INF Requesting new quick Tunnel on trycloudflare.com...
2023-11-23T08:33:53Z INF +--------------------------------------------------------------------------------------------+
2023-11-23T08:33:53Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
2023-11-23T08:33:53Z INF |  https://maps-victim-warm-registration.trycloudflare.com                                   |
2023-11-23T08:33:53Z INF +--------------------------------------------------------------------------------------------+
2023-11-23T08:33:53Z INF Cannot determine default configuration path. No file [config.yml config.yaml] in [~/.cloudflared ~/.cloudflare-warp ~/cloudflare-warp /etc/cloudflared /usr/local/etc/cloudflared]
2023-11-23T08:33:53Z INF Version 2023.8.2
2023-11-23T08:33:53Z INF GOOS: darwin, GOVersion: go1.20.7, GoArch: amd64
2023-11-23T08:33:53Z INF Settings: map[ha-connections:1 protocol:quic url:http://localhost:3000]
2023-11-23T08:33:53Z INF cloudflared will not automatically update when run from the shell. To enable auto-updates, run cloudflared as a service: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/run-tunnel/as-a-service/
2023-11-23T08:33:53Z INF Generated Connector ID: 65df45f4-8ab7-48fd-ad0b-4e52847c5924
2023-11-23T08:33:53Z INF Initial protocol quic
2023-11-23T08:33:53Z INF ICMP proxy will use 192.168.68.112 as source for IPv4
2023-11-23T08:33:53Z INF ICMP proxy will use fe80::10a5:5e5a:9e14:f080 in zone en0 as source for IPv6
2023-11-23T08:33:53Z INF Created ICMP proxy listening on 192.168.68.112:0
2023-11-23T08:33:53Z INF Created ICMP proxy listening on [fe80::10a5:5e5a:9e14:f080%en0]:0
2023-11-23T08:33:53Z INF Starting metrics server on 127.0.0.1:61237/metrics
2023-11-23T08:33:53Z WRN Your version 2023.8.2 is outdated. We recommend upgrading it to 2023.10.0
2023-11-23T08:33:54Z INF Registered tunnel connection connIndex=0 connection=d6531124-06de-4034-9f30-058c7a14e8a7 event=0 ip=198.41.200.23 location=kix04 protocol=quic

In this case, https://maps-victim-warm-registration.trycloudflare.com/ is the public URL receiving requests from Slack. Open src/manifest.ts and replace the two request_url: "https://TODO.trycloudflare.com/" parts in the code with this string.

Perform an apps.manifest.create API call

Alright, the manifest data is now prepared, so let's proceed to make the API call.

Head to https://api.slack.com/reference/manifests#config-tokens and grab your refresh token:

You will use .env file located in the root directory of this project.

echo 'SLACK_TOOLING_REFRESH_TOKEN=xoxe-1-...' > .env

Let's use Bun for quickly running src/manifest.ts. If you're on macOS, the following commands set up the bun command for you:

brew install bun
bun add -d bun-types

Everything is set! Execute the command provided below to create a new Slack app with remote functions:

bun run src/manifest.ts

If everything goes well, you will see a mesage like !!! Visit https://api.slack.com/apps/{app_id} to install the app !!! on the terminal. Click the URL and install the app into your Slack workspace.

Configure secrets

To configure your app, copy the following two secrets:

SLACK_SIGNING_SECRET: Settings > Basic Information > App Credentials > Signing Secret
SLACK_BOT_TOKEN: Settings > Install App > Bot User OAuth Token

To run the app locally, create .dev.vars file with the following content:

SLACK_SIGNING_SECRET=...
SLACK_BOT_TOKEN=xoxb-...
SLACK_LOGGING_LEVEL=DEBUG

Run the app on your local machine

When you hit npm start on the termimnal, you will see the outputs like this:

$ npm start

> my-remote-func@0.0.0 start
> wrangler dev --port 3000

 ⛅️ wrangler 3.17.1
-------------------
Using vars defined in .dev.vars
Your worker has access to the following bindings:
- Vars:
  - SLACK_SIGNING_SECRET: "(hidden)"
  - SLACK_BOT_TOKEN: "(hidden)"
  - SLACK_LOGGING_LEVEL: "(hidden)"
⎔ Starting local server...
[mf:inf] Ready on http://*:3000
[mf:inf] - http://127.0.0.1:3000
[mf:inf] - http://192.168.68.112:3000
[mf:inf] - http://localhost:3000
[mf:inf] - http://[::1]:3000
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                         │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Once your remote function has been installed to your Slack workspace or organization, you can utilize the custom step in the Workflow Builder as follows:

Share the trigger URL for the workflow either in a channel or a canvas document. Clicking the link button initiates the workflow. The execution of your custom step within this workflow triggers a 'function_executed' event in your Cloudflare Workers app.

Deploy the app

Now that the app is working, you can deploy this app onto Cloudflare Workers as a service ready for production. To do so, execute the commands mentioned below. You can go with the secrets that are already available in the dev.vars file.

wrangler deploy
wrangler secret put SLACK_SIGNING_SECRET
wrangler secret put SLACK_BOT_TOKEN

Lastly, head to https://api.slack.com/apps/{app_id} and finalize the two request URLs (Interactivity & Shortcuts, Event Subcriptions) to use the Cloudflware Workers URL like https://slack-remote-functions-on-cloudflare.{your account here}.workers.dev.

Build your own remote function

The examples contained in this repo illustrate the use of buttons and modal views. Yet, if such engagement is not required for your use case, you can simply consolidate all neccessary logic into the app.function(callbackId) listener and remove other app.action/app.view listeners.

Please note, it is necessary to call either functions.completeSuccess or functions.completeError API. This action is required to instruct Slack's workflow to proceed to the subsequent step, or abort the workflow execution respectively. You can refer to src/index.ts for guidance on how to implement these API calls within the code.

Enjoy!

Running Slack App on Cloudflare Workers

Kazuhiro "Kaz" Sera — Wed, 19 Jul 2023 12:16:25 +0000

Recently, as a weekend hobby project, I created a Slack app development framework for Cloudflare Workers and Vercel Edge Functions.

In this article, I will explain the basics of Slack app development and how to use the following libraries:

If you are already familiar with Slack app development and want to try it out right away, it might be faster to read the documentation by following the links from the README.

"Slack App" development basics

Let me explain a little about the basics of "Slack app".

A "Slack app" is a mechanism for adding features such as bots that can converse in a Slack workspace, workflows that respond to events that occur within Slack (e.g., someone joining a channel), slash commands, shortcuts, etc.

There are two ways to communicate between this "Slack app" and Slack's API server:

Request URL: Set up a public endpoint in advance on the app configuration page at https://api.slack.com/apps, receive event data from Slack, and respond with HTTP responses or Web API calls.
Socket Mode: Receive event data from Slack via a WebSocket connection and respond with WebSocket messages or Web API calls.

The latter, Socket Mode, is useful for local development or when it is not possible to expose a public URL. In this article, I will guide you on how to develop a Slack app by setting the URL issued when deployed to Cloudflare Workers as the Request URL.

Digression: New platform feature for Workflow Builder

By the way, since the beginning of this year (2023), a new app development mechanism for extending the Workflow Builder, called the next-generation automation platform, has been added to the Slack platform.

In the Workflow Builder, there is one starting point called a trigger, and small processes called steps are connected in series to form a workflow. The next-generation platform allows you to create your own steps.

While it has become easier to automate within Slack, there are unsupported features while they're available with existing app development. For example, as of 2023, you cannot add slash commands to the entire workspace or set a home tab for users. Also, note that this next-generation platform feature is only available in paid Slack workspaces, and usage charges apply for workflow executions that exceed the free tier. For more details, please read the series of articles I wrote a few months ago: https://dev.to/seratch/series/21161

Wanna go without any libraries?

You might think, "if all I need to do with Cloudflare Workers' fetch function is receiving request data, at most calling Slack's Web API or other services, and returning an HTTP response, why not just implement it without bothering to use a library?"

Of course, you could implement all the things all yourself. However, considering the following points, it's hard to deny that implementing everything yourself every time can be quite a hassle.

Request verification

The Request URL of a Slack app is a URL that is publicly available on the internet, and the source IP address of Slack's requests is not always guaranteed to be the same. Therefore, there is a risk that a malicious third party could mimic the payload sent from Slack and make requests.

As a countermeasure against this, every HTTP request from Slack includes headers called x-slack-signature and x-slack-request-timestamp. It is recommended that the Slack app side verifies the x-slack-signature string using the Signing Secret shared only with Slack, and also checks that the x-slack-request-timestamp is not an old date and time. For more details, please read the official documentation.

To implement this as code that runs on Cloudflare Workers, you first need to read the request body as plain text and then implement the specified verification logic. Here is an example of such an implementation:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Request#text() on Cloudflare Workers prints warning
    const blobRequestBody = await request.blob();
    const rawBody: string = await blobRequestBody.text();
    if (await verifySlackRequest(env.SLACK_SIGNING_SECRET, request.headers, rawBody)) {
      // Valid request pattern
    } else {
      // Invalid signature or timestamp
      return new Response("invalid signature", { status: 401 });
    }
  },
};

async function verifySlackRequest(signingSecret: string, requsetHeaders: Headers, requestBody: string) {
  const timestampHeader = requsetHeaders.get("x-slack-request-timestamp");
  if (!timestampHeader) {
    return false;
  }
  const fiveMinutesAgoSeconds = Math.floor(Date.now() / 1000) - 60 * 5;
  if (Number.parseInt(timestampHeader) < fiveMinutesAgoSeconds) {
    return false;
  }
  const signatureHeader = requsetHeaders.get("x-slack-signature");
  if (!signatureHeader) {
    return false;
  }
  const textEncoder = new TextEncoder();
  return await crypto.subtle.verify(
    "HMAC",
    await crypto.subtle.importKey("raw", textEncoder.encode(signingSecret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]),
    fromHexStringToBytes(signatureHeader.substring(3)), textEncoder.encode(`v0:${timestampHeader}:${requestBody}`)
  );
}

function fromHexStringToBytes(hexString: string) {
  const bytes = new Uint8Array(hexString.length / 2);
  for (let idx = 0; idx < hexString.length; idx += 2) {
    bytes[idx / 2] = parseInt(hexString.substring(idx, idx + 2), 16);
  }
  return bytes.buffer;
}

Various formats of payloads

Due to historical reasons, the format of the request body sent from Slack varies depending on the feature. For the Events API, it's Content-Type: application/json, but for other features, it's application/x-www-form-urlencoded, and the format of the contents differs between slash commands and other features. To accommodate all patterns, you need to implement something like this: https://github.com/seratch/slack-edge/blob/main/src/request/request-parser.ts

Various data patterns

Slack's developer platform supports a wide variety of events. And for each event, there are quite a few edge cases and diverse data patterns when you delve into the details. For example, even channel messages, which are the most basic data, can be just text or can include rich text and interactive components using blocks from Block Kit. When files, emails, etc. are attached, they are also added as attachments.

Also, this is a point for improvement in Slack's developer support, but there is a lack of comprehensive documentation on payloads (So sorry!).

For this reason, using a library like the one I developed this time and receiving support from TypeScript types, this area can be much easier.

Why don't you use Bolt?

Many of you may be aware of Bolt for JavaScript, an npm package that serves as a framework for developing Slack apps. It's an official full-stack Slack app development framework developed by the Slack Developer Relations team (of which I am a member) to free Slack app developers from the hassles I mentioned above.

However, unfortunately, Bolt for JS depends on axios and other Node.js APIs, and cannot be used directly with Cloudflare Workers. Although its name is for JavaScript, it's more of a framework for Node.js.

Also, while Bolt for JS is designed to be extended with an interface called Receiver, this aspect does not mesh well with the specification of processing requests as Cloudflare Workers' fetch function.

This also becomes a constraint when you want to run it as part of a web application using modern frameworks like Next.js or Nest.js. Since I often get questions about this, I explored possible ways on the weekends and eventually created a library to circumvent the constraints of the Receiver. At the moment, there are no plans to transfer this Bolt HTTP Runner into the 1st party SDKs. However, I intend to continue maintaining it as much as I can as an individual, so if you really want to try running it on Next.js or something similar, please use or fork this library.

I digressed a bit. As you can see, it's surprisingly difficult (or was) to properly create a Slack app on Cloudflare Workers. For example, this app that implements integration with ChatGPT is doing all the things I mentioned above on its own.

When I was playing with Cloudflare Workers on the weekend, I thought, "I want to make it easier to create Slack apps," and found the time to create the slack-cloudflare-workers and slack-edge libraries.

Initially, I put all the implementation into slack-cloudflare-workers, but along the way, I realized that most of it could also be used with Vercel Edge Functions (and presumably other similar runtimes), so I extracted that part as slack-edge and left only the OAuth flow-related implementation (such as managing installation information) using KV in slack-cloudflare-workers.

And while this library was originally a hobby project aimed solely at running on edge functions, as I progressed with the implementation, I was able to complete it as something that solved the challenges that Bolt for JS had been facing for a long time:

Streamlined Slack Web API client
- Improved portability: Eliminated all dependencies on axios and other 3rd party modules as well as Node.js, implemented to depend only on the Fetch API
- Implemented more precise TypeScript typing for API response data (especially the types of Block Kit components are much easier to use)
- Support for Web APIs that are only available on the Next Generation Platform
- Simplified code by completely removing support for deprecated APIs
Native support for async code execution to avoid 3-second timeouts
- Equipped with a feature equivalent to Bolt for Python's Lazy Listeners as standard using the Fetch event's waitUntil command
Resolved issues with TypeScript support in Bolt for JS
- Changed the behavior and payload type of app.message listener to be more intuitive
- By removing support for deprecated features such as old-style dialogs and button click events in attachments, the type of app.action listener arguments is more clearly defined
- Designed to enable developers to more easily avoid the error saying you've called ack() method several times when matching multiple listeners
- More strictly defined the types of returned values from listeners
Added features missing in Bolt for JS
- Added middleware mechanism that runs before the authorize function
- Added support for "Sign in with Slack" (OpenID Connect) feature
Added Socket Mode for local development without other dependency libraries (this is still experimental)
Added supports for emerging JavaScript/TypeScript runtimes such as Deno and Bun

For those who are not familiar with Slack app development, it may seem like a lot of things that aren't quite understandable, but the point is, "It's not just that it works on Cloudflare Workers, it's also improved in many ways over Bolt for JS." If you're going to create a Slack app with TypeScript in 2023, I think it's not an exaggeration to say that this is the easiest library to use. As I mentioned earlier, it's designed to work with Deno and Bun as well, so you can use it even if you want to run your Deno/Bun app on a container service (e.g., k8s, Amazon ECS), not just on edge functions.

Ideally, I'd like to incorporate the insights gained from this development into Bolt for JS, but most of them would result in breaking changes, and as the DevRel team, most of the members are focusing on the next generation platform, so the improvements I could add to the 1st party ones are still very limited. I hope to be able to do it little by little.

Getting Stared

The introduction might be quite long. Now let's finally create a Slack app. Most of the things are already written in the library's README, but I'll go over them with more details.

Install the wragnler CLI and create a project

Install wrangler, the CLI for developing Cloudflare Workers apps, and create a project.

npm install -g wrangler@latest
npx wrangler generate my-slack-app

Proceed with the default specification set to Yes. The console should output something like this.

$ npx wrangler generate my-slack-app
 ⛅️ wrangler 3.2.0
------------------
Using npm as package manager.
▲ [WARNING] The `init` command is no longer supported. Please use `npm create cloudflare@2 -- my-slack-app` instead.

  The `init` command will be removed in a future version.


✨ Created my-slack-app/wrangler.toml
✔ Would you like to use git to manage this Worker? … yes
✨ Initialized git repository at my-slack-app
✔ No package.json found. Would you like to create one? … yes
✨ Created my-slack-app/package.json
✔ Would you like to use TypeScript? … yes
✨ Created my-slack-app/tsconfig.json
✔ Would you like to create a Worker at my-slack-app/src/index.ts? › Fetch handler
✨ Created my-slack-app/src/index.ts
✔ Would you like us to write your first test with Vitest? … yes
✨ Created my-slack-app/src/index.test.ts
npm WARN deprecated rollup-plugin-inject@3.0.2: This package has been deprecated and is no longer maintained. Please use @rollup/plugin-inject.
npm WARN deprecated sourcemap-codec@1.4.8: Please use @jridgewell/sourcemap-codec instead

added 160 packages, and audited 161 packages in 48s

29 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
✨ Installed @cloudflare/workers-types, typescript, and vitest into devDependencies

To start developing your Worker, run `cd my-slack-app && npm start`
To start testing your Worker, run `npm test`
To publish your Worker to the Internet, run `npm run deploy`

Then, we'll add the library I developed, slack-cloudflare-workers:

cd my-slack-app
npm i slack-cloudflare-workers@latest

It's still the default sample code, but if you run npm start, you should see the following console output.

$ npm start

> my-slack-app@0.0.0 start
> wrangler dev

 ⛅️ wrangler 3.2.0
------------------
wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
⎔ Starting local server...
[mf:wrn] The latest compatibility date supported by the installed Cloudflare Workers Runtime is "2023-07-10",
but you've requested "2023-07-15". Falling back to "2023-07-10"...
[mf:inf] Ready on http://127.0.0.1:8787/
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

If you access http://127.0.0.1:8787/ from your browser, you should see Hello World! there.

Slack app settings

Access https://api.slack.com/apps in your web browser. If you're not already logged into the Slack workspace you're planning to use for development in that browser, log in first.

There's a button in the upper right corner that says "Create New App". Click on it, select "From an app manifest", and create an app using the YAML configuration information after the video below (just set it as is for now, we'll change it later).

display_information:
  name: cf-worker-test-app
features:
  bot_user:
    display_name: cf-worker-test-app
    always_online: true
  shortcuts:
    - name: Hey Cloudflare Wokers!
      type: global
      callback_id: hey-cf-workers
      description: Say hi to CF Workers
  slash_commands:
    - command: /hey-cf-workers
      url: https://XXX.trycloudflare.com/
      description: Say hi to CF Workers
      usage_hint: Say hi to CF Workers
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - chat:write.public
      - commands
settings:
  event_subscriptions:
    request_url: https://XXX.trycloudflare.com/
    bot_events:
      - app_mention
  interactivity:
    is_enabled: true
    request_url: https://XXX.trycloudflare.com/
    message_menu_options_url: https://XXX.trycloudflare.com/

Once the app settings are created, you should see a button that says "Install to Workspace". Click on it and complete the installation to your Slack workspace.

Set env variables

Create a file named .dev.vars in the top directory of the project and set it with the following content.

# https://api.slack.com/apps/{your App ID}/general
# Settings > Basic Information > App Credentials > Signing Secret
SLACK_SIGNING_SECRET=....
# https://api.slack.com/apps/{your App ID}/install-on-team
# Settings > Install App > Bot User OAuth Token
SLACK_BOT_TOKEN=xoxb-...
SLACK_LOGGING_LEVEL=DEBUG

As written in the comments,

SLACK_SIGNING_SECRET is in Settings > Basic Information > App Credentials > Signing Secret on the app management screen
SLACK_BOT_TOKEN is in Settings > Install App > Bot User OAuth Token on the app management screen

Please set these to the correct values and restart the npm start command. We will check if they are set correctly in the next step.

Now the minimum preparation is complete! Next, we will check the communication with Slack.

Check if the URL is reachable

Before we start writing code, let's check if the app we're about to develop can communicate correctly with Slack.

Edit `src/index.ts`

We'll flesh out the logic later, but for now, please paste the following minimum code into src/index.ts. It will no longer be consistent with src/index.test.ts, but let's hold off maintaining the tests for now (sorry! this article does not cover how to write tests).

import { SlackApp, SlackEdgeAppEnv } from "slack-cloudflare-workers";

export default {
  async fetch(
    request: Request,
    env: SlackEdgeAppEnv,
    ctx: ExecutionContext
  ): Promise<Response> {
    const app = new SlackApp({ env });

    return await app.run(request, ctx);
  },
};

Configure Cloudflare Tunnel

As mentioned at the beginning, the Request URL needs to be a URL that is publicly available on the internet. The App Manifest YAML settings we set earlier had a placeholder of https://XXX.trycloudflare.com/. We will change this to the correct value.

Please install the command following the steps below to use Cloudflare Tunnel. For instructions other than macOS, please follow the official guide.

brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel --url http://localhost:8787

If it starts up correctly, the console should output something like the following.

$ cloudflared tunnel --url http://localhost:8787
2023-07-15T07:13:03Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to experiment and try it out. However, be aware that these account-less Tunnels have no uptime guarantee. If you intend to use Tunnels in production you should use a pre-created named tunnel by following: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
2023-07-15T07:13:03Z INF Requesting new quick Tunnel on trycloudflare.com...
2023-07-15T07:13:04Z INF +--------------------------------------------------------------------------------------------+
2023-07-15T07:13:04Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
2023-07-15T07:13:04Z INF |  https://system-guam-mpg-adequate.trycloudflare.com                                        |
2023-07-15T07:13:04Z INF +--------------------------------------------------------------------------------------------+
2023-07-15T07:13:04Z INF Cannot determine default configuration path. No file [config.yml config.yaml] in [~/.cloudflared ~/.cloudflare-warp ~/cloudflare-warp /etc/cloudflared /usr/local/etc/cloudflared]
2023-07-15T07:13:04Z INF Version 2023.7.0
2023-07-15T07:13:04Z INF GOOS: darwin, GOVersion: go1.19.3, GoArch: amd64
2023-07-15T07:13:04Z INF Settings: map[ha-connections:1 protocol:quic url:http://localhost:8787]
2023-07-15T07:13:04Z INF cloudflared will not automatically update when run from the shell. To enable auto-updates, run cloudflared as a service: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/run-tunnel/as-a-service/
2023-07-15T07:13:04Z INF Generated Connector ID: 663b9432-4d49-44ef-a1c6-c4d923206a17
2023-07-15T07:13:04Z INF Initial protocol quic
2023-07-15T07:13:04Z INF ICMP proxy will use 192.168.68.112 as source for IPv4
2023-07-15T07:13:04Z INF ICMP proxy will use fe80::1424:857f:f8a9:7f56 in zone en0 as source for IPv6
2023-07-15T07:13:04Z INF Created ICMP proxy listening on 192.168.68.112:0
2023-07-15T07:13:04Z INF Created ICMP proxy listening on [fe80::1424:857f:f8a9:7f56%en0]:0
2023-07-15T07:13:04Z INF Starting metrics server on 127.0.0.1:61426/metrics
2023-07-15T07:13:05Z INF Registered tunnel connection connIndex=0 connection=68158100-10f4-40f6-891f-d5deaa033092 event=0 ip=198.41.192.227 location=NRT protocol=quic

In this case, https://system-guam-mpg-adequate.trycloudflare.com is the available public URL.

Please enter this URL into Request URL under Features > Event Subscriptions on the app configuration page. If .dev.vars is set correctly, it should display Verified as shown below.

Don't forget to press the "Save Changes" button at the bottom right to save the settings. Please set this same URL on the following screens:

Features > Interactivity & Shortcuts > Request URL
Features > Interactivity & Shortcuts > Select Menus > Options Load URL
Features > Slash Commands > Click the pencil icon for /hey-cf-workers > Request URL

Please be careful not to forget to press the save button on each screen.

Add functionalites to the app

We have the minimum preparations in place, but this app has no implementation yet.

Try running the added slash command /hey-cf-workers. You should get an error with the "dispatch_failed" code.

If you look at the console where you started the app with npm start, you should see output like the following.

*** Received request body ***
 {
  "token": "zzz",
  "team_id": "T03E94MJU",
  "team_domain": "seratch",
  "channel_id": "CHE2DUW5V",
  "channel_name": "dev",
  "user_id": "U03E94MK0",
  "user_name": "seratch",
  "command": "/hey-cf-workers",
  "text": "",
  "api_app_id": "A05H6MVTXA6",
  "is_enterprise_install": "false",
  "response_url": "https://hooks.slack.com/commands/T03E94MJU/xxx/yyy",
  "trigger_id": "111.222.xxx"
}
*** No listener found ***
{ .... }
[mf:inf] POST / 404 Not Found (263ms)
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The very simple code to respond to /hey-cf-workers can be as follows.

const app = new SlackApp({ env });
app.command("/hey-cf-workers",
  // "ack" function must complete within 3 seconds
  async (_req) => {
    // This text can be sent as an ephemeral message
    return "What's up?";
  },
  // "lazy" function can do whatever you want to do asynchronously
  async (req) => {
    await req.context.respond({
      text: "Hey! This is an async response!"
    });
  }
);
return await app.run(request, ctx);

If everything is working correctly, you should not get an error this time, and you should see two ephemeral messages displayed.

You might be wondering, "Why are we passing two functions to app.command() here?"

This mechanism of executing two functions, ack/lazy, was originally something I devised for Function-as-a-Service environments like AWS Lambda. Slack's event delivery requires 3rd party apps to respond within 3 seconds, but in AWS Lambda, once a function triggered by an HTTP request returns an HTTP response, the runtime can be terminated, so you can't perform time-consuming asynchronous processing after returning a response. As a solution for it, Bolt for Python's Lazy Listeners were designed to handle asynchronous processing in a separate AWS Lambda execution with the same input.

However, with Cloudflare Workers, there is already a mechanism called the Fetch event's waitUntil command, so there's no need for such a workaround, and the same thing can be achieved with a simple implementation. THIS IS AMAZING!!!

By the way, when it's clear that the lazy processing is not needed, you can omit the second function. However, if you go with this implementation, make sure that all processing finishes within 3 seconds. If that's always true, move the time-consuming processing to the second asynchronous execution function.

app.command("/hey-cf-workers", async () => {
  return "What's up?";
});

Slash commands and Block Kit interations

Let's improve the above slash command example further by adding a message with a Block Kit button, and also add a process for when the button is pressed.

// Post a message with a button in response to a slash command invocation
app.command("/hey-cf-workers", async () => {
  return {
    response_type: "ephemeral",
    text: "Click this!",
    blocks: [
      {
        "type": "section",
        "block_id": "button",
        "text": { "type": "mrkdwn", "text": "Click this!" },
        "accessory": {
          "type": "button",
          "action_id": "button-action", // app.action will match this string
          "text": { "type": "plain_text", "text": "Button" },
          "value": "hidden value",
        }
      }
    ],
  }
});
app.action("button-action",
  async () => { }, // just acknowledge the request
  async ({ context, payload }) => {
    if (context.respond) {
      // context.respond sends a message using response_url
      await context.respond({ text: "You've clicked it!" });
    } else {
      await context.client.views.open({
        trigger_id: payload.trigger_id,
        view: {
          type: "modal",
          callback_id: "test-modal",
          title: { type: "plain_text", text: "Button click" },
          close: { type: "plain_text", text: "Close" },
          blocks: [
            {
              "type": "section",
              "text": { "type": "plain_text", "text": "You've clicked it!" }
            }
          ],
        },
      });
    }
  },
);

This code overwrites the original message where the button was placed.

If you set the response_type to "in_channel", you can post it as a message that can be seen by other people in the channel. The context.respond is a utility that uses response_url to send a message. There is also an example of opening a modal that just conveys the same text in the else clause of the above code, so please try that as well if you like.

Shortcuts and modal data submissions

Next, I will introduce an example where a modal opens when a global shortcut is executed, and input validation is performed when data is sent. An example of a search function using external data is also included.

// From a global shortcut execution to modal data submission
app.shortcut("hey-cf-workers",
  async () => { }, // just acknowledge the request
  async ({ context, body }) => {
    await context.client.views.open({
      trigger_id: body.trigger_id,
      view: {
        type: "modal",
        callback_id: "test-modal", // app.view will match this string
        title: { type: "plain_text", text: "Test modal" },
        submit: { type: "plain_text", text: "Submit" },
        close: { type: "plain_text", text: "Cancel" },
        blocks: [
          {
            "type": "input",
            "block_id": "memo",
            "label": { "type": "plain_text", "text": "Memo" },
            "element": { "type": "plain_text_input", "multiline": true, "action_id": "input" },
          },
          {
            "type": "input",
            "block_id": "category",
            "label": { "type": "plain_text", "text": "Category" },
            "element": {
              "type": "external_select",
              "action_id": "category-search", // app.options will match this string
              'min_query_length': 1,
            },
          }
        ],
      },
    });
  }
);
// Respond to a keyword search using the external_select block element
// This listener must complete to return search results within 3 seconds
// Therefore, having lazy listeners is not supported
app.options("category-search", async ({ payload }) => {
  console.log(`Query: ${payload.value}`);
  // TODO: you will filter the options by the keyword
  return {
    options: [
      {
        "text": { "type": "plain_text", "text": "Work" },
        "value": "work"
      },
      {
        "text": { "type": "plain_text", "text": "Family" },
        "value": "family"
      },
      {
        "text": { "type": "plain_text", "text": "Running" },
        "value": "running"
      },
      {
        "text": { "type": "plain_text", "text": "Random thoughts" },
        "value": "random-thought"
      },
    ],
  };
});
// Handle modal data submissions
app.view("test-modal",
  async ({ payload }) => {
    // Do all the things within 3 seconds here
    const stateValues = payload.view.state.values;
    console.log(JSON.stringify(stateValues, null, 2));
    const memo = payload.view.state.values.memo.input.value!;
    if (memo.length <= 10) {
      // validation errors
      return {
        response_action: "errors",
        errors: { "memo": "The memo must be longer than 10 characters" }
      }
    }
    // Update the modal view as "completed"
    return {
      response_action: "update",
      view: {
        type: "modal",
        callback_id: "test-modal",
        title: { type: "plain_text", text: "Test modal" },
        close: { type: "plain_text", text: "Close" },
        blocks: [
          {
            "type": "section",
            "text": { "type": "plain_text", "text": "Thank you!" }
          }
        ],
      },
    };
    // If you just want to close the modal, no need to return anything here
  },
  async (req) => {
    // you can do async jobs here
  }
);

Event delivery when someone mentions your app's bot

Lasty, here is an example of the Events API. It's the "app_mention" event, which notifies when the bot user of the app is mentioned.

// In the Events API, there are no requirements that must be responded to synchronously within 3 seconds, so you can pass only the lazy function.
app.event("app_mention", async ({ context }) => {
  await context.say({
    text: `Hey <@${context.userId}>, is there anything I can help you with?`
  });
});

If you want to create an app that responds to other events, you can specify the events from this list in the app configuration pages and reinstall it in the workspace to be able to receive them.

The payload argument of the listener function is resolved to the data type of the specified event payload:

If there are any deficiencies or errors, please report them to this issue tracker and I will correct them. I appreciate your help!

Deploy to Cloudflare

That's it for the implementation of the features. Now, let's deploy this app to the Cloudflare Workers environment and see it in action.

wrangler deploy

If the deployment is successful, the console will output something like this:

$ wrangler deploy
 ⛅️ wrangler 3.2.0
------------------
Total Upload: 131.16 KiB / gzip: 19.86 KiB
Uploaded my-slack-app (1.42 sec)
Published my-slack-app (3.77 sec)
  https://my-slack-app.YOURS.workers.dev
Current Deployment ID: f0d7708e-edde-4b29-9bc4-ac4db11fcdbd

If you want to switch the app you just tested locally to production as is, it's a bit of a hassle, but you need to switch all four of the following settings that were previously set with the trycloudflare.com URL to https://my-slack-app.YOURS.workers.dev.

Features > Event Subscriptions > Request URL
Features > Interactivity & Shortcuts > Request URL
Features > Interactivity & Shortcuts > Select Menus > Options Load URL
Features > Slash Commands > Click the pencil icon for /hey-cf-workers > Request URL

If you plan to create a production app with a new separate configuration, it would be easier to replace the https://XXX.trycloudflare.com/ part of the App Manifest YAML configuration file with the issued production URL, and then create the app.

As the last step, tell the Signing Secret and Bot User OAuth Token set in .dev.vars to the production secrets. For this step as well, if you are creating a new production app separately, the values will be different, so please obtain them from the Slack app management screen after installing them in your workspace and specify those values.

wrangler secret put SLACK_SIGNING_SECRET
wrangler secret put SLACK_BOT_TOKEN

The console outputs will look like this:

$ wrangler secret put SLACK_SIGNING_SECRET
 ⛅️ wrangler 3.2.0
------------------
✔ Enter a secret value: … ********************************
🌀 Creating the secret for the Worker "my-slack-app"
✨ Success! Uploaded secret SLACK_SIGNING_SECRET

$ wrangler secret put SLACK_BOT_TOKEN
 ⛅️ wrangler 3.2.0
------------------
✔ Enter a secret value: … ******************************************************
🌀 Creating the secret for the Worker "my-slack-app"
✨ Success! Uploaded secret SLACK_BOT_TOKEN

Once all the settings are complete, please check to see if it works the same way when switched. Perhaps, the app running in the production environment can respond much more quickly.

Wrap up

"Will anyone read this to the end...?" This article has become quite long. Thank you so much for reading this far!

Cloudflare Workers are truly convenient. Especially, the Fetch event's waitUntil command is absolutely fantastic! I almost thought it was a feature designed specifically for Slack apps (joking). Also, the development experience is very smooth, and I think it can be used for various purposes, not limited to Slack apps.

As for slack-edge and slack-cloudflare-workers, they are completely my personal hobby projects. So, I'm not sure how much time I can devote to them, but I hope to continue improving them at my own pace. Currently, they only support KV, so I want to add support for other data stores as well. Please feel free to give me any questions or feedback. Also, if you create something interesting using these, I'd love to hear about it!

That's all for now!

Slack Next-gen Platform - Button Interactions

Kazuhiro "Kaz" Sera — Thu, 29 Dec 2022 23:41:45 +0000

In this tutorial, you'll learn how to use interactions starting from a button in your Slack's next-generation platform apps.

There are two approaches to add button interactions in your next-gen apps:

Use the built-in SendMessage function's interactive_blocks, plus add your own function that handles the block_actions events
Write your custom function that posts a message with buttons, plus add handlers for its block_actions events

This article covers both approaches.

Prerequisites

If you're new to the platform, please read my The Simplest "Hello World" tutorial first. In a nutshell, you'll need a paid Slack workspace, and permission to use the beta feature in the workspace. And then, you can connect your Slack CLI with the workspace.

If all the above are already done, you're ready to build your first app. Let's get started!

Create a Blank Project

When you start a new project, you can run slack create command. In this tutorial, you will build an app from scratch. So select "Blank project" from the list:

$ slack create
? Select a template to build from:

  Hello World
  A simple workflow that sends a greeting

  Scaffolded project
  A solid foundational project that uses a Slack datastore

> Blank project
  A, well.. blank project

  To see all available samples, visit github.com/slack-samples.

Once the project is generated, let's check if slack run command works without any issues. This command installs a "dev" version of your new app into your connected Slack workspace. Now your app's bot user is in the workspace, and your app has its bot token for API calls.

$ cd stoic-wolf-344
$ slack run
? Choose a workspace  seratch  T03E94MJU
   App is not installed to this workspace

Updating dev app install for workspace "Acme Corp"

⚠️  Outgoing domains
   No allowed outgoing domains are configured
   If your function makes network requests, you will need to allow the outgoing domains
   Learn more about upcoming changes to outgoing domains: https://api.slack.com/future/changelog
✨  seratch of Acme Corp
Connected, awaiting events

Handle button clicks on `SendMessage` Function's `interactive_blocks`

The built-in Schema.slack.functions.SendMessage function offers a simplified version of interactive Block Kit components. You can add simple blocks to your message, and then a suceeding custom function can respond to the click events.

For a demo workflow for interactive_blocks handling, you will create two files:

interactive_blocks_demo.ts, which defines a worfklow and its link trigger
handle_interactive_blocks.ts, which defines a custom funtion that handles the button click events in interactive_blocks

Save the following source code as interactive_blocks_demo.ts:

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
export const workflow = DefineWorkflow({
  callback_id: "demo-workflow",
  title: "Demo Workflow",
  input_parameters: {
    properties: {
      channel_id: { type: Schema.slack.types.channel_id },
      user_id: { type: Schema.slack.types.user_id },
    },
    required: ["channel_id", "user_id"],
  },
});

// Send a message via SendMessage + interactive_blocks
const sendMessageStep = workflow.addStep(Schema.slack.functions.SendMessage, {
  channel_id: workflow.inputs.channel_id,
  message: `Do you approve <@${workflow.inputs.user_id}>'s time off request?`,
  // Simplified blocks for interactions
  interactive_blocks: [
    {
      "type": "actions",
      "block_id": "approve-deny-buttons",
      "elements": [
        {
          type: "button",
          action_id: "approve",
          text: { type: "plain_text", text: "Approve" },
          style: "primary",
        },
        {
          type: "button",
          action_id: "deny",
          text: { type: "plain_text", text: "Deny" },
          style: "danger",
        },
      ],
    },
  ],
});

// Handle the button click events on interactive_blocks
import { def as handleInteractiveBlocks } from "./handle_interactive_blocks.ts";
workflow.addStep(handleInteractiveBlocks, {
  // The clicked action's details
  action: sendMessageStep.outputs.action,
  // For further interactions on a modal
  interactivity: sendMessageStep.outputs.interactivity,
  // The message's URL
  messageLink: sendMessageStep.outputs.message_link,
  // The message's unique ID in the channel
  messageTs: sendMessageStep.outputs.message_ts,
});

import { Trigger } from "deno-slack-api/types.ts";
const trigger: Trigger<typeof workflow.definition> = {
  type: "shortcut",
  name: "Interaction Demo Trigger",
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  inputs: {
    channel_id: { value: "{{data.channel_id}}" },
    user_id: { value: "{{data.user_id}}" },
  },
};
export default trigger;

Since handle_interactive_blocks.ts does not exist, the TS compilation should fail at this point. Let's add another file named handle_interactive_blocks.ts. This is a custom function that handles click events that can come from the preceding SendMessage function:

import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";

export const def = DefineFunction({
  callback_id: "handle_interactive_blocks",
  title: "Handle button clicks in interactive_blocks",
  source_file: "handle_interactive_blocks.ts",
  input_parameters: {
    // The input values from the SendMessage function's interactive_blocks
    properties: {
      action: { type: Schema.types.object },
      interactivity: { type: Schema.slack.types.interactivity },
      messageLink: { type: Schema.types.string },
      messageTs: { type: Schema.types.string },
    },
    required: ["action", "interactivity"],
  },
  output_parameters: { properties: {}, required: [] },
});

export default SlackFunction(
  def,
  // When the worfklow is executed, this handler is called
  async ({ inputs, client }) => {
    if (inputs.action.action_id === "deny") {
      // Only when the click is on "Deny", this function opens a modal
      // to ask the reason of the denial
      const response = await client.views.open({
        interactivity_pointer: inputs.interactivity.interactivity_pointer,
        view: buildNewModalView(),
      });
      if (response.error) {
        const error = `Failed to open a modal due to ${response.error}`;
        return { error };
      }
      // Continue the interactions on the modal
      return { completed: false };
    }
    return { completed: true, outputs: {} };
  },
)
  // Handle the button click events on the modal
  .addBlockActionsHandler("clear-inputs", async ({ body, client }) => {
    const response = await client.views.update({
      interactivity_pointer: body.interactivity.interactivity_pointer,
      view_id: body.view.id,
      view: buildNewModalView(),
    });
    if (response.error) {
      const error = `Failed to update a modal due to ${response.error}`;
      return { error };
    }
    return { completed: false };
  })
  // Handle the data submission from the modal
  .addViewSubmissionHandler(
    ["deny-reason-submission"],
    ({ view }) => {
      const values = view.state.values;
      const reason = String(Object.values(values)[0]["deny-reason"].value);
      if (reason.length <= 5) {
        console.log(reason);
        const errors: Record<string, string> = {};
        const blockId = Object.keys(values)[0];
        errors[blockId] = "The reason must be 5 characters or longer";
        return { response_action: "errors", errors };
      }
      return {};
    },
  )
  // Handle the events when the end-user closes the modal
  .addViewClosedHandler(
    ["deny-reason-submission", "deny-reason-confirmation"],
    ({ view }) => {
      console.log(JSON.stringify(view, null, 2));
    },
  );

/**
 * Returns the initial state of the modal view
 * @returns the initial modal view
 */
function buildNewModalView() {
  return {
    "type": "modal",
    "callback_id": "deny-reason-submission",
    "title": { "type": "plain_text", "text": "Reason for the denial" },
    "notify_on_close": true,
    "submit": { "type": "plain_text", "text": "Confirm" },
    "blocks": [
      {
        "type": "input",
        // If you reuse block_id when refreshing an existing modal view,
        // the old block may remain. To avoid this, always set a random value.
        "block_id": crypto.randomUUID(),
        "label": { "type": "plain_text", "text": "Reason" },
        "element": {
          "type": "plain_text_input",
          "action_id": "deny-reason",
          "multiline": true,
          "placeholder": {
            "type": "plain_text",
            "text": "Share the reason why you denied the request in detail",
          },
        },
      },
      {
        "type": "actions",
        "block_id": "clear",
        "elements": [
          {
            type: "button",
            action_id: "clear-inputs",
            text: { type: "plain_text", text: "Clear all the inputs" },
            style: "danger",
          },
        ],
      },
    ],
  };
}

As always, don't forget to add the workflow to manifest.ts:

import { Manifest } from "deno-slack-sdk/mod.ts";
// Add this
import { workflow as InteractiveBlocksDemo } from "./interactive_blocks_demo.ts";

export default Manifest({
  name: "stoic-wolf-344",
  description: "Demo workflow",
  icon: "assets/default_new_app_icon.png",
  workflows: [InteractiveBlocksDemo], // Add this
  outgoingDomains: [],
  botScopes: ["commands", "chat:write", "chat:write.public"],
});

Everything is now ready! Start the app by running slack run command in a terminal window and confirm there is no error in the stdout.

$ slack run
? Choose a workspace  seratch  T03E94MJU
   stoic-wolf-344 A04G9S43G2K

Updating dev app install for workspace "Acme Corp"

⚠️  Outgoing domains
   No allowed outgoing domains are configured
   If your function makes network requests, you will need to allow the outgoing domains
   Learn more about upcoming changes to outgoing domains: https://api.slack.com/future/changelog
✨  seratch of Acme Corp
Connected, awaiting events

And then, open a new terminal window to run slack triggers create --trigger-def interactive_blocks_demo.ts to generate a link trigger.

$ slack triggers create --trigger-def interactive_blocks_demo.ts
? Choose an app  seratch (dev)  T03E94MJU
   stoic-wolf-344 (dev) A04G9S43G2K

⚡ Trigger created
   Trigger ID:   Ft04HCF4SSBB
   Trigger Type: shortcut
   Trigger Name: Interaction Demo Trigger
   URL: https://slack.com/shortcuts/***/***
$

Share the link in a Slack channel and click it. You will see a message with two buttons:

When you click the "Approve" button, your handle_interactive_blocks.ts function accepts the event request and does nothing. In this case, nothing happens apart from the interactive_blocks part replacement by the platform.

Contrarily, when you click the "Deny" button, your custom function opens a new modal dialog to ask the reason for denial.

Also, your additional handler for view data submissions does input data validation (length check), and also provides a button to clear the inputs.

As you can see, when you build a simple approval process, the built-in interactive_blocks is easy to implement. But you cannot customize some details such as how to update the interactive_blocks part when any of the buttons is clicked. If you want to have full control of the interactions, you can build an interactive message blocks using Block Kit from scratch. In the next section, you'll learn how to make it.

Write Custom Function With Full Interactivity Features

Create a new file named send_interactive_message.ts. This source file defines a new custom function that sends a channel message with full-feature Block Kit blocks, and handles all the interactive events with the message's blocks.

import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";

export const def = DefineFunction({
  callback_id: "send_interactive_message",
  title: "Send a message with interactive blocks",
  source_file: "send_interactive_message.ts",
  input_parameters: {
    properties: {
      user_id: { type: Schema.slack.types.user_id },
      channel_id: { type: Schema.slack.types.channel_id },
    },
    required: ["user_id", "channel_id"],
  },
  output_parameters: { properties: {}, required: [] },
});

export default SlackFunction(
  def,
  // When the worfklow is executed, this handler is called
  async ({ inputs, client }) => {
    const text = `Do you approve <@${inputs.user_id}>'s time off request?`;
    // Block Kit elements (https://api.slack.com/block-kit)
    const blocks = [
      {
        type: "section",
        text: { type: "mrkdwn", text },
      },
      { type: "divider" },
      {
        type: "actions",
        block_id: "approve-deny-buttons",
        elements: [
          {
            type: "button",
            action_id: "approve",
            text: { type: "plain_text", text: "Approve" },
            style: "primary",
          },
          {
            type: "button",
            action_id: "deny",
            text: { type: "plain_text", text: "Deny" },
            style: "danger",
          },
        ],
      },
    ];
    const response = await client.chat.postMessage({
      channel: inputs.channel_id,
      text,
      blocks,
    });
    if (response.error) {
      console.log(JSON.stringify(response, null, 2));
      const error = `Failed to post a message due to ${response.error}`;
      return { error };
    }
    // To continue with this interaction, return false for the completion
    return { completed: false };
  },
)
  // Handle the "Approve" button clicks
  .addBlockActionsHandler("approve", async ({ body, client, inputs }) => {
    const text = "Thank you for approving the request!";
    const response = await client.chat.update({
      channel: inputs.channel_id,
      ts: body.container.message_ts,
      text,
      blocks: [{ type: "section", text: { type: "mrkdwn", text } }],
    });
    if (response.error) {
      const error = `Failed to update the message due to ${response.error}`;
      return { error };
    }
    return { completed: true, outputs: {} };
  })
  // Handle the "Deny" button clicks
  .addBlockActionsHandler("deny", async ({ body, client, inputs }) => {
    const text =
      "OK, we need more information... Could you share the reason for denial?";
    const messageResponse = await client.chat.update({
      channel: inputs.channel_id,
      ts: body.container.message_ts,
      text,
      blocks: [{ type: "section", text: { type: "mrkdwn", text } }],
    });
    if (messageResponse.error) {
      const error =
        `Failed to update the message due to ${messageResponse.error}`;
      return { error };
    }
    const modalResponse = await client.views.open({
      interactivity_pointer: body.interactivity.interactivity_pointer,
      view: buildNewModalView(),
    });
    if (modalResponse.error) {
      const error = `Failed to open a modal due to ${modalResponse.error}`;
      return { error };
    }
    return { completed: false };
  })
  // Handle the button click events on the modal
  .addBlockActionsHandler("clear-inputs", async ({ body, client }) => {
    const response = await client.views.update({
      interactivity_pointer: body.interactivity.interactivity_pointer,
      view_id: body.view.id,
      view: buildNewModalView(),
    });
    if (response.error) {
      const error = `Failed to update a modal due to ${response.error}`;
      return { error };
    }
    return { completed: false };
  })
  // Handle the data submission from the modal
  .addViewSubmissionHandler(
    ["deny-reason-submission"],
    ({ view }) => {
      const values = view.state.values;
      const reason = String(Object.values(values)[0]["deny-reason"].value);
      if (reason.length <= 5) {
        console.log(reason);
        const errors: Record<string, string> = {};
        const blockId = Object.keys(values)[0];
        errors[blockId] = "The reason must be 5 characters or longer";
        return { response_action: "errors", errors };
      }
      return {};
    },
  )
  // Handle the events when the end-user closes the modal
  .addViewClosedHandler(
    ["deny-reason-submission", "deny-reason-confirmation"],
    ({ view }) => {
      console.log(JSON.stringify(view, null, 2));
    },
  );

/**
 * Returns the initial state of the modal view
 * @returns the initial modal view
 */
function buildNewModalView() {
  return {
    "type": "modal",
    "callback_id": "deny-reason-submission",
    "title": { "type": "plain_text", "text": "Reason for the denial" },
    "notify_on_close": true,
    "submit": { "type": "plain_text", "text": "Confirm" },
    "blocks": [
      {
        "type": "input",
        // If you reuse block_id when refreshing an existing modal view,
        // the old block may remain. To avoid this, always set a random value.
        "block_id": crypto.randomUUID(),
        "label": { "type": "plain_text", "text": "Reason" },
        "element": {
          "type": "plain_text_input",
          "action_id": "deny-reason",
          "multiline": true,
          "placeholder": {
            "type": "plain_text",
            "text": "Share the reason why you denied the request in detail",
          },
        },
      },
      {
        "type": "actions",
        "block_id": "clear",
        "elements": [
          {
            type: "button",
            action_id: "clear-inputs",
            text: { type: "plain_text", text: "Clear all the inputs" },
            style: "danger",
          },
        ],
      },
    ],
  };
}

Next, create a new workflow that uses the above function. Save the following as interactive_message_demo.ts:

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
export const workflow = DefineWorkflow({
  callback_id: "demo-workflow",
  title: "Demo Workflow",
  input_parameters: {
    properties: {
      channel_id: { type: Schema.slack.types.channel_id },
      user_id: { type: Schema.slack.types.user_id },
    },
    required: ["channel_id", "user_id"],
  },
});

import { def as sendInteractiveMessage } from "./send_interactive_message.ts";
workflow.addStep(sendInteractiveMessage, {
  user_id: workflow.inputs.user_id,
  channel_id: workflow.inputs.channel_id,
});

import { Trigger } from "deno-slack-api/types.ts";
const trigger: Trigger<typeof workflow.definition> = {
  type: "shortcut",
  name: "Interaction Demo Trigger",
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  inputs: {
    channel_id: { value: "{{data.channel_id}}" },
    user_id: { value: "{{data.user_id}}" },
  },
};
export default trigger;

Add the workflow to manifest.ts:

import { Manifest } from "deno-slack-sdk/mod.ts";
import { workflow as InteractiveBlocksDemo } from "./interactive_blocks_demo.ts";
// Add this
import { workflow as InteractiveMessageDemo } from "./interactive_message_demo.ts";

export default Manifest({
  name: "stoic-wolf-344",
  description: "Demo workflow",
  icon: "assets/default_new_app_icon.png",
  workflows: [InteractiveBlocksDemo, InteractiveMessageDemo], // Add this
  outgoingDomains: [],
  botScopes: ["commands", "chat:write", "chat:write.public"],
});

Lastly, create a link trigger in the same way you've done above. When you start the workflow, you will see a message with buttons. When you click the buttons, you'll find the behavior is different from the one with SendMessage's interactive_blocks. The message modification looks more natural.

A simplified code for the message replacement can look like this:

  .addBlockActionsHandler("approve", async ({ body, client, inputs }) => {
    const text = "Thank you for approving the request!";
    await client.chat.update({
      channel: inputs.channel_id,
      ts: body.container.message_ts,
      text,
      blocks: [{ type: "section", text: { type: "mrkdwn", text } }],
    });
    return { completed: true, outputs: {} };
  })

As for the patterns with the "Deny" button, the handler opens a modal in the same way with the first example. In addition, it replaces the message with more meaningful message.

Here is a simplified source code for handling the "Deny" button clicks. Please note that, in this case, your handler can get interactivity not from inputs but from body data.

  .addBlockActionsHandler("deny", async ({ body, client, inputs }) => {
    const text =
      "OK, we need more information... Could you share the reason for denial?";
    await client.chat.update({
      channel: inputs.channel_id,
      ts: body.container.message_ts,
      text,
      blocks: [{ type: "section", text: { type: "mrkdwn", text } }],
    });
    await client.views.open({
      interactivity_pointer: body.interactivity.interactivity_pointer,
      view: buildNewModalView(),
    });
    // To continue interactions, return completed: false
    return { completed: false };
  })

If you're not so familiar with Block Kit and Slack's modals, you may need more time to understand some parts of the code. You can start with this relative simple example and then learn more by changing the code on your own.

To adjust blocks, Block Kit Builder is very useful. If you haven't tried it yet, visit the site and click the available blocks on the left pane.

Wrapping Up

You've learned the following points with this hands-on tutorial:

Use SendMessage's interactive_blocks and handle its events in your custom function
Build a custom function that sends an interactive message and handles the message's interactive events

The complete project is available at https://github.com/seratch/slack-next-generation-platform-tutorials/tree/main/12_Button_Interactions

I hope you enjoy this tutorial! As always, if you have any comments or feedback, please feel free to let me know on Twitter (@seratch) or elsewhere I can check out!

Happy hacking with Slack's next-generation platform 🚀

Slack Next-gen Platform - Trigger Configurator

Kazuhiro "Kaz" Sera — Thu, 29 Dec 2022 14:15:47 +0000

In this tutorial, you'll learn how to build [a workflow to configure another workflow's triggers in your Slack's next-generation platform apps.

When you learned how to add an event trigger that requires channel_ids in its definition (If you haven't read the article, reading it first is highly recommended), I've mentioned that hard-coding the list in code could be a difficulty for many use cases.

This tutorial provides a solution for it. When you have a workflow ("Main" workflow) with an event trigger, in the same app, you can have another workflow ("Configurator" workflow), which configures the trigger for the "Main" workflow. You may wonder if this can be complex, but the implementation is relatively simple. Let's get started!

Prerequisites

If all the above are already done, you're ready to build your first app. Let's get started!

Create a Blank Project

When you start a new project, you can run slack create command. In this tutorial, you will build an app from scratch. So select "Blank project" from the list:

$ slack create
? Select a template to build from:

  Hello World
  A simple workflow that sends a greeting

  Scaffolded project
  A solid foundational project that uses a Slack datastore

> Blank project
  A, well.. blank project

  To see all available samples, visit github.com/slack-samples.

$ cd vibrant-orca-513
$ slack run
? Choose a workspace  seratch  T03E94MJU
   App is not installed to this workspace

Updating dev app install for workspace "Acme Corp"

⚠️  Outgoing domains
   No allowed outgoing domains are configured
   If your function makes network requests, you will need to allow the outgoing domains
   Learn more about upcoming changes to outgoing domains: https://api.slack.com/future/changelog
✨  seratch of Acme Corp
Connected, awaiting events

If you see Connected, awaiting events log message, the app is successfully connected to Slack. You can hit "Ctrl + C" to terminate the local app process.

In this tutorial, we'll build three workflows:

The "Main" workflow that needs a "reaction_added" event trigger
The "Configurator" workflow that configures the "Main" workflow's trigger via a webhook request
The "Configurator" workflow that configures the "Main" workflow's trigger using user inputs sent from a modal dialog

Add The "Main" Workflow

First off, create a new file named main_workflow.ts with the following content:

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";

export const workflow = DefineWorkflow({
  callback_id: "main_event_workflow",
  title: "Main event workflow",
  input_parameters: {
    properties: {
      // The list of input properties needs to be consistent with
      // the trigger operation code in `manage_triggers.ts`
      userId: { type: Schema.slack.types.user_id },
      channelId: { type: Schema.slack.types.channel_id },
      messageTs: { type: Schema.types.string },
      reaction: { type: Schema.types.string },
    },
    required: ["userId", "channelId", "reaction"],
  },
});

// Send an ephemeral message when an expected reaction is added
workflow.addStep(Schema.slack.functions.SendEphemeralMessage, {
  user_id: workflow.inputs.userId,
  channel_id: workflow.inputs.channelId,
  message: `Thanks for adding :${workflow.inputs.reaction}:!`,
});

// This source file does not have its trigger definition!
// The "reaction_added" event trigger will be created by
// the "Configurator" workflow's custom function.

As mentioned at the bottom of the source code, you don't have any trigger definition in this file, as you'll generate a trigger using another workflow.

Also, before forgetting, let's add the workflow to manifest.ts:

import { Manifest } from "deno-slack-sdk/mod.ts";
// Add this
import { workflow as MainWorkflow } from "./main_workflow.ts";

export default Manifest({
  name: "vibrant-orca-513",
  description: "Configurator Demo",
  icon: "assets/default_new_app_icon.png",
  workflows: [MainWorkflow], // Add this
  outgoingDomains: [],
  botScopes: [
    "commands",
    "chat:write",
    "chat:write.public",
    // We're going to use "reaction_added" event trigger
    "reactions:read",
  ],
});

Add The Custom Function To Configure Triggers

The next step is to add your custom function that generates a trigger for a different workflow. Note that the "Configurator" workflow itself will be invoked via a trigger that is created using a source code file.

In this part, you will create three source files - manage_triggers.ts, join_channels.ts, and configure.ts.

Let's start with manage_triggers.ts, which provides the core logic for trigger management. Save the following code as manage_triggers.ts:

import { SlackAPIClient } from "deno-slack-api/types.ts";

// These need to be consistent with `main_workflow.ts`
const triggerEventType = "slack#/events/reaction_added";
const triggerName = "reaction_added event trigger";
const triggerInputs = {
  userId: { value: "{{data.user_id}}" },
  channelId: { value: "{{data.channel_id}}" },
  messageTs: { value: "{{data.message_ts}}" },
  reaction: { value: "{{data.reaction}}" },
};

/**
 * Check if the target trigger already exists and then return the metadata if it exists.
 * @param client Slack API client
 * @param workflowCallbackId the target workflow's callback_id
 * @returns the existing trigger's metadata (can be undefined)
 */
export async function findTriggerToUpdate(
  client: SlackAPIClient,
  workflowCallbackId: string,
): Promise<Record<string, string> | undefined> {
  // Fetch all the triggers that this app can access
  const listResponse = await client.workflows.triggers.list({ is_owner: true });
  // Find the target trigger in the list
  // If the list contains duplicated items, this function may not work properly
  if (listResponse && listResponse.triggers) {
    for (const trigger of listResponse.triggers) {
      if (
        trigger.workflow.callback_id === workflowCallbackId &&
        trigger.event_type === triggerEventType
      ) {
        return trigger;
      }
    }
  }
  // The target trigger does not exist yet
  return undefined;
}

/**
 * Create or update the target trigger. The operation by this method is not atomic, meaning that duplicated triggers can be generated when the creation is requested simultaneously. Also, when updating the trigger, there is no validation of conflicts.
 * @param client Slack API client
 * @param workflowCallbackId the target workflow's callback_id
 * @param channelIds the list of channel IDs to enable the trigger
 * @param triggerId the existing trigger ID (only for updates)
 */
export async function createOrUpdateTrigger(
  client: SlackAPIClient,
  workflowCallbackId: string,
  channelIds: string[],
  triggerId?: string,
): Promise<void> {
  // Since the Deno SDK type constraints require hard-coding the list of string items, there is no way to pass the method argument for it directly. Thus, we have to bypass the type check here.
  // deno-lint-ignore no-explicit-any
  const channel_ids = channelIds as any;

  if (triggerId) {
    // Update the existing trigger
    const update = await client.workflows.triggers.update({
      trigger_id: triggerId,
      type: "event",
      name: triggerName,
      workflow: `#/workflows/${workflowCallbackId}`,
      event: { event_type: triggerEventType, channel_ids },
      inputs: triggerInputs,
    });
    if (update.error) {
      const error = `Failed to update a trigger! - ${JSON.stringify(update)}`;
      throw new Error(error);
    }
    console.log(`The trigger updated: ${JSON.stringify(update)}`);
  } else {
    // Create a new trigger
    const creation = await client.workflows.triggers.create({
      type: "event",
      name: triggerName,
      workflow: `#/workflows/${workflowCallbackId}`,
      event: { event_type: triggerEventType, channel_ids },
      inputs: triggerInputs,
    });
    if (creation.error) {
      const error = `Failed to create a trigger! - ${JSON.stringify(creation)}`;
      throw new Error(error);
    }
    console.log(`A new trigger created: ${JSON.stringify(creation)}`);
  }
}

The next one is join_channels.ts, which provides a utility method to join a lot of channels easily:

import { SlackAPIClient } from "deno-slack-api/types.ts";

/**
 * Join all the channels.
 * Even when the app's bot user has joined, the API does not return an error.
 * @param client
 * @param channelIds
 * @returns
 */
export async function joinAllChannels(
  client: SlackAPIClient,
  channelIds: string[],
): Promise<string | undefined> {
  const futures = channelIds.map((c) => _joinChannel(client, c));
  const results = (await Promise.all(futures)).filter((r) => r !== undefined);
  if (results.length > 0) {
    throw new Error(results[0]);
  }
  return undefined;
}

async function _joinChannel(
  client: SlackAPIClient,
  channelId: string,
): Promise<string | undefined> {
  const response = await client.conversations.join({ channel: channelId });
  if (response.error) {
    const error = `Failed to join <#${channelId}> due to ${response.error}`;
    console.log(error);
    return error;
  }
}

The reason to add your app's bot user is that, without a channel membership, your app cannot call many common APIs such as conversations.history, conversations.replies, and reactions.get APIs. To build something meaningful with channel events, these APIs will be used a lot.

Lastly, let's add configure.ts, a custom function for your "Configurator" workflow. This code has references to the above two source files:

import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";
import {
  createOrUpdateTrigger,
  findTriggerToUpdate,
} from "./manage_triggers.ts";
import { joinAllChannels } from "./join_channels.ts";

export const def = DefineFunction({
  callback_id: "configure",
  title: "Configure a trigger",
  source_file: "configure.ts",
  input_parameters: {
    properties: {
      workflowCallbackId: { type: Schema.types.string },
      channelIds: {
        type: Schema.types.array,
        items: { type: Schema.slack.types.channel_id },
      },
    },
    required: ["workflowCallbackId", "channelIds"],
  },
  output_parameters: { properties: {}, required: [] },
});

export default SlackFunction(def, async ({ inputs, client }) => {
  try {
    await createOrUpdateTrigger(
      client,
      inputs.workflowCallbackId,
      inputs.channelIds,
      (await findTriggerToUpdate(client, inputs.workflowCallbackId))?.id,
    );
  } catch (e) {
    const error = `Failed to create/update a trigger due to ${e}.`;
    return { error };
  }

  // If you don't need to invite your app's bot user to the channels,
  // you can safely remove the following part:
  const failure = await joinAllChannels(client, inputs.channelIds);
  if (failure) {
    const error = `Failed to join channels due to ${failure}.`;
    return { error };
  }

  return { outputs: {} };
});

Create The "Configurator" Workflow (Webhook Trigger)

Let's create your "Configurator" workflow that uses configure.ts for trigger management.

Create a new file named webhook_configurator.ts:

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
export const workflow = DefineWorkflow({
  callback_id: "webhook_configurator",
  title: "Webhook Configurator",
  input_parameters: {
    properties: {
      channel_ids: {
        type: Schema.types.array,
        items: { type: Schema.slack.types.channel_id },
      },
    },
    required: ["channel_ids"],
  },
});

import { def as Configure } from "./configure.ts";
import { workflow as MainWorkflow } from "./main_workflow.ts";
workflow.addStep(Configure, {
  // The callback_id here must be the one for "Main" workflow!
  workflowCallbackId: MainWorkflow.definition.callback_id,
  channelIds: workflow.inputs.channel_ids,
});

// Trigger to invoke the "Configurator" workflow
import { Trigger } from "deno-slack-api/types.ts";
const trigger: Trigger<typeof workflow.definition> = {
  type: "webhook",
  name: "Webhook Configurator Trigger",
  // The callback_id here must be the one for "Configurator" workflow!
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  inputs: { "channel_ids": { "value": "{{data.channel_ids}}" } },
};
export default trigger;

Don't forget to add this workflow to manifest.ts. Adding the "Configurator" workflow to the workflows list, plus a few scopes need to be added to botScopes.

import { Manifest } from "deno-slack-sdk/mod.ts";
import { workflow as MainWorkflow } from "./main_workflow.ts";
// Add this
import { workflow as ConfiguratorWorkflow } from "./webhook_configurator.ts";

export default Manifest({
  name: "vibrant-orca-513",
  description: "Configurator Demo",
  icon: "assets/default_new_app_icon.png",
  workflows: [MainWorkflow, ConfiguratorWorkflow], // Add this
  outgoingDomains: [],
  botScopes: [
    "commands",
    "chat:write",
    "chat:write.public",
    // We're going to use "reaction_added" event trigger
    "reactions:read",
    // Required for `configure.ts`
    "triggers:read",
    "triggers:write",
    "channels:join",
  ],
});

Run slack triggers create --trigger-def ./webhook_configurator.ts to generate a webhook trigger:

$ slack triggers create --trigger-def ./webhook_configurator.ts
? Choose an app  seratch (dev)  T03E94MJU
   vibrant-orca-513 (dev) A04FRL4323G

⚡ Trigger created
   Trigger ID:   Ft04FY7H1AM9
   Trigger Type: webhook
   Trigger Name: Webhook Configurator Trigger
   Webhook URL:  https://hooks.slack.com/triggers/T03E94***/***/***

To invoke the "Configurator" workflow, send an HTTP POST request to the webhook URL with {"channel_ids": ["C03E94MKS"]} in its request body. To know the channel ID string values, go through these steps in the Slack client UI.

$ curl -XPOST \
  https://hooks.slack.com/triggers/T03E94***/***/*** \
  -d'{"channel_ids": ["C03E94MKS"]}'
{"ok":true}%

Check the slack run command terminal. If you don't see any errors, it should be successful!

$ slack run
? Choose a workspace  seratch  T03E94MJU
   vibrant-orca-513 A04FRL4323G

Updating dev app install for workspace "Acme Corp"

⚠️  Outgoing domains
   No allowed outgoing domains are configured
   If your function makes network requests, you will need to allow the outgoing domains
   Learn more about upcoming changes to outgoing domains: https://api.slack.com/future/changelog
✨  seratch of Acme Corp
Connected, awaiting events

2022-12-20 14:14:29 [info] [Fn04GN1S5CP2] (Trace=Tr04FRNYD1QW) Function execution started for workflow function 'Webhook Configurator'
2022-12-20 14:14:29 [info] [Wf04FY7BP8M9] (Trace=Tr04FHQLH3K9) Execution started for workflow 'Webhook Configurator'
2022-12-20 14:14:30 [info] [Wf04FY7BP8M9] (Trace=Tr04FHQLH3K9) Executing workflow step 1 of 1
2022-12-20 14:14:30 [info] [Fn04FVCA06N9] (Trace=Tr04FHQLH3K9) Function execution started for app function 'Configure a trigger'
A new trigger created: {"ok":true,"trigger":{ ... }}
2022-12-20 14:14:32 [info] [Fn04FVCA06N9] (Trace=Tr04FHQLH3K9) Function execution completed for function 'Configure a trigger'
2022-12-20 14:14:32 [info] [Wf04FY7BP8M9] (Trace=Tr04FHQLH3K9) Execution completed for workflow step 'Configure a trigger'
2022-12-20 14:14:33 [info] [Fn04GN1S5CP2] (Trace=Tr04FRNYD1QW) Function execution completed for function 'Webhook Configurator'
2022-12-20 14:14:33 [info] [Wf04FY7BP8M9] (Trace=Tr04FHQLH3K9) Execution completed for workflow 'Webhook Configurator'

Head to the channel you passed in the webhook request, and then add a reaction emoji to a message in the channel. If you receive an ephemeral message like the below, the event trigger for the "Main" workflow is properly configured 🎉

Create The "Configurator" Workflow (Link Trigger + Modal)

The above "Configurator" workflow worked very well, but it's not end-user-friendly. Also, allowing anyone to configure the trigger just by sending an HTTP POST request without any authentication mechanism is not secure enough.

To improve this, let's create a different version of the "Configurator" workflow, which can be invoked via a link trigger and accepts the channel ID list through a modal data submission.

First, add a new function named configure_interactive.ts. This function handles modal interactions plus saves the changes to the target trigger.

import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";
import {
  createOrUpdateTrigger,
  findTriggerToUpdate,
} from "./manage_triggers.ts";
import { joinAllChannels } from "./join_channels.ts";

export const def = DefineFunction({
  callback_id: "configure_interactive",
  title: "Configure a trigger using a modal",
  source_file: "configure_interactive.ts",
  input_parameters: {
    properties: {
      interactivity: { type: Schema.slack.types.interactivity },
      workflowCallbackId: { type: Schema.types.string },
    },
    required: ["interactivity", "workflowCallbackId"],
  },
  output_parameters: { properties: {}, required: [] },
});

export default SlackFunction(def, async ({ inputs, client }) => {
  const trigger = await findTriggerToUpdate(client, inputs.workflowCallbackId);
  const channelIds = trigger?.channel_ids ?? [];

  const response = await client.views.open({
    interactivity_pointer: inputs.interactivity.interactivity_pointer,
    view: {
      "type": "modal",
      "callback_id": "configure-workflow",
      "title": { "type": "plain_text", "text": "My App" },
      "submit": { "type": "plain_text", "text": "Confirm" },
      "close": { "type": "plain_text", "text": "Close" },
      "blocks": [
        {
          "type": "input",
          "block_id": "channels",
          "element": {
            "type": "multi_channels_select",
            "initial_channels": channelIds,
            "action_id": "action",
          },
          "label": {
            "type": "plain_text",
            "text": "Channels to enable the main workflow",
          },
        },
      ],
    },
  });
  if (response.error) {
    const error =
      `Failed to open a modal in the configurator workflow. Contact the app maintainers with the following information - (error: ${response.error})`;
    return { error };
  }
  return {
    // To continue the interaction, you must return completed: false
    completed: false,
  };
})
  .addViewSubmissionHandler(
    ["configure-workflow"],
    async ({ inputs, client, view }) => {
      const channelIds = view.state.values.channels.action.selected_channels;
      try {
        await createOrUpdateTrigger(
          client,
          inputs.workflowCallbackId,
          channelIds,
          (await findTriggerToUpdate(client, inputs.workflowCallbackId))?.id,
        );
      } catch (e) {
        const error = `Failed to create/update a trigger due to ${e}.`;
        return { error };
      }

      // If you don't need to invite your app's bot user to the channels,
      // you can safely remove the following part:
      const failure = await joinAllChannels(client, channelIds);
      if (failure) {
        const error = `Failed to join channels due to ${failure}.`;
        return { error };
      }

      // Display the completion page
      return {
        response_action: "update",
        view: {
          "type": "modal",
          "callback_id": "completion",
          "title": { "type": "plain_text", "text": "My App" },
          "close": { "type": "plain_text", "text": "Close" },
          "blocks": [
            {
              "type": "section",
              "text": {
                "type": "mrkdwn",
                "text":
                  "*You're all set!*\n\nThe main workflow is now available for the channels :white_check_mark:",
              },
            },
          ],
        },
      };
    },
  );

Add modal_configurator.ts, which defines the workflow that calls configure_interactive.ts function, and the workflow's link trigger.

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
export const workflow = DefineWorkflow({
  callback_id: "modal-configurator",
  title: "Modal Configurator",
  input_parameters: {
    properties: { interactivity: { type: Schema.slack.types.interactivity } },
    required: ["interactivity"],
  },
});

import { def as ConfigureWithModal } from "./configure_interactive.ts";
import { workflow as MainWorkflow } from "./main_workflow.ts";
workflow.addStep(ConfigureWithModal, {
  interactivity: workflow.inputs.interactivity,
  // The callback_id here must be the one for "Main" workflow!
  workflowCallbackId: MainWorkflow.definition.callback_id,
});

// Trigger to invoke the "Configurator" workflow
import { Trigger } from "deno-slack-api/types.ts";
const trigger: Trigger<typeof workflow.definition> = {
  type: "shortcut",
  name: "Modal Configurator Trigger",
  // The callback_id here must be the one for "Configurator" workflow!
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  inputs: { interactivity: { value: "{{data.interactivity}}" } },
};
export default trigger;

Lastly, don't forget to add this workflow to manifest.ts:

import { Manifest } from "deno-slack-sdk/mod.ts";
import { workflow as MainWorkflow } from "./main_workflow.ts";
// Add this
import { workflow as ConfiguratorWorkflow } from "./webhook_configurator.ts";
import { workflow as ModalConfiguratorWorkflow } from "./modal_configurator.ts";

export default Manifest({
  name: "vibrant-orca-513",
  description: "Configurator Demo",
  icon: "assets/default_new_app_icon.png",
  workflows: [MainWorkflow, ConfiguratorWorkflow, ModalConfiguratorWorkflow], // Add this
  outgoingDomains: [],
  botScopes: [
    "commands",
    "chat:write",
    "chat:write.public",
    // We're going to use "reaction_added" event trigger
    "reactions:read",
    // Required for `configure.ts`
    "triggers:read",
    "triggers:write",
    "channels:join",
  ],
});

OK, the workflow is ready to use. Generate the link trigger by running slack triggers create --trigger-def modal_configurator.ts, and then share the link in a channel. When you start the workflow, you can easily configure the channel list in the modal UI:

Either way works! But for most use cases, I suggest using this modal configurator. Also, if you're interested in the details of the modal interactions, refer to my "Advanced Modals" tutorial for more information.

Wrapping Up

You've learned the following points with this hands-on tutorial:

Create a "Configurator" workflow, which manages another workflow's triggers

The complete project is available at https://github.com/seratch/slack-next-generation-platform-tutorials/tree/main/11_Trigger_Configurator

I hope you enjoy this tutorial! As always, if you have any comments or feedback, please feel free to let me know on Twitter (@seratch) or elsewhere I can check out!

Happy hacking with Slack's next-generation platform 🚀

Slack Next-gen Platform - Advanced Modals

Kazuhiro "Kaz" Sera — Thu, 29 Dec 2022 06:33:22 +0000

In this tutorial, you'll learn how to use advanced modal interactions in your Slack's next-generation platform apps.

You may have already read The "Built-in Forms" tutorial. With the built-in OpenForm function, you can generate a simple modal view to collect user inputs. It's powerful enough! But it has some limitations, such as no custom handler support for modal data submissions, modal closures, and button interactions.

In this tutorial, I'll guide you on how to build a sophisticated user interface that fully leverages Slack's modals and its foundation, Block Kit UI framework.

Prerequisites

If all the above are already done, you're ready to build your first app. Let's get started!

Create a Blank Project

When you start a new project, you can run slack create command. In this tutorial, you will build an app from scratch. So select "Blank project" from the list:

$ slack create
? Select a template to build from:

  Hello World
  A simple workflow that sends a greeting

  Scaffolded project
  A solid foundational project that uses a Slack datastore

> Blank project
  A, well.. blank project

  To see all available samples, visit github.com/slack-samples.

$ cd sharp-chipmunk-480
$ slack run
? Choose a workspace  seratch  T03E94MJU
   App is not installed to this workspace

Updating dev app install for workspace "Acme Corp"

⚠️  Outgoing domains
   No allowed outgoing domains are configured
   If your function makes network requests, you will need to allow the outgoing domains
   Learn more about upcoming changes to outgoing domains: https://api.slack.com/future/changelog
✨  seratch of Acme Corp
Connected, awaiting events

If you see Connected, awaiting events log message, the app is successfully connected to Slack. You can hit "Ctrl + C" to terminate the local app process.

Define Workflow and Trigger

Let's start with defining a simple demo workflow and its link trigger. As always, save the source code as workflow_and_trigger.ts:

// ----------------
// Workflow Definition
// ----------------
import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
export const workflow = DefineWorkflow({
  callback_id: "modal-demo-workflow",
  title: "Modal Demo Workflow",
  input_parameters: {
    properties: { interactivity: { type: Schema.slack.types.interactivity } },
    required: ["interactivity"],
  },
});

// Add your custom function to open and handle a modal
import { def as ModalDemo } from "./function.ts";
workflow.addStep(ModalDemo, {
  interactivity: workflow.inputs.interactivity,
});

// ----------------
// Trigger Definition
// ----------------
import { Trigger } from "deno-slack-api/types.ts";
const trigger: Trigger<typeof workflow.definition> = {
  type: "shortcut", // link trigger
  name: "Modal Demo Trigger",
  workflow: `#/workflows/${workflow.definition.callback_id}`,
  inputs: {
    // Modal interactions require `interactivity` input parameter.
    // As of this writing, only link triggers can provide the value.
    interactivity: { value: "{{data.interactivity}}" },
  },
};
export default trigger;

Since you don't have function.ts yet, the compilation should fail. Let's add the following source code as function.ts:

import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";

export const def = DefineFunction({
  callback_id: "modal-example",
  title: "Modal interaction example",
  source_file: "function.ts",
  input_parameters: {
    properties: { interactivity: { type: Schema.slack.types.interactivity } },
    required: ["interactivity"],
  },
  output_parameters: { properties: {}, required: [] },
});

export default SlackFunction(
  def,
  // ---------------------------
  // The first handler function that opens a modal.
  // This function can be called when the workflow executes the function step.
  // ---------------------------
  async ({ inputs, client }) => {
    // Open a new modal with the end-user who interacted with the link trigger
    const response = await client.views.open({
      interactivity_pointer: inputs.interactivity.interactivity_pointer,
      view: {
        "type": "modal",
        // Note that this ID can be used for dispatching view submissions and view closed events.
        "callback_id": "first-page",
        // This option is required to be notified when this modal is closed by the user
        "notify_on_close": true,
        "title": { "type": "plain_text", "text": "My App" },
        "submit": { "type": "plain_text", "text": "Next" },
        "close": { "type": "plain_text", "text": "Close" },
        "blocks": [
          {
            "type": "input",
            "block_id": "first_text",
            "element": { "type": "plain_text_input", "action_id": "action" },
            "label": { "type": "plain_text", "text": "First" },
          },
        ],
      },
    });
    if (response.error) {
      const error =
        `Failed to open a modal in the demo workflow. Contact the app maintainers with the following information - (error: ${response.error})`;
      return { error };
    }
    return {
      // To continue with this interaction, return false for the completion
      completed: false,
    };
  },
)
  // ---------------------------
  // The handler that can be called when the above modal data is submitted.
  // It saves the inputs from the first page as private_metadata,
  // and then displays the second-page modal view.
  // ---------------------------
  .addViewSubmissionHandler(["first-page"], ({ view }) => {
    // Extract the input values from the view data
    const firstText = view.state.values.first_text.action.value;
    // Input validations
    if (firstText.length < 5) {
      return {
        response_action: "errors",
        // The key must be a valid block_id in the blocks on a modal
        errors: { first_text: "Must be 5 characters or longer" },
      };
    }
    // Successful. Update the modal with the second page presentation
    return {
      response_action: "update",
      view: {
        "type": "modal",
        "callback_id": "second-page",
        // This option is required to be notified when this modal is closed by the user
        "notify_on_close": true,
        "title": { "type": "plain_text", "text": "My App" },
        "submit": { "type": "plain_text", "text": "Next" },
        "close": { "type": "plain_text", "text": "Close" },
        // Hidden string data, which is not visible to end-users
        // You can use this property to transfer the state of interaction
        // to the following event handlers.
        // (Up to 3,000 characters allowed)
        "private_metadata": JSON.stringify({ firstText }),
        "blocks": [
          // Display the inputs from "first-page" modal view
          {
            "type": "section",
            "text": { "type": "mrkdwn", "text": `First: ${firstText}` },
          },
          // New input block to receive text
          {
            "type": "input",
            "block_id": "second_text",
            "element": { "type": "plain_text_input", "action_id": "action" },
            "label": { "type": "plain_text", "text": "Second" },
          },
        ],
      },
    };
  })
  // ---------------------------
  // The handler that can be called when the second modal data is submitted.
  // It displays the completion page view with the inputs from
  // the first and second pages.
  // ---------------------------
  .addViewSubmissionHandler(["second-page"], ({ view }) => {
    // Extract the first-page inputs from private_metadata
    const { firstText } = JSON.parse(view.private_metadata!);
    // Extract the second-page inputs from the view data
    const secondText = view.state.values.second_text.action.value;
    // Displays the third page, which tells the completion of the interaction
    return {
      response_action: "update",
      view: {
        "type": "modal",
        "callback_id": "completion",
        // This option is required to be notified when this modal is closed by the user
        "notify_on_close": true,
        "title": { "type": "plain_text", "text": "My App" },
        // This modal no longer accepts further inputs.
        // So, the "Submit" button is intentionally removed from the view.
        "close": { "type": "plain_text", "text": "Close" },
        // Display the two inputs
        "blocks": [
          {
            "type": "section",
            "text": { "type": "mrkdwn", "text": `First: ${firstText}` },
          },
          {
            "type": "section",
            "text": { "type": "mrkdwn", "text": `Second: ${secondText}` },
          },
        ],
      },
    };
  })
  // ---------------------------
  // The handler that can be called when the second modal data is closed.
  // If your app runs some resource-intensive operations on the backend side,
  // you can cancel the ongoing process and/or tell the end-user
  // what to do next in DM and so on.
  // ---------------------------
  .addViewClosedHandler(
    ["first-page", "second-page", "completion"],
    ({ view }) => {
      console.log(`view_closed handler called: ${JSON.stringify(view)}`);
      return { completed: true };
    },
  );

I'll explain the details later, but the key points are:

The first handler opens a modal for the end-user
Dispatch modal data submission events using addViewSubmissionHandler()'s handler registration + a modal's callback_id
Dispatch modal closure events using addViewClosedHandler()'s handler registration + a modal's callback_id

Create a Link Trigger

Let's create a link trigger to start an interaction.

$ slack triggers create --trigger-def workflow_and_trigger.ts
? Choose an app  seratch (dev)  T03E94MJU
   sharp-chipmunk-480 (dev) A04G9S43G2K


⚡ Trigger created
   Trigger ID:   Ft04GZK1EE3E
   Trigger Type: shortcut
   Trigger Name: Modal Demo Trigger
   URL: https://slack.com/shortcuts/***/***

Share the link trigger URL in a channel, and click it. You should be able to interact with the modal as expected — the modal transfer your inputs to the second page. The last page displays the two inputs.

When handling the first-page data submission, the handler does input validations (the length check). If the inputs are valid, it returns response_action: "update" with a new modal view. Also, the code passes the inputs as JSON string data, which can be embedded in the modal view as private_metadata.

.addViewSubmissionHandler(["first-page"], ({ view }) => {
  // Extract the input values from the view data
  const firstText = view.state.values.first_text.action.value;
  // Input validations
  if (firstText.length < 5) {
    return {
      response_action: "errors",
      // The key must be a valid block_id in the blocks on a modal
      errors: { first_text: "Must be 5 characters or longer" },
    };
  }
  // Successful. Update the modal with the second-page presentation
  return {
    response_action: "update",
    view: {
      "type": "modal",
      "callback_id": "second-page",
      "private_metadata": JSON.stringify({ firstText }),
      ...
    },
  };
})

As for the second-page handling, the handler extracts values from both view.private_metadata and view.state.values. The updated view displays both values in a single modal view.

.addViewSubmissionHandler(["second-page"], ({ view }) => {
  // Extract the first-page inputs from private_metadata
  const { firstText } = JSON.parse(view.private_metadata!);
  // Extract the second-page inputs from the view data
  const secondText = view.state.values.second_text.action.value;
  // Displays the third page, which tells the completion of the interaction
  return { response_action: "update", view: { ... } };
  };
})

Lastly, your app can handle all the modal closure events by a single handler registered by addViewClosedHandler() method call.

.addViewClosedHandler(
  ["first-page", "second-page", "completion"],
  ({ view }) => {
    console.log(`view_closed handler called: ${JSON.stringify(view)}`);
    return { completed: true };
  },
);

A Few Things To Know

The handlers registered by addViewSubmissionHandler() must complete within 3 seconds (as of this writing, the duration is a bit longer, but it may be changed in the near future). If your handler runs some time-consuming tasks, there are two options:

Update the modal with "Processing..." view first, pass the bot token to the backend service, and then call views.update API when the process completes on the backend side
End the interactions on the modal and then continue the communications with the same user in DM or elsewhere

Also, if you're already familiar with Slack' modals for a long time, you might be confused with the necessity to pass interactivity_pointer instead of trigger_id. Actually, these work in the same way. The only difference is the way to get a value. You can get interactivity_pointer only from inputs.interactivity while the existing platform features provide trigger_id in interactive event payloads.

Wrapping Up

You've learned the following points with this hands-on tutorial:

Start a full-feature modal in your custom function
Handle data submissions from a full-feature modal

The complete project is available at https://github.com/seratch/slack-next-generation-platform-tutorials/tree/main/10_Advanced_Modals

I hope you enjoy this tutorial! As always, if you have any comments or feedback, please feel free to let me know on Twitter (@seratch) or elsewhere I can check out!

Happy hacking with Slack's next-generation platform 🚀

DEV Community: Kazuhiro "Kaz" Sera

OpenAI Agents SDK + Multiple MCP Servers

Python and Node

Slack App

Python Demo Script

Wrap up

Additional Notes on Responses API and Agents SDK

Responses API

Built-in Tools

Agents SDK

Observability Tools

Building Slack Platform Expert AI

Key System Components

Keeping the AI Grounded

Hybrid Retriever Architecture

Building Search Index within Docker Image

Hybrid Search & Ranking

Source Document Data Pipeline

Streamlit UI Optimization

Dynamic “Kaz is thinking …” Indicator

Simple Abuse Prevention & Cached Responses

Sign in with Google

Moving Forward

Easier TypeScript API Testing with Vitest + MSW

Introduction

The Game Changer

How It Works

Setting Up New Project:

Configuring TypeScript:

Start Writing Test Code:

Wrap Up

Further Tips on Slack's files.upload Deprecation

Slack Automation: No More Hardcoding channel_ids for Event Triggers!

What's the Slack Automation Platform?

Types of Event Triggers

What Has Changed?

No Need for channel_ids with all_resources: true!

Migrating Existing Workflows

Reminder: Make Sure Your import_map.json Settings Are Correct!

Wrap Up

Rapid Bolt app development w/ Slack CLI and sandboxes

Slack's Developer Program

What's exciting about this?

Create your first sandbox

What's Enterprise Grid?

Set up Slack CLI

Create a Python app

Set up Python venv and libraries

Place required files for CLI

Start your app

Create a Node.js app

Create a TypeScript + Node.js app

Benefits of using CLI + sandboxes

Wrap up

Slack's remote functions on Cloudflare Workers

Clone the example project

Create a new remote-funtion app

Create Cloudflare Tunnel for local development

Perform an apps.manifest.create API call

Configure secrets

Run the app on your local machine

Deploy the app

Build your own remote function

Running Slack App on Cloudflare Workers

"Slack App" development basics

Digression: New platform feature for Workflow Builder

Wanna go without any libraries?

Request verification

Various formats of payloads

Various data patterns

Why don't you use Bolt?

Getting Stared

Install the wragnler CLI and create a project

Slack app settings

Set env variables

Check if the URL is reachable

Edit src/index.ts

Configure Cloudflare Tunnel

Add functionalites to the app

Slash commands and Block Kit interations

No Need for `channel_ids` with `all_resources: true`!

Edit `src/index.ts`

Handle button clicks on `SendMessage` Function's `interactive_blocks`