Skip to content

Commit

Permalink
Changed tutorial path and included review suggestions
Browse files Browse the repository at this point in the history
  • Loading branch information
@VaishnaviNandakumar
VaishnaviNandakumar committed Nov 8, 2023
1 parent 91d716d commit 05c57bd
Showing 1 changed file with 67 additions and 66 deletions.
133 changes: 67 additions & 66 deletions ...ng-started/slackbot-websocket-tutorial.md → .../tutorials/slackbot-websocket-tutorial.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
---
title: Create an AsyncAPI Document for a SlackBot with WebSockets
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
weight: 140
---

## Introduction
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 `Heart-Counter-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` 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 `Heart-Counter-Slack-Bot` should work:
Here’s a visual representation of how `Heart-Counter` should work:

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

## Background context
Expand All @@ -48,46 +48,47 @@ Note left of Heart-Counter-Slack-Bot: Event received
```mermaid
sequenceDiagram
Client -->> Server: Initiate WebSocket Connection
Server -->> Client: WebSocket Response
Server -->> Client: WebSocket Response
Server -->> Client: WebSocket Response
Server -->> Client: WebSocket Response
Server -->> Client: Message 1
Server -->> Client: Message 2
Server -->> Client: Message 3
Server -->> Client: Message 4
```

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
## 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`, `protocol` and `description`.
The `servers` section allows you to define the protocol and specify information about the URLs your application will use, such as `host`, `pathname`, `protocol` and `description`.

<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.
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 your Slackbot to generate this URL.
</Remember>

```
asyncapi: '3.0.0'
info:
title: Create an AsyncAPI Document for a SlackBot with WebSockets
title: Create an AsyncAPI Document for a Slackbot with WebSockets
version: '1.0.0'
description: |
The Heart-Counter-Slack-Bot manages popular messages in a Slack workspace by monitoring message reaction data using Slack's Event API.
The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data
servers:
ws:
host: wss://wss-primary.slack.com/
production:
host: wss://wss-primary.slack.com
pathname: /link/
protocol: wss
description: Websocket URL generated to communicate with Slack
description: Slack's server in Socket Mode for real-time communication
```


## Define Channels and Bindings
## Define channels and bindings

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.

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.
The WebSocket URL generated for `Heart-Counter` 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:
Expand All @@ -113,8 +114,8 @@ channels:
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.
## Define operations
The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how `Heart-Counter` 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.

Expand All @@ -137,7 +138,7 @@ operations:
- $ref: '#/channels/root/messages/reactionListener'
```

## Define Messages and Schemas
## 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.

Expand All @@ -150,48 +151,22 @@ The `const` value feature ensures that the data exchanged through your API compl
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 @@ -211,6 +186,32 @@ 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
```


Expand All @@ -219,16 +220,17 @@ You've now completed the tutorial! Putting these blocks together gives you your
```
asyncapi: '3.0.0'
info:
title: Create an AsyncAPI Document for a SlackBot with WebSockets
title: Create an AsyncAPI Document for a Slackbot with WebSockets
version: '1.0.0'
description: |
The Heart-Counter-Slack-Bot manages popular messages in a Slack workspace by monitoring message reaction data using Slack's Event API.
The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data
servers:
ws:
host: wss://wss-primary.slack.com/
production:
host: wss://wss-primary.slack.com
pathname: /link/
protocol: wss
description: Websocket URL generated to communicate with Slack
description: Slack's server in Socket Mode for real-time communication
channels:
root:
Expand Down Expand Up @@ -275,7 +277,7 @@ components:
$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'
Expand Down Expand Up @@ -327,14 +329,13 @@ components:
description: Channel information of original message
ts:
type: string
description: Timestamp information of original message.
description: Timestamp information of original message
event_ts:
type: string
description: Reaction timestamp
```




## Summary
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.
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 05c57bd

Please sign in to comment.