Skip to content

Commit

Permalink
Renamed slack-bot name and updated AsyncAPI doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@VaishnaviNandakumar
VaishnaviNandakumar committed Oct 31, 2023
1 parent 353e7bb commit 91d716d
Showing 1 changed file with 114 additions and 87 deletions.
201 changes: 114 additions & 87 deletions pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
---
title: Creating an AsyncAPI Document for a SlackBot in Socket Mode
description: In this tutorial, you'll learn how to create an AsyncAPI document designed for a Slack application that operates in Socket Mode.
title: Create an AsyncAPI Document for a SlackBot with WebSockets
description: In this tutorial, you'll learn how to create an AsyncAPI document designed for a Slack application that operates in Socket Mode using the WebSockets protocol.
weight: 80
---

## Introduction
In this tutorial, you will learn how to generate an AsyncAPI document designed for a Slack application that operates in Socket Mode. Our aim is to help you grasp a real-world application of AsyncAPI with the WebSocket protocol.
In this tutorial, you will learn how to generate an AsyncAPI document designed for a Slack application that operates in Socket Mode. The aim is to help you grasp a real-world application of AsyncAPI with the WebSocket protocol.

Consider a scenario where you are in charge of maintaining a highly active Slack workspace. You want an easy way to keep track of the popular messages across all the channels but doing this manually would be a difficult task. To simplify this process, you’re going to build a Slackbot called my-slack-bot that actively monitors reactions added to a message and determine its popularity by counting the reactions of the “heart” emoji.
Consider a scenario where you are in charge of maintaining a highly active Slack workspace. You want an easy way to keep track of the popular messages across all the channels but doing this manually would be a difficult task. To simplify this process, you’re going to build a Slackbot called `Heart-Counter-Slack-Bot` that actively monitors reactions added to a message and determine its popularity by counting the reactions of the “heart” emoji.

Here’s a visual representation of how my-slack-bot should work.
Here’s a visual representation of how `Heart-Counter-Slack-Bot` should work:

```mermaid
sequenceDiagram
participant my-slack-bot
participant Heart-Counter-Slack-Bot
participant Slack Server (Socket Mode)
participant User
my-slack-bot->>Slack Server (Socket Mode): Connect
Note right of my-slack-bot: Establish WebSocket connection
Heart-Counter-Slack-Bot ->>Slack Server (Socket Mode): Connect
Note right of Heart-Counter-Slack-Bot: Establish WebSocket connection
Slack Server (Socket Mode)->> my-slack-bot : Handshake
Slack Server (Socket Mode)->> Heart-Counter-Slack-Bot : Handshake
Note left of Slack Server (Socket Mode): Establish Socket Mode connection
Slack Server (Socket Mode)->> my-slack-bot : Sends "hello" event
Slack Server (Socket Mode)->> Heart-Counter-Slack-Bot : Sends "hello" event
Note left of Slack Server (Socket Mode): Confirms successful connection
Expand All @@ -35,14 +35,14 @@ Note left of Slack Server (Socket Mode): Confirms successful connection
User-->>Slack Server (Socket Mode): Adds emoji to a message.
Slack Server (Socket Mode)->>my-slack-bot: Sending "reaction_added" payload
Slack Server (Socket Mode)->>Heart-Counter-Slack-Bot: Sending "reaction_added" payload
Note left of my-slack-bot: Event received
Note left of Heart-Counter-Slack-Bot: Event received
```

## Background context
[WebSocket](https://en.wikipedia.org/wiki/WebSocket) is a communication protocol that enables full-duplex, bidirectional data exchange between a client and a server over a single, long-lived connection. Unlike HTTP, which relies on the request-response model, WebSocket is ideal for scenarios where real-time, interactive and low-latency communication is necessary.
[WebSocket](https://en.wikipedia.org/wiki/WebSocket) is a communication protocol that enables simultaneous bidirectional data exchange between a client and a server over a single, long-lived connection. Unlike HTTP, which relies on the request-response model, WebSocket is ideal for scenarios where real-time, interactive and low-latency communication is necessary.


```mermaid
Expand All @@ -54,81 +54,97 @@ Server -->> Client: WebSocket Response
Server -->> Client: WebSocket Response
```

In Slack, WebSocket is employed as part of its [Socket Mode](https://api.slack.com/apis/connections/socket) feature to facilitate real-time notifications between Slack's servers and third-party applications or bots. Socket Mode simplifies Slack app development by eliminating complex infrastructure challenges faced with HTTP, offering simpler and more feature driven solutions for app developers.


The [Slack Event API](https://api.slack.com/apis/connections/events-api) is a tool that lets developers receive real-time notifications of specific events in a Slack workspace. By subscribing to event types like messages, reactions, and user presence changes, this API enhances automation within the Slack platform, making it a powerful resource for building custom integrations and chatbots.

In Slack, WebSocket is employed as part of its [Socket Mode](https://api.slack.com/apis/connections/socket) feature to facilitate real-time notifications between Slack's servers and third-party applications or bots. The [Slack Event API](https://api.slack.com/apis/connections/events-api) is a tool that lets you receive real-time notifications of specific events in a Slack workspace such as messages, reactions, and user presence changes.


## Define AsyncAPI Version, API Information, and Server

You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slack application's API which includes details such as the `title`, `version` and `description`.

The `ws` server section allows you to define the protocol and specify information about the URLs your application will use, such as `host`, `pathname`, and `description`.
The `ws` server section allows you to define the protocol and specify information about the URLs your application will use, such as `host`, `protocol` and `description`.

The WebSocket URL is generated by invoking the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API. You use the authorization tokens obtained during the configuration of my-slack-bot to generate this URL.
<Remember>
The WebSocket URL is generated by invoking the <a href="https://api.slack.com/methods/apps.connections.open">apps.connections.open</a> method from Slack’s API. You use the authentication tokens obtained during the configuration of <code>Heart-Counter-Slack-Bot</code> to generate this URL.
</Remember>

```
asyncapi: '3.0.0'
info:
title: MySlackBot API
title: Create an AsyncAPI Document for a SlackBot with WebSockets
version: '1.0.0'
description: |
The MySlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API.
The Heart-Counter-Slack-Bot manages popular messages in a Slack workspace by monitoring message reaction data using Slack's Event API.
servers:
ws:
host: wss://wss-primary.slack.com/
pathname: link/?ticket=13748dac-b866-4ea7-b98e-4fb7895c0a7f&app_id=fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f
protocol: wss
description: "Websocket URL generated to communicate with Slack"
description: Websocket URL generated to communicate with Slack
```


## Define Operations and Channels
The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how my-slack-bot interacts with Slack.
## Define Channels and Bindings

In this example, the `helloListenerOperation` keeps an eye out for the message sent by the Slack server when a WebSocket connection is successfully established. On the other hand, the `reactionListener` is focused on the reaction_added event type.
The `channels` attribute defines a communication channel for the event. The `address` specifies where the channel is tuned in to receive messages while the `messages` property defines a key-value pair where each key corresponds to the event it's set up to handle.

Your Slack application is designed to be notified of events within your workspace. It does this by subscribing to a specific event type making use of Slack's Event API. So in this case the `action` property in both the operations is set to receive events.

Now, moving on to the `channels` section. The `address` specifies where the channel is tuned in to receive messages while the `messages` property defines the structure of the event it's set up to handle.
The WebSocket URL generated for `Heart-Counter-Slack-Bot` includes authentication tokens, and this protocol-specific data is represented using the `bindings` attribute. By utilizing the `query` object, you can outline the parameters needed for the connection and the conditions they must meet.

```
channels:
reactionListener:
address: /
messages:
reactionListener:
$ref: '#/components/messages/reactionListenerMessage'
helloListener:
root:
address: /
messages:
helloListener:
$ref: '#/components/messages/helloListenerMessage'
reactionListener:
$ref: '#/components/messages/reactionListenerMessage'
bindings:
ws:
query:
type: object
description: Contains the authentication tokens for the WebSocket URL
properties:
ticket:
type: string
const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f'
app_id:
type: string
const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f'
```

## Define Operations
The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how `Heart-Counter-Slack-Bot` interacts with Slack.

In this example, the `helloListenerOperation` keeps an eye out for the message sent by the Slack server when a WebSocket connection is successfully established. On the other hand, the `reactionListener` is focused on the `reaction_added` event type.

Your Slack application is designed to be notified of events within your workspace. It does this by subscribing to a specific event type making use of Slack's Event API. So in this case the `action` property in both the operations is set to `receive` events.

```
operations:
helloListenerOperation:
action: receive
channel:
$ref: "#/channels/helloListener"
$ref: '#/channels/root'
messages:
- $ref: '#/channels/root/messages/helloListener'
reactionListenerOperation:
action: receive
channel:
$ref: "#/channels/reactionListener"
$ref: '#/channels/root'
messages:
- $ref: '#/channels/root/messages/reactionListener'
```

## Define Messages and Schemas

Your AsyncAPI document needs to be very clear on the type of event it is expected to receive. Here's where the `messages` component steps in. Using the `payload` property, you can specify what these events should look like, their structure, and what content they carry.

And that brings us to what the `payload` attribute does. It specifies the name, format, and description of all expected properties, and can even set constant values that must be followed during schema validation.
For example, in `reactionPayload` schema definition, any API message received from this channel must follow the constant value for the "reaction" property which is clearly defined as “heart”.
That leads us to the function of the `payload` attribute. It specifies the name, format, and description of all expected properties, and can even set constant values that must be followed during schema validation.
For example, in `reactionPayload` schema definition, any API message received from this channel must follow the constant value for the `reaction` property which is clearly defined as “heart”.

The const value feature ensures that the data exchanged through your API complies with your specified constants, helping to maintain data integrity and accuracy.
The `const` value feature ensures that the data exchanged through your API complies with your specified constants, helping to maintain data integrity and accuracy.

```
components:
Expand Down Expand Up @@ -198,92 +214,78 @@ components:
```


And there you have it! Putting these blocks together gives you your AsyncAPI document all ready to go.
You've now completed the tutorial! Putting these blocks together gives you your AsyncAPI document all ready to go.

```
asyncapi: '3.0.0'
info:
title: MySlackBot API
title: Create an AsyncAPI Document for a SlackBot with WebSockets
version: '1.0.0'
description: |
The MySlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API.
The Heart-Counter-Slack-Bot manages popular messages in a Slack workspace by monitoring message reaction data using Slack's Event API.
servers:
ws:
host: wss://wss-primary.slack.com/
pathname: link/?ticket=13748dac-b866-4ea7-b98e-4fb7895c0a7f&app_id=fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f
protocol: wss
description: "Websocket URL generated to communicate with Slack"
description: Websocket URL generated to communicate with Slack
channels:
reactionListener:
address: /
messages:
reactionListener:
$ref: '#/components/messages/reactionListenerMessage'
helloListener:
root:
address: /
messages:
helloListener:
$ref: '#/components/messages/helloListenerMessage'
reactionListener:
$ref: '#/components/messages/reactionListenerMessage'
bindings:
ws:
query:
type: object
description: Contains the authentication tokens for the WebSocket URL
properties:
ticket:
type: string
const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f'
app_id:
type: string
const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f'
operations:
helloListenerOperation:
action: receive
channel:
$ref: "#/channels/helloListener"
$ref: '#/channels/root'
messages:
- $ref: '#/channels/root/messages/helloListener'
reactionListenerOperation:
action: receive
channel:
$ref: "#/channels/reactionListener"
$ref: '#/channels/root'
messages:
- $ref: '#/channels/root/messages/reactionListener'
components:
messages:
reactionListenerMessage:
summary: "Action triggered when channel receives a new event of type reaction-added"
summary: Action triggered when the channel receives a new reaction-added event
payload:
$ref: '#/components/schemas/reactionPayload'
helloListenerMessage:
summary: "Action triggered when a successful WebSocket connection is established."
summary: Action triggered when a successful WebSocket connection is established.
payload:
$ref: '#/components/schemas/helloPayload'
schemas:
reactionPayload:
type: object
properties:
user:
type: string
description: ID of the user who performed this event
reaction:
type: string
description: The only reaction that we need is a heart emoji
const: "heart"
item_user:
type: string
description: ID of the user that created the original item that has been reacted to
item:
type: object
properties:
channel:
type: string
description: Channel information of original message
ts:
type: string
description: Timestamp information of original message.
event_ts:
type: string
description: Timestamp of reaction
helloPayload:
type: object
properties:
type:
type: string
description: A hello string confirming WS connection
description: A hello string confirming WebSocket connection
const: "hello"
connection_info:
type: object
Expand All @@ -303,11 +305,36 @@ components:
type: integer
approximate_connection_time:
type: integer
reactionPayload:
type: object
properties:
user:
type: string
description: User ID who performed this event
reaction:
type: string
description: The only reaction that we need is a heart emoji
const: "heart"
item_user:
type: string
description: User ID that created the original item that has been reacted to
item:
type: object
properties:
channel:
type: string
description: Channel information of original message
ts:
type: string
description: Timestamp information of original message.
event_ts:
type: string
description: Reaction timestamp
```




## Summary
In this tutorial, you were introduced to a practical application of WebSocket protocols within an AsyncAPI document. In our future tutorials, we'll dive deeper into more advanced concepts and explore the extensive features of AsyncAPI.

In this tutorial, you learned to create an AsyncAPI document for a SlackBot using WebSocket in Socket Mode. You gained practical insights into the functionality of operations, channels, messages, and schemas. Now you're equipped to handle real-world applications that facilitates bidirectional real-time data exchange such as chatbots and live-streaming platforms.

0 comments on commit 91d716d

Please sign in to comment.