From cfab59130d4a6f5f4a201921d9cd86631da07c96 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Wed, 18 Oct 2023 20:41:01 +0530 Subject: [PATCH 01/30] Initial draft --- .../slackbot-websocket-tutorial.md | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md new file mode 100644 index 000000000000..213c2171680a --- /dev/null +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -0,0 +1,167 @@ +--- +title: Building a SlackBot with AsyncAPI and WebSocket +description: In this tutorial, you'll learn how to create an AsyncAPI document designed for a Slack application that operates in Socket Mode +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. + +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, we're going to build a Slackbot with some specific features. + +- **Event Subscription:** Your Slackbot 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. +- **Event Type:** In the context of your Slackbot, it actively listens for the "reaction_added" event type. This event is triggered each time a user reacts to a message using an emoji. +- **Popularity Indicator:** The bot will now specifically look at the count of the “heart” emoji to indicate the popularity of the message. +- **Communication Protocol:** Slack employs a WebSocket URL as a means of communication with your application. + +## 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. + +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 makes it easier to create Slack apps without dealing with complex infrastructure issues. Building these apps using HTTP had challenges when working from certain environments. With Socket Mode, this becomes simpler and more feature-rich 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, third-party apps can react to these events instantly. This API enhances automation and interactivity within the Slack platform, making it a powerful resource for building custom integrations and chatbots. + +## Create AsyncAPI document + +``` +asyncapi: '3.0.0' +info: + title: SlackBot API + version: '1.0.0' + description: | + The SlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. + +servers: + ws: + host: wss.slack.com/ + pathname: ticket=$ticketId&app_id=$appId + protocol: ws + description: "Websocket URL generated to communicate with Slack" + +channels: + reactionListener: + address: / + messages: + reactionListener: + $ref: '#/components/messages/reactionListener' + +operations: + reactionListener: + action: receive + channel: + $ref: "#/channels/reactionListener" + +components: + messages: + reactionListener: + summary: "Action triggered when channel receives a new event of type reaction-added" + payload: + $ref: '#/components/schemas/reactionPayload' + + 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 +``` + +Let’s take a closer look - + +``` +servers: + ws: + host: wss.slack.com/ + pathname: ticket={ticketId}&app_id={appId} + protocol: ws + description: "Websocket URL generated to communicate with Slack" +``` + +In the ws server section, we refer to the WebSocket URL generated at runtime by invoking the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API. Authorization tokens, obtained during the Slackbot configuration, are used to generate this URL. + +``` +operations: + reactionListener: + action: receive + channel: + $ref: "#/channels/reactionListener" +``` +The `reactionListener` operation defines how the Slackbot interacts with Slack. In this use case, it's configured to **receive** events from Slack through the app's event subscription. + +``` +channels: + reactionListener: + address: / + messages: + reactionListener: + $ref: '#/components/messages/reactionListener' +``` +"The `operation` property links us to the `channel` section, offering additional details. The reactionListener channel is established to receive events from Slack. The `address` specifies where the channel is tuned to while the `messages` property is used to define the structure of the events it's set up to handle. + +``` +components: + messages: + reactionListener: + summary: "Action triggered when channel receives a new event of type reaction-added" + payload: + $ref: '#/components/schemas/reactionPayload' +``` +Within the `components` section, we specify the message structure for reactionListener. This structure is composed of key-value pairs, and the payload section details how an event should look when received by the Slackbot. + +``` + 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 +``` +And that brings us to the `payload` property. This property strictly defines the structure of the event using AsyncAPI schemas. It contains the property name, format type and description. + +The AsyncAPI document also allows you to set specific constant values that must be adhered to. In this schema definition, any API message received from this channel must follow the constant value for the "reaction" property which is clearly defined as “heart”. + +This feature ensures that the data exchanged through your API complies with your specified constants, helping to maintain data integrity and accuracy. + + +## Summary + +This tutorial introduced you to the practical application of WebSocket protocols within an AsyncAPI document. We used a practical example to build a Slack App that effectively worked with Slack's Event API in Socket Mode. In our future tutorials, we'll dive deeper into more advanced concepts and explore the extensive features of AsyncAPI. From 9acefa730514be93f80c187371cfa65e32fd2d88 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Thu, 19 Oct 2023 16:57:56 +0530 Subject: [PATCH 02/30] Added steps and diagrams --- .../slackbot-websocket-tutorial.md | 140 +++++++++++++----- 1 file changed, 105 insertions(+), 35 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index 213c2171680a..b7a53ba45f81 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -7,21 +7,72 @@ 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. -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, we're going to build a Slackbot with some specific features. +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 that actively monitors reactions added to a message and determine its popularity by counting the reactions of the “heart” emoji. -- **Event Subscription:** Your Slackbot 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. -- **Event Type:** In the context of your Slackbot, it actively listens for the "reaction_added" event type. This event is triggered each time a user reacts to a message using an emoji. -- **Popularity Indicator:** The bot will now specifically look at the count of the “heart” emoji to indicate the popularity of the message. -- **Communication Protocol:** Slack employs a WebSocket URL as a means of communication with your application. +Here’s a visual representation of how your Slackbot should work. + +```mermaid +sequenceDiagram +participant Slackbot +participant WebSocket +participant Slack API Server +participant User + + +Slackbot->>WebSocket: Connect +Note right of Slackbot: Establish WebSocket connection + + +Slack API Server->>WebSocket : Handshake +Note right of WebSocket: Establish Socket Mode connection + + +Slackbot->>WebSocket: Listen for Events +Note right of Slackbot : Start listening for "reaction_added" Slack events + + +User-->>Slack API Server: Adds emoji to a message. + + +Slack API Server->>WebSocket: Slack's Events API Sends payload to WS URL + + +WebSocket->>Slackbot: Event Data +Note left of Slackbot: Event received by Slackbot +``` ## 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 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. + + +```mermaid +sequenceDiagram +Client -->> Server: Initiate WebSocket Connection +Server -->> Client: WebSocket Response +Server -->> Client: WebSocket Response +Server -->> Client: WebSocket Response +Server -->> Client: WebSocket Response +``` + +```mermaid +sequenceDiagram +Client -->> Server: Initiate HTTP Connection +Server -->> Client: HTTP Response +Client -->> Server: Pull +Server -->> Client: Response +Client -->> Server: Pull +Server -->> Client: 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 makes it easier to create Slack apps without dealing with complex infrastructure issues. Building these apps using HTTP had challenges when working from certain environments. With Socket Mode, this becomes simpler and more feature-rich 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, third-party apps can react to these events instantly. This API enhances automation and interactivity within the Slack platform, making it a powerful resource for building custom integrations and chatbots. ## Create AsyncAPI document +In this section, you will learn how to write an AsyncAPI document for the Slackbot. This document will serve as a resource for understanding and interacting with your Slackbot, making it easier for others to integrate and work with your API. + +**Step 1: Define AsyncAPI Version, API Information, and Server** ``` asyncapi: '3.0.0' @@ -38,19 +89,41 @@ servers: protocol: ws description: "Websocket URL generated to communicate with Slack" +``` +You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slackbot API. This includes details such as the `title`, `version` and `description`. + +In the `ws` server section, the WebSocket URL is generated at runtime 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 Slackbot configuration to generate this URL. + +**Step 2 : Define Operations and Channels** + +``` channels: reactionListener: address: / messages: reactionListener: - $ref: '#/components/messages/reactionListener' + $ref: '#/components/messages/reactionListenerMessage' + operations: - reactionListener: + reactionListenerOperation: action: receive channel: $ref: "#/channels/reactionListener" +``` +The `operation` property, which we'll explore through the `reactionListenerOperation` is all about defining specific tasks your application can perform. Essentially, it's how your Slackbot interacts with Slack. + +Your Slackbot 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 is set to receive events. + +Now, moving on to the `channel` section, you have the `reactionListener` channel that is set to to receive events from Slack. 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. +**Step 3: Define Messages and Schemas** + +Next up, we have the `messages` section and this is where things get slightly technical. In the context of your Slackbot, it actively listens for the "reaction_added" event type which gets triggered each time a user reacts to a message using an emoji. + +Your AsyncAPI document needs to be very clear on the type of event it is expected to receive. This is 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. + +``` components: messages: reactionListener: @@ -58,6 +131,7 @@ components: payload: $ref: '#/components/schemas/reactionPayload' + schemas: reactionPayload: type: object @@ -85,50 +159,49 @@ components: type: string description: Timestamp of reaction ``` +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 this schema definition, any API message received from this channel must follow the constant value for the "reaction" property which is clearly defined as “heart”. + +This feature ensures that the data exchanged through your API complies with your specified constants, helping to maintain data integrity and accuracy. -Let’s take a closer look - +And there you have it! Putting these blocks together gives you your AsyncAPI document all ready to go. ``` +asyncapi: '3.0.0' +info: + title: SlackBot API + version: '1.0.0' + description: | + The SlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. + servers: ws: host: wss.slack.com/ - pathname: ticket={ticketId}&app_id={appId} + pathname: ticket=$ticketId&app_id=$appId protocol: ws description: "Websocket URL generated to communicate with Slack" -``` - -In the ws server section, we refer to the WebSocket URL generated at runtime by invoking the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API. Authorization tokens, obtained during the Slackbot configuration, are used to generate this URL. - -``` -operations: - reactionListener: - action: receive - channel: - $ref: "#/channels/reactionListener" -``` -The `reactionListener` operation defines how the Slackbot interacts with Slack. In this use case, it's configured to **receive** events from Slack through the app's event subscription. -``` channels: reactionListener: address: / messages: reactionListener: - $ref: '#/components/messages/reactionListener' -``` -"The `operation` property links us to the `channel` section, offering additional details. The reactionListener channel is established to receive events from Slack. The `address` specifies where the channel is tuned to while the `messages` property is used to define the structure of the events it's set up to handle. + $ref: '#/components/messages/reactionListenerMessage' + +operations: + reactionListenerOperation: + action: receive + channel: + $ref: "#/channels/reactionListener" -``` components: messages: - reactionListener: + reactionListenerMessage: summary: "Action triggered when channel receives a new event of type reaction-added" payload: $ref: '#/components/schemas/reactionPayload' -``` -Within the `components` section, we specify the message structure for reactionListener. This structure is composed of key-value pairs, and the payload section details how an event should look when received by the Slackbot. -``` + schemas: reactionPayload: type: object properties: @@ -155,13 +228,10 @@ Within the `components` section, we specify the message structure for reactionLi type: string description: Timestamp of reaction ``` -And that brings us to the `payload` property. This property strictly defines the structure of the event using AsyncAPI schemas. It contains the property name, format type and description. -The AsyncAPI document also allows you to set specific constant values that must be adhered to. In this schema definition, any API message received from this channel must follow the constant value for the "reaction" property which is clearly defined as “heart”. -This feature ensures that the data exchanged through your API complies with your specified constants, helping to maintain data integrity and accuracy. ## 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. -This tutorial introduced you to the practical application of WebSocket protocols within an AsyncAPI document. We used a practical example to build a Slack App that effectively worked with Slack's Event API in Socket Mode. In our future tutorials, we'll dive deeper into more advanced concepts and explore the extensive features of AsyncAPI. From 5d0488157c957f9b5b5e1a2d00dce946779a7157 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Thu, 19 Oct 2023 17:05:14 +0530 Subject: [PATCH 03/30] Fixed minor issues --- .../getting-started/slackbot-websocket-tutorial.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index b7a53ba45f81..2351defc2489 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -67,10 +67,10 @@ Server -->> Client: 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 makes it easier to create Slack apps without dealing with complex infrastructure issues. Building these apps using HTTP had challenges when working from certain environments. With Socket Mode, this becomes simpler and more feature-rich 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, third-party apps can react to these events instantly. This API enhances automation and interactivity within the Slack platform, making it a powerful resource for building custom integrations and chatbots. +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, third-party apps can react to these events instantly. The API enhances automation and interactivity within the Slack platform, making it a powerful resource for building custom integrations and chatbots. ## Create AsyncAPI document -In this section, you will learn how to write an AsyncAPI document for the Slackbot. This document will serve as a resource for understanding and interacting with your Slackbot, making it easier for others to integrate and work with your API. +In this section, you will learn how to write an AsyncAPI document for the Slackbot. The document will serve as a resource for understanding and interacting with your Slackbot, making it easier for others to integrate and work with your API. **Step 1: Define AsyncAPI Version, API Information, and Server** @@ -90,7 +90,7 @@ servers: description: "Websocket URL generated to communicate with Slack" ``` -You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slackbot API. This includes details such as the `title`, `version` and `description`. +You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slackbot API which includes details such as the `title`, `version` and `description`. In the `ws` server section, the WebSocket URL is generated at runtime 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 Slackbot configuration to generate this URL. @@ -119,9 +119,9 @@ Now, moving on to the `channel` section, you have the `reactionListener` channel **Step 3: Define Messages and Schemas** -Next up, we have the `messages` section and this is where things get slightly technical. In the context of your Slackbot, it actively listens for the "reaction_added" event type which gets triggered each time a user reacts to a message using an emoji. +Next up comes the `messages` section and this is where things get slightly technical. In the context of your Slackbot, it actively listens for the "reaction_added" event type which gets triggered each time a user reacts to a message using an emoji. -Your AsyncAPI document needs to be very clear on the type of event it is expected to receive. This is 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. +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. ``` components: @@ -162,7 +162,7 @@ components: 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 this schema definition, any API message received from this channel must follow the constant value for the "reaction" property which is clearly defined as “heart”. -This 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. And there you have it! Putting these blocks together gives you your AsyncAPI document all ready to go. From 10b83826e0234526a73d9758c531279e4b9b7d30 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Thu, 26 Oct 2023 00:19:26 +0530 Subject: [PATCH 04/30] Added content for hello event --- .../slackbot-websocket-tutorial.md | 175 +++++++++++++----- 1 file changed, 127 insertions(+), 48 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index 2351defc2489..4715bfd0814d 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -1,44 +1,44 @@ --- -title: Building a SlackBot with AsyncAPI and WebSocket -description: In this tutorial, you'll learn how to create an AsyncAPI document designed for a Slack application that operates in Socket Mode +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. 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. -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 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 my-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 your Slackbot should work. ```mermaid sequenceDiagram -participant Slackbot -participant WebSocket -participant Slack API Server +participant my-slack-bot +participant Slack Server (Socket Mode) participant User -Slackbot->>WebSocket: Connect -Note right of Slackbot: Establish WebSocket connection +my-slack-bot->>Slack Server (Socket Mode): Connect +Note right of my-slack-bot: Establish WebSocket connection -Slack API Server->>WebSocket : Handshake -Note right of WebSocket: Establish Socket Mode connection +Slack Server (Socket Mode)->> my-slack-bot : Handshake +Note left of Slack Server (Socket Mode): Establish Socket Mode connection +Slack Server (Socket Mode)->> my-slack-bot : Sends "hello" event +Note left of Slack Server (Socket Mode): Confirms successful connection -Slackbot->>WebSocket: Listen for Events -Note right of Slackbot : Start listening for "reaction_added" Slack events -User-->>Slack API Server: Adds emoji to a message. -Slack API Server->>WebSocket: Slack's Events API Sends payload to WS URL +User-->>Slack Server (Socket Mode): Adds emoji to a message. -WebSocket->>Slackbot: Event Data -Note left of Slackbot: Event received by Slackbot +Slack Server (Socket Mode)->>my-slack-bot: Sending "reaction_added" payload + + +Note left of my-slack-bot: Event received by Slackbot ``` ## Background context @@ -54,25 +54,22 @@ Server -->> Client: WebSocket Response Server -->> Client: WebSocket Response ``` -```mermaid -sequenceDiagram -Client -->> Server: Initiate HTTP Connection -Server -->> Client: HTTP Response -Client -->> Server: Pull -Server -->> Client: Response -Client -->> Server: Pull -Server -->> Client: 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. Socket Mode makes it easier to create Slack apps without dealing with complex infrastructure issues. Building these apps using HTTP had challenges when working from certain environments. With Socket Mode, this becomes simpler and more feature-rich 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, third-party apps can react to these events instantly. The API enhances automation and interactivity within the Slack platform, making it a powerful resource for building custom integrations and chatbots. +## Define AsyncAPI Version, API Information, and Server -## Create AsyncAPI document -In this section, you will learn how to write an AsyncAPI document for the Slackbot. The document will serve as a resource for understanding and interacting with your Slackbot, making it easier for others to integrate and work with your API. +You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slackbot 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`. -**Step 1: Define AsyncAPI Version, API Information, and Server** + +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 Slack Bot configuration to generate this URL. + ``` asyncapi: '3.0.0' @@ -90,11 +87,16 @@ servers: description: "Websocket URL generated to communicate with Slack" ``` -You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slackbot API which includes details such as the `title`, `version` and `description`. -In the `ws` server section, the WebSocket URL is generated at runtime 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 Slackbot configuration to generate this URL. -**Step 2 : Define Operations and Channels** +## Define Operations and Channels +The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how your Slackbot interacts with Slack. + +In this example, we make use of two operations. 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 Slackbot 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. ``` channels: @@ -103,34 +105,43 @@ channels: messages: reactionListener: $ref: '#/components/messages/reactionListenerMessage' - + + helloListener: + address: / + messages: + helloListener: + $ref: '#/components/messages/helloListenerMessage' operations: + helloListenerOperation: + action: receive + channel: + $ref: "#/channels/helloListener" + reactionListenerOperation: action: receive channel: $ref: "#/channels/reactionListener" ``` -The `operation` property, which we'll explore through the `reactionListenerOperation` is all about defining specific tasks your application can perform. Essentially, it's how your Slackbot interacts with Slack. -Your Slackbot 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 is set to receive events. +## Step 3: Define Messages and Schemas -Now, moving on to the `channel` section, you have the `reactionListener` channel that is set to to receive events from Slack. 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. - -**Step 3: Define Messages and Schemas** - -Next up comes the `messages` section and this is where things get slightly technical. In the context of your Slackbot, it actively listens for the "reaction_added" event type which gets triggered each time a user reacts to a message using an emoji. +In the context of your Slackbot, it actively monitors two events. The first is the "hello" event, received upon successfully securing a WebSocket connection. The second is the "reaction_added" event type, triggered whenever a user reacts to a message using an emoji. 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. ``` components: messages: - reactionListener: + reactionListenerMessage: summary: "Action triggered when channel receives a new event of type reaction-added" payload: $ref: '#/components/schemas/reactionPayload' - + + helloListenerMessage: + summary: "Action triggered when a successful WebSocket connection is established." + payload: + $ref: '#/components/schemas/helloPayload' schemas: reactionPayload: @@ -158,9 +169,35 @@ components: event_ts: type: string description: Timestamp of reaction + + helloPayload: + type: object + properties: + type: + type: string + description: A hello string confirming WS connection + const: "hello" + connection_info: + type: object + properties: + app_id: + type: string + num_connections: + type: integer + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer ``` 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 this schema definition, any API message received from this channel must follow the constant value for the "reaction" property which is clearly defined as “heart”. +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. @@ -169,16 +206,16 @@ And there you have it! Putting these blocks together gives you your AsyncAPI doc ``` asyncapi: '3.0.0' info: - title: SlackBot API + title: MySlackBot API version: '1.0.0' description: | The SlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. servers: ws: - host: wss.slack.com/ - pathname: ticket=$ticketId&app_id=$appId - protocol: 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" channels: @@ -187,8 +224,19 @@ channels: messages: reactionListener: $ref: '#/components/messages/reactionListenerMessage' + + helloListener: + address: / + messages: + helloListener: + $ref: '#/components/messages/helloListenerMessage' operations: + helloListenerOperation: + action: receive + channel: + $ref: "#/channels/helloListener" + reactionListenerOperation: action: receive channel: @@ -200,6 +248,11 @@ components: summary: "Action triggered when channel receives a new event of type reaction-added" payload: $ref: '#/components/schemas/reactionPayload' + + helloListenerMessage: + summary: "Action triggered when a successful WebSocket connection is established." + payload: + $ref: '#/components/schemas/helloPayload' schemas: reactionPayload: @@ -227,6 +280,32 @@ components: event_ts: type: string description: Timestamp of reaction + + helloPayload: + type: object + properties: + type: + type: string + description: A hello string confirming WS connection + const: "hello" + connection_info: + type: object + properties: + app_id: + type: string + num_connections: + type: integer + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer ``` From d073e0b04401a20c743599651977a9513d35d474 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Thu, 26 Oct 2023 00:25:27 +0530 Subject: [PATCH 05/30] Removed remember tag --- .../tutorials/getting-started/slackbot-websocket-tutorial.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index 4715bfd0814d..cf24a221cd27 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -67,9 +67,7 @@ You start your AsyncAPI document by specifying the AsyncAPI version and essentia 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 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 Slack Bot configuration to generate this URL. - ``` asyncapi: '3.0.0' From dd97bd7418643174ea2c680408f2a102110fe9ce Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Thu, 26 Oct 2023 10:30:50 +0530 Subject: [PATCH 06/30] Renamed instances of SlackBot --- .../slackbot-websocket-tutorial.md | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index cf24a221cd27..9e9de5789fb0 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -9,7 +9,7 @@ In this tutorial, you will learn how to generate an AsyncAPI document designed f 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. -Here’s a visual representation of how your Slackbot should work. +Here’s a visual representation of how my-slack-bot should work. ```mermaid sequenceDiagram @@ -63,36 +63,35 @@ The [Slack Event API](https://api.slack.com/apis/connections/events-api) is a to ## Define AsyncAPI Version, API Information, and Server -You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slackbot API which includes details such as the `title`, `version` and `description`. +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 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 Slack Bot configuration to generate this URL. +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. ``` asyncapi: '3.0.0' info: - title: SlackBot API + title: MySlackBot API version: '1.0.0' description: | The SlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. servers: ws: - host: wss.slack.com/ - pathname: ticket=$ticketId&app_id=$appId - protocol: 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" - ``` ## Define Operations and Channels -The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how your Slackbot interacts with Slack. +The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how your my-slack-bot interacts with Slack. In this example, we make use of two operations. 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 Slackbot 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. +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. @@ -122,12 +121,17 @@ operations: $ref: "#/channels/reactionListener" ``` -## Step 3: Define Messages and Schemas +## Define Messages and Schemas -In the context of your Slackbot, it actively monitors two events. The first is the "hello" event, received upon successfully securing a WebSocket connection. The second is the "reaction_added" event type, triggered whenever a user reacts to a message using an emoji. +In the context of my-slack-bot, it actively monitors two events. The first is the "hello" event, received upon successfully securing a WebSocket connection. The second is the "reaction_added" event type, triggered whenever a user reacts to a message using an emoji. 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”. + +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: messages: @@ -194,10 +198,7 @@ components: approximate_connection_time: type: integer ``` -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”. -The const value feature ensures that the data exchanged through your API complies with your specified constants, helping to maintain data integrity and accuracy. And there you have it! Putting these blocks together gives you your AsyncAPI document all ready to go. From 353e7bb05963ef9f6d5d8351374d518f19dd9f6c Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Fri, 27 Oct 2023 00:06:55 +0530 Subject: [PATCH 07/30] Renamed instances of SlackBot --- .../getting-started/slackbot-websocket-tutorial.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index 9e9de5789fb0..2a261de6dcaa 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -38,7 +38,7 @@ User-->>Slack Server (Socket Mode): Adds emoji to a message. Slack Server (Socket Mode)->>my-slack-bot: Sending "reaction_added" payload -Note left of my-slack-bot: Event received by Slackbot +Note left of my-slack-bot: Event received ``` ## Background context @@ -75,7 +75,7 @@ info: title: MySlackBot API version: '1.0.0' description: | - The SlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. + The MySlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. servers: ws: @@ -87,9 +87,9 @@ servers: ## Define Operations and Channels -The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how your my-slack-bot interacts with Slack. +The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how my-slack-bot interacts with Slack. -In this example, we make use of two operations. 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. +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. @@ -123,8 +123,6 @@ operations: ## Define Messages and Schemas -In the context of my-slack-bot, it actively monitors two events. The first is the "hello" event, received upon successfully securing a WebSocket connection. The second is the "reaction_added" event type, triggered whenever a user reacts to a message using an emoji. - 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. @@ -208,7 +206,7 @@ info: title: MySlackBot API version: '1.0.0' description: | - The SlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. + The MySlackBot App manages popular messages in a workspace by monitoring message reaction data from Slack's Event API. servers: ws: From 91d716d79ef9a9178a3d7c0273be6e3f6d69d4ce Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Wed, 1 Nov 2023 00:19:08 +0530 Subject: [PATCH 08/30] Renamed slack-bot name and updated AsyncAPI doc --- .../slackbot-websocket-tutorial.md | 201 ++++++++++-------- 1 file changed, 114 insertions(+), 87 deletions(-) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md index 2a261de6dcaa..4008530186d3 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md @@ -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 @@ -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 @@ -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. + +The WebSocket URL is generated by invoking the apps.connections.open method from Slack’s API. You use the authentication tokens obtained during the configuration of Heart-Counter-Slack-Bot to generate this URL. + ``` 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: @@ -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 @@ -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. From 05c57bd79ad44b82e166cdcf358964c39cc5b92c Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Wed, 8 Nov 2023 20:53:27 +0530 Subject: [PATCH 09/30] Changed tutorial path and included review suggestions --- .../slackbot-websocket-tutorial.md | 133 +++++++++--------- 1 file changed, 67 insertions(+), 66 deletions(-) rename pages/docs/tutorials/{getting-started => }/slackbot-websocket-tutorial.md (77%) diff --git a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md b/pages/docs/tutorials/slackbot-websocket-tutorial.md similarity index 77% rename from pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md rename to pages/docs/tutorials/slackbot-websocket-tutorial.md index 4008530186d3..d56f99081f5f 100644 --- a/pages/docs/tutorials/getting-started/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/slackbot-websocket-tutorial.md @@ -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 @@ -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 @@ -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`. -The WebSocket URL is generated by invoking the apps.connections.open method from Slack’s API. You use the authentication tokens obtained during the configuration of Heart-Counter-Slack-Bot to generate this URL. +The WebSocket URL is generated by invoking the apps.connections.open method from Slack’s API. You use the authentication tokens obtained during the configuration of your Slackbot to generate this URL. ``` 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: @@ -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. @@ -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. @@ -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 @@ -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 ``` @@ -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: @@ -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' @@ -327,7 +329,7 @@ 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 @@ -335,6 +337,5 @@ components: - ## 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. From a1f3929d2ec83ea66c7d15dcd3cb398af17ec7fe Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Tue, 14 Nov 2023 20:12:03 +0530 Subject: [PATCH 10/30] Changed order of message sections and updated AsyncAPI doc --- .../tutorials/slackbot-websocket-tutorial.md | 158 +++++++++--------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/pages/docs/tutorials/slackbot-websocket-tutorial.md b/pages/docs/tutorials/slackbot-websocket-tutorial.md index d56f99081f5f..b8db65129c91 100644 --- a/pages/docs/tutorials/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/slackbot-websocket-tutorial.md @@ -78,71 +78,16 @@ info: servers: production: host: wss://wss-primary.slack.com - pathname: /link/ + pathname: /link protocol: wss description: Slack's server in Socket Mode for real-time communication ``` - -## 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` 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: - 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` 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/root' - messages: - - $ref: '#/channels/root/messages/helloListener' - - reactionListenerOperation: - action: receive - channel: - $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. -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. +The `payload` attribute 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. @@ -150,18 +95,18 @@ The `const` value feature ensures that the data exchanged through your API compl ``` components: messages: - reactionListenerMessage: + reaction: summary: Action triggered when the channel receives a new reaction-added event payload: - $ref: '#/components/schemas/reactionPayload' + $ref: '#/components/schemas/reaction' - helloListenerMessage: + hello: summary: Action triggered when a successful WebSocket connection is established payload: - $ref: '#/components/schemas/helloPayload' + $ref: '#/components/schemas/hello' schemas: - helloPayload: + hello: type: object properties: type: @@ -187,7 +132,7 @@ components: approximate_connection_time: type: integer - reactionPayload: + reaction: type: object properties: user: @@ -214,6 +159,60 @@ components: description: Reaction timestamp ``` +## 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` 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: + root: + address: / + messages: + hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' + + bindings: + ws: + query: + type: object + properties: + ticket: + type: string + description: Temporary token generated when connection is initiated + const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' + app_id: + type: string + description: Unique identifier assigned to the Slack app + const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' +``` + +## 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. + +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: + helloListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/hello' + + reactionListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' +``` You've now completed the tutorial! Putting these blocks together gives you your AsyncAPI document all ready to go. @@ -228,7 +227,7 @@ info: servers: production: host: wss://wss-primary.slack.com - pathname: /link/ + pathname: /link protocol: wss description: Slack's server in Socket Mode for real-time communication @@ -236,53 +235,54 @@ channels: root: address: / messages: - helloListener: - $ref: '#/components/messages/helloListenerMessage' - reactionListener: - $ref: '#/components/messages/reactionListenerMessage' + hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' bindings: ws: query: type: object - description: Contains the authentication tokens for the WebSocket URL properties: ticket: type: string + description: Temporary token generated when connection is initiated const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' app_id: type: string + description: Unique identifier assigned to the Slack app const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' operations: - helloListenerOperation: + helloListener: action: receive channel: $ref: '#/channels/root' messages: - - $ref: '#/channels/root/messages/helloListener' + - $ref: '#/channels/root/messages/hello' - reactionListenerOperation: + reactionListener: action: receive channel: $ref: '#/channels/root' messages: - - $ref: '#/channels/root/messages/reactionListener' + - $ref: '#/channels/root/messages/reaction' components: messages: - reactionListenerMessage: + reaction: summary: Action triggered when the channel receives a new reaction-added event payload: - $ref: '#/components/schemas/reactionPayload' + $ref: '#/components/schemas/reaction' - helloListenerMessage: + hello: summary: Action triggered when a successful WebSocket connection is established payload: - $ref: '#/components/schemas/helloPayload' + $ref: '#/components/schemas/hello' schemas: - helloPayload: + hello: type: object properties: type: @@ -308,7 +308,7 @@ components: approximate_connection_time: type: integer - reactionPayload: + reaction: type: object properties: user: From d4342da2d6eeca8b7f75c7e746ef55b05cd142d8 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Tue, 14 Nov 2023 21:20:19 +0530 Subject: [PATCH 11/30] Added desc for queries --- pages/docs/tutorials/slackbot-websocket-tutorial.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/slackbot-websocket-tutorial.md b/pages/docs/tutorials/slackbot-websocket-tutorial.md index b8db65129c91..39ab7c8eb5cf 100644 --- a/pages/docs/tutorials/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/slackbot-websocket-tutorial.md @@ -88,7 +88,7 @@ servers: 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. The `payload` attribute 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”. +For example, in `reaction` 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. @@ -179,6 +179,7 @@ channels: ws: query: type: object + description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API properties: ticket: type: string @@ -193,7 +194,7 @@ channels: ## 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. +In this example, the `helloListener` operation 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. @@ -244,6 +245,7 @@ channels: ws: query: type: object + description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API properties: ticket: type: string From 8fcd64c3aefa60de48e9ed17d4f78fa8ab5c8420 Mon Sep 17 00:00:00 2001 From: Vaishnavi <41518119+VaishnaviNandakumar@users.noreply.github.com> Date: Wed, 15 Nov 2023 21:01:13 +0530 Subject: [PATCH 12/30] Update pages/docs/tutorials/slackbot-websocket-tutorial.md Co-authored-by: Lukasz Gornicki --- pages/docs/tutorials/slackbot-websocket-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/slackbot-websocket-tutorial.md b/pages/docs/tutorials/slackbot-websocket-tutorial.md index 39ab7c8eb5cf..7c418783ff4d 100644 --- a/pages/docs/tutorials/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/slackbot-websocket-tutorial.md @@ -5,7 +5,7 @@ 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. +In this tutorial, you will learn how to write 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. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a Websocket server. You will also learn why AsyncAPI bindings feature exist and how to use it. 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. From e8eeade69f70f52ccc83aa389ce468d2c93154ae Mon Sep 17 00:00:00 2001 From: Vaishnavi <41518119+VaishnaviNandakumar@users.noreply.github.com> Date: Wed, 15 Nov 2023 21:01:33 +0530 Subject: [PATCH 13/30] Update pages/docs/tutorials/slackbot-websocket-tutorial.md Co-authored-by: Lukasz Gornicki --- pages/docs/tutorials/slackbot-websocket-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/slackbot-websocket-tutorial.md b/pages/docs/tutorials/slackbot-websocket-tutorial.md index 7c418783ff4d..5558b5700c19 100644 --- a/pages/docs/tutorials/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/slackbot-websocket-tutorial.md @@ -163,7 +163,7 @@ components: 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` 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. This information is represented using query parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is a protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. ``` channels: From aa98467ef592290e8ea5e4aaf4509fc0ebecfd9a Mon Sep 17 00:00:00 2001 From: Vaishnavi <41518119+VaishnaviNandakumar@users.noreply.github.com> Date: Wed, 15 Nov 2023 21:32:25 +0530 Subject: [PATCH 14/30] Update slackbot-websocket-tutorial.md Minor format changes --- pages/docs/tutorials/slackbot-websocket-tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/slackbot-websocket-tutorial.md b/pages/docs/tutorials/slackbot-websocket-tutorial.md index 5558b5700c19..adc2c3a7725b 100644 --- a/pages/docs/tutorials/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/slackbot-websocket-tutorial.md @@ -5,7 +5,7 @@ weight: 140 --- ## Introduction -In this tutorial, you will learn how to write 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. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a Websocket server. You will also learn why AsyncAPI bindings feature exist and how to use it. +In this tutorial, you will learn how to write 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. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a WebSocket server. You will also learn why AsyncAPI bindings feature exist and how to use it. 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. @@ -163,7 +163,7 @@ components: 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` includes authentication tokens. This information is represented using query parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is a protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, 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. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is a protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. ``` channels: From ab599014a61814ffe3226b8e3df31e7b48cc47a5 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Fri, 17 Nov 2023 15:55:56 +0530 Subject: [PATCH 15/30] Added new directory - WebSocket --- pages/docs/tutorials/websocket/_section.md | 4 ++++ .../{slackbot-websocket-tutorial.md => websocket/index.md} | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 pages/docs/tutorials/websocket/_section.md rename pages/docs/tutorials/{slackbot-websocket-tutorial.md => websocket/index.md} (99%) diff --git a/pages/docs/tutorials/websocket/_section.md b/pages/docs/tutorials/websocket/_section.md new file mode 100644 index 000000000000..fea168daf9bc --- /dev/null +++ b/pages/docs/tutorials/websocket/_section.md @@ -0,0 +1,4 @@ +--- +title: 'WebSocket' +weight: 2 +--- diff --git a/pages/docs/tutorials/slackbot-websocket-tutorial.md b/pages/docs/tutorials/websocket/index.md similarity index 99% rename from pages/docs/tutorials/slackbot-websocket-tutorial.md rename to pages/docs/tutorials/websocket/index.md index adc2c3a7725b..f55f722537fb 100644 --- a/pages/docs/tutorials/slackbot-websocket-tutorial.md +++ b/pages/docs/tutorials/websocket/index.md @@ -1,7 +1,7 @@ --- 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: 140 +weight: 2 --- ## Introduction From 6002a98976430ea4784c64015a2b04a82882f6cc Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Fri, 17 Nov 2023 15:59:52 +0530 Subject: [PATCH 16/30] Updated weights --- pages/docs/tutorials/websocket/_section.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/websocket/_section.md b/pages/docs/tutorials/websocket/_section.md index fea168daf9bc..98082695efaa 100644 --- a/pages/docs/tutorials/websocket/_section.md +++ b/pages/docs/tutorials/websocket/_section.md @@ -1,4 +1,4 @@ --- title: 'WebSocket' -weight: 2 +weight: 20 --- From 5439191fb1d97aaeb2775cc3fce6fb99e0e94400 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Fri, 17 Nov 2023 16:04:38 +0530 Subject: [PATCH 17/30] Updated weights --- pages/docs/tutorials/websocket/_section.md | 2 +- pages/docs/tutorials/websocket/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/websocket/_section.md b/pages/docs/tutorials/websocket/_section.md index 98082695efaa..f0967315b307 100644 --- a/pages/docs/tutorials/websocket/_section.md +++ b/pages/docs/tutorials/websocket/_section.md @@ -1,4 +1,4 @@ --- title: 'WebSocket' -weight: 20 +weight: 200 --- diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index f55f722537fb..d1d20791748b 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -1,7 +1,7 @@ --- 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: 2 +weight: 210 --- ## Introduction From f4317b0569b9a99a47c5b9c4c25826fd347c9f9e Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Thu, 7 Dec 2023 13:01:56 +0530 Subject: [PATCH 18/30] Made minor change in asyncapi doc and fixed typo --- pages/docs/tutorials/websocket/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index d1d20791748b..178e5bfd0992 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -5,7 +5,7 @@ weight: 210 --- ## Introduction -In this tutorial, you will learn how to write 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. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a WebSocket server. You will also learn why AsyncAPI bindings feature exist and how to use it. +In this tutorial, you will learn how to write 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. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a WebSocket server. You will also learn why the AsyncAPI bindings feature exist and how to use it. 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. @@ -77,7 +77,7 @@ info: servers: production: - host: wss://wss-primary.slack.com + host: wss-primary.slack.com pathname: /link protocol: wss description: Slack's server in Socket Mode for real-time communication @@ -163,7 +163,7 @@ components: 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` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is a protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, 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. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. ``` channels: @@ -227,7 +227,7 @@ info: servers: production: - host: wss://wss-primary.slack.com + host: wss-primary.slack.com pathname: /link protocol: wss description: Slack's server in Socket Mode for real-time communication From a2023eb8fada46382852d03fbdd1e805358b5803 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 25 Dec 2023 22:12:05 +0530 Subject: [PATCH 19/30] Added codeblocks and removed const description --- pages/docs/tutorials/websocket/index.md | 27 ++++++++++--------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 178e5bfd0992..ce1bde5868a8 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -67,7 +67,7 @@ The `servers` section allows you to define the protocol and specify information The WebSocket URL is generated by invoking the apps.connections.open method from Slack’s API. You use the authentication tokens obtained during the configuration of your Slackbot to generate this URL. -``` + asyncapi: '3.0.0' info: title: Create an AsyncAPI Document for a Slackbot with WebSockets @@ -81,18 +81,15 @@ servers: pathname: /link protocol: wss description: Slack's server in Socket Mode for real-time communication -``` + ## 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. -The `payload` attribute 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 `reaction` 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 `payload` attribute specifies the name, format, and description of all the expected properties. `Heart-Counter` starts the popularity count of a message by validating if the `reaction` property set in the `reaction` schema definition corresponds to "heart". -``` + components: messages: reaction: @@ -141,7 +138,6 @@ components: 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 @@ -157,7 +153,7 @@ components: event_ts: type: string description: Reaction timestamp -``` + ## Define channels and bindings @@ -165,7 +161,7 @@ The `channels` attribute defines a communication channel for the event. The `add The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. -``` + channels: root: address: / @@ -189,7 +185,7 @@ channels: type: string description: Unique identifier assigned to the Slack app const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' -``` + ## Define operations The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how `Heart-Counter` interacts with Slack. @@ -198,7 +194,7 @@ In this example, the `helloListener` operation keeps an eye out for the message 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: helloListener: action: receive @@ -213,11 +209,11 @@ operations: $ref: '#/channels/root' messages: - $ref: '#/channels/root/messages/reaction' -``` + 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: Create an AsyncAPI Document for a Slackbot with WebSockets @@ -319,7 +315,6 @@ components: 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 @@ -335,7 +330,7 @@ components: event_ts: type: string description: Reaction timestamp -``` + From ca05916ac970b630ed9eb704b0de2657dc7284b3 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 25 Dec 2023 22:21:39 +0530 Subject: [PATCH 20/30] Closed code block --- pages/docs/tutorials/websocket/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index ce1bde5868a8..f780e13ad889 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -209,7 +209,7 @@ operations: $ref: '#/channels/root' messages: - $ref: '#/channels/root/messages/reaction' - + You've now completed the tutorial! Putting these blocks together gives you your AsyncAPI document all ready to go. From bc2c0896b189ba874b59adb747a75f7a5b3be9ea Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 25 Dec 2023 22:27:52 +0530 Subject: [PATCH 21/30] Fixed code block typo --- pages/docs/tutorials/websocket/index.md | 209 +++++++++++++----------- 1 file changed, 110 insertions(+), 99 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index f780e13ad889..88cd22846787 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -68,19 +68,22 @@ The WebSocket URL is generated by invoking the +{` asyncapi: '3.0.0' info: title: Create an AsyncAPI Document for a Slackbot with WebSockets version: '1.0.0' description: | The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data - + servers: - production: - host: wss-primary.slack.com - pathname: /link - protocol: wss - description: Slack's server in Socket Mode for real-time communication +production: +host: wss-primary.slack.com +pathname: /link +protocol: wss +description: Slack's server in Socket Mode for real-time communication +`} + ## Define messages and schemas @@ -90,45 +93,46 @@ Your AsyncAPI document needs to be very clear on the type of event it is expecte The `payload` attribute specifies the name, format, and description of all the expected properties. `Heart-Counter` starts the popularity count of a message by validating if the `reaction` property set in the `reaction` schema definition corresponds to "heart". +{` components: messages: reaction: summary: Action triggered when the channel receives a new reaction-added event payload: $ref: '#/components/schemas/reaction' - + hello: summary: Action triggered when a successful WebSocket connection is established payload: $ref: '#/components/schemas/hello' - schemas: - hello: - type: object - properties: - type: - type: string - description: A hello string confirming WebSocket connection - const: "hello" - connection_info: - type: object - properties: - app_id: - type: string - num_connections: - type: integer - debug_info: - type: object - properties: - host: - type: string - started: - type: string - build_number: - type: integer - approximate_connection_time: - type: integer - +schemas: +hello: +type: object +properties: +type: +type: string +description: A hello string confirming WebSocket connection +const: "hello" +connection_info: +type: object +properties: +app_id: +type: string +num_connections: +type: integer +debug_info: +type: object +properties: +host: +type: string +started: +type: string +build_number: +type: integer +approximate_connection_time: +type: integer + reaction: type: object properties: @@ -153,6 +157,7 @@ components: event_ts: type: string description: Reaction timestamp +`} ## Define channels and bindings @@ -162,6 +167,7 @@ The `channels` attribute defines a communication channel for the event. The `add The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. +{` channels: root: address: / @@ -185,6 +191,7 @@ channels: type: string description: Unique identifier assigned to the Slack app const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' +`} ## Define operations @@ -195,6 +202,7 @@ In this example, the `helloListener` operation keeps an eye out for the message 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: helloListener: action: receive @@ -203,39 +211,41 @@ operations: messages: - $ref: '#/channels/root/messages/hello' - reactionListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/reaction' +reactionListener: +action: receive +channel: +$ref: '#/channels/root' +messages: +- $ref: '#/channels/root/messages/reaction' +`} 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: Create an AsyncAPI Document for a Slackbot with WebSockets version: '1.0.0' description: | The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data - + servers: - production: - host: wss-primary.slack.com - pathname: /link - protocol: wss - description: Slack's server in Socket Mode for real-time communication +production: +host: wss-primary.slack.com +pathname: /link +protocol: wss +description: Slack's server in Socket Mode for real-time communication channels: - root: - address: / - messages: - hello: - $ref: '#/components/messages/hello' - reaction: - $ref: '#/components/messages/reaction' +root: +address: / +messages: +hello: +$ref: '#/components/messages/hello' +reaction: +$ref: '#/components/messages/reaction' bindings: ws: @@ -253,59 +263,59 @@ channels: const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' operations: - helloListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/hello' - - reactionListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/reaction' +helloListener: +action: receive +channel: +$ref: '#/channels/root' +messages: +- $ref: '#/channels/root/messages/hello' + +reactionListener: +action: receive +channel: +$ref: '#/channels/root' +messages: +- $ref: '#/channels/root/messages/reaction' components: - messages: - reaction: - summary: Action triggered when the channel receives a new reaction-added event - payload: - $ref: '#/components/schemas/reaction' - +messages: +reaction: +summary: Action triggered when the channel receives a new reaction-added event +payload: +$ref: '#/components/schemas/reaction' + hello: summary: Action triggered when a successful WebSocket connection is established payload: $ref: '#/components/schemas/hello' - schemas: - hello: - type: object - properties: - type: - type: string - description: A hello string confirming WebSocket connection - const: "hello" - connection_info: - type: object - properties: - app_id: - type: string - num_connections: - type: integer - debug_info: - type: object - properties: - host: - type: string - started: - type: string - build_number: - type: integer - approximate_connection_time: - type: integer - +schemas: +hello: +type: object +properties: +type: +type: string +description: A hello string confirming WebSocket connection +const: "hello" +connection_info: +type: object +properties: +app_id: +type: string +num_connections: +type: integer +debug_info: +type: object +properties: +host: +type: string +started: +type: string +build_number: +type: integer +approximate_connection_time: +type: integer + reaction: type: object properties: @@ -330,6 +340,7 @@ components: event_ts: type: string description: Reaction timestamp +`} From dad9b59598e616cc7579b5caf0f0386d7942e598 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 25 Dec 2023 22:43:32 +0530 Subject: [PATCH 22/30] Fixed code block typo --- pages/docs/tutorials/websocket/index.md | 181 ++++++++++++------------ 1 file changed, 90 insertions(+), 91 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 88cd22846787..7ea80289d6fc 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -77,13 +77,12 @@ info: The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data servers: -production: -host: wss-primary.slack.com -pathname: /link -protocol: wss -description: Slack's server in Socket Mode for real-time communication + production: + host: wss-primary.slack.com + pathname: /link + protocol: wss + description: Slack's server in Socket Mode for real-time communication `} - ## Define messages and schemas @@ -106,32 +105,32 @@ components: payload: $ref: '#/components/schemas/hello' -schemas: -hello: -type: object -properties: -type: -type: string -description: A hello string confirming WebSocket connection -const: "hello" -connection_info: -type: object -properties: -app_id: -type: string -num_connections: -type: integer -debug_info: -type: object -properties: -host: -type: string -started: -type: string -build_number: -type: integer -approximate_connection_time: -type: integer + schemas: + hello: + type: object + properties: + type: + type: string + description: A hello string confirming WebSocket connection + const: "hello" + connection_info: + type: object + properties: + app_id: + type: string + num_connections: + type: integer + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer reaction: type: object @@ -212,11 +211,11 @@ operations: - $ref: '#/channels/root/messages/hello' reactionListener: -action: receive -channel: -$ref: '#/channels/root' -messages: -- $ref: '#/channels/root/messages/reaction' + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' `} @@ -232,20 +231,20 @@ info: The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data servers: -production: -host: wss-primary.slack.com -pathname: /link -protocol: wss -description: Slack's server in Socket Mode for real-time communication + production: + host: wss-primary.slack.com + pathname: /link + protocol: wss + description: Slack's server in Socket Mode for real-time communication channels: -root: -address: / -messages: -hello: -$ref: '#/components/messages/hello' -reaction: -$ref: '#/components/messages/reaction' + root: + address: / + messages: + hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' bindings: ws: @@ -263,26 +262,26 @@ $ref: '#/components/messages/reaction' const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' operations: -helloListener: -action: receive -channel: -$ref: '#/channels/root' -messages: -- $ref: '#/channels/root/messages/hello' + helloListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/hello' -reactionListener: -action: receive -channel: -$ref: '#/channels/root' -messages: -- $ref: '#/channels/root/messages/reaction' + reactionListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' components: -messages: -reaction: -summary: Action triggered when the channel receives a new reaction-added event -payload: -$ref: '#/components/schemas/reaction' + messages: + reaction: + summary: Action triggered when the channel receives a new reaction-added event + payload: + $ref: '#/components/schemas/reaction' hello: summary: Action triggered when a successful WebSocket connection is established @@ -290,31 +289,31 @@ $ref: '#/components/schemas/reaction' $ref: '#/components/schemas/hello' schemas: -hello: -type: object -properties: -type: -type: string -description: A hello string confirming WebSocket connection -const: "hello" -connection_info: -type: object -properties: -app_id: -type: string -num_connections: -type: integer -debug_info: -type: object -properties: -host: -type: string -started: -type: string -build_number: -type: integer -approximate_connection_time: -type: integer + hello: + type: object + properties: + type: + type: string + description: A hello string confirming WebSocket connection + const: "hello" + connection_info: + type: object + properties: + app_id: + type: string + num_connections: + type: integer + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer reaction: type: object From 2035171301fa8a02cf8d92c6bdfb6a745d975128 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 25 Dec 2023 22:47:01 +0530 Subject: [PATCH 23/30] Fixed code block typo --- pages/docs/tutorials/websocket/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 7ea80289d6fc..4f0a4b257edb 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -228,8 +228,7 @@ info: title: Create an AsyncAPI Document for a Slackbot with WebSockets version: '1.0.0' description: | - The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data - + The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data. servers: production: host: wss-primary.slack.com From 05ba1b84b77c17621a4abe383baf46cb0a7f898d Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Tue, 26 Dec 2023 11:21:49 +0530 Subject: [PATCH 24/30] Fixed code block typo --- pages/docs/tutorials/websocket/index.md | 412 +++++++++++------------- 1 file changed, 194 insertions(+), 218 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 4f0a4b257edb..291e8a37d16e 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -68,21 +68,18 @@ The WebSocket URL is generated by invoking the -{` -asyncapi: '3.0.0' -info: - title: Create an AsyncAPI Document for a Slackbot with WebSockets - version: '1.0.0' - description: | - The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data - -servers: - production: - host: wss-primary.slack.com - pathname: /link - protocol: wss - description: Slack's server in Socket Mode for real-time communication -`} +{` asyncapi: '3.0.0' + info: + title: Create an AsyncAPI Document for a Slackbot with WebSockets + version: '1.0.0' + description: | + The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data + servers: + production: + host: wss-primary.slack.com + pathname: /link + protocol: wss + description: Slack's server in Socket Mode for real-time communication `} ## Define messages and schemas @@ -92,71 +89,66 @@ Your AsyncAPI document needs to be very clear on the type of event it is expecte The `payload` attribute specifies the name, format, and description of all the expected properties. `Heart-Counter` starts the popularity count of a message by validating if the `reaction` property set in the `reaction` schema definition corresponds to "heart". -{` -components: - messages: - reaction: - summary: Action triggered when the channel receives a new reaction-added event - payload: - $ref: '#/components/schemas/reaction' - - hello: - summary: Action triggered when a successful WebSocket connection is established - payload: - $ref: '#/components/schemas/hello' - - schemas: - hello: - type: object - properties: - type: - type: string - description: A hello string confirming WebSocket connection - const: "hello" - connection_info: - type: object - properties: - app_id: - type: string - num_connections: - type: integer - debug_info: +{` components: + messages: + reaction: + summary: Action triggered when the channel receives a new reaction-added event + payload: + $ref: '#/components/schemas/reaction' + hello: + summary: Action triggered when a successful WebSocket connection is established + payload: + $ref: '#/components/schemas/hello' + schemas: + hello: type: object properties: - host: - type: string - started: - type: string - build_number: - type: integer - approximate_connection_time: - type: integer - - reaction: - type: object - properties: - user: - type: string - description: User ID who performed this event + type: + type: string + description: A hello string confirming WebSocket connection + const: "hello" + connection_info: + type: object + properties: + app_id: + type: string + num_connections: + type: integer + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer reaction: - type: string - description: The only reaction that we need is a heart emoji - item_user: - type: string - description: User ID that created the original item that has been reacted to - item: type: object properties: - channel: + user: + type: string + description: User ID who performed this event + reaction: type: string - description: Channel information of original message - ts: + description: The only reaction that we need is a heart emoji + item_user: type: string - description: Timestamp information of original message - event_ts: - type: string - description: Reaction timestamp -`} + 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 `} ## Define channels and bindings @@ -166,31 +158,28 @@ The `channels` attribute defines a communication channel for the event. The `add The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. -{` -channels: - root: - address: / - messages: - hello: - $ref: '#/components/messages/hello' - reaction: - $ref: '#/components/messages/reaction' - - bindings: - ws: - query: - type: object - description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API - properties: - ticket: - type: string - description: Temporary token generated when connection is initiated - const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' - app_id: - type: string - description: Unique identifier assigned to the Slack app - const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' -`} +{` channels: + root: + address: / + messages: + hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' + bindings: + ws: + query: + type: object + description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API + properties: + ticket: + type: string + description: Temporary token generated when connection is initiated + const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' + app_id: + type: string + description: Unique identifier assigned to the Slack app + const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' `} ## Define operations @@ -201,144 +190,131 @@ In this example, the `helloListener` operation keeps an eye out for the message 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: - helloListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/hello' - -reactionListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/reaction' -`} +{` operations: + helloListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/hello' + reactionListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' `} 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: Create an AsyncAPI Document for a Slackbot with WebSockets - version: '1.0.0' - description: | - The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data. -servers: - production: - host: wss-primary.slack.com - pathname: /link - protocol: wss - description: Slack's server in Socket Mode for real-time communication - -channels: - root: - address: / - messages: +{` asyncapi: '3.0.0' + info: + title: Create an AsyncAPI Document for a Slackbot with WebSockets + version: '1.0.0' + description: | + The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data. + servers: + production: + host: wss-primary.slack.com + pathname: /link + protocol: wss + description: Slack's server in Socket Mode for real-time communication + channels: + root: + address: / + messages: + hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' + bindings: + ws: + query: + type: object + description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API + properties: + ticket: + type: string + description: Temporary token generated when connection is initiated + const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' + app_id: + type: string + description: Unique identifier assigned to the Slack app + const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' + operations: + helloListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/hello' + reactionListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' + components: + messages: + reaction: + summary: Action triggered when the channel receives a new reaction-added event + payload: + $ref: '#/components/schemas/reaction' + hello: + summary: Action triggered when a successful WebSocket connection is established + payload: + $ref: '#/components/schemas/hello' + schemas: hello: - $ref: '#/components/messages/hello' - reaction: - $ref: '#/components/messages/reaction' - - bindings: - ws: - query: - type: object - description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API - properties: - ticket: - type: string - description: Temporary token generated when connection is initiated - const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' - app_id: - type: string - description: Unique identifier assigned to the Slack app - const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' - -operations: - helloListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/hello' - - reactionListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/reaction' - -components: - messages: - reaction: - summary: Action triggered when the channel receives a new reaction-added event - payload: - $ref: '#/components/schemas/reaction' - - hello: - summary: Action triggered when a successful WebSocket connection is established - payload: - $ref: '#/components/schemas/hello' - -schemas: - hello: - type: object - properties: - type: - type: string - description: A hello string confirming WebSocket connection - const: "hello" - connection_info: type: object properties: - app_id: + type: type: string - num_connections: - type: integer - debug_info: + description: A hello string confirming WebSocket connection + const: "hello" + connection_info: type: object properties: - host: - type: string - started: + app_id: type: string - build_number: - type: integer - approximate_connection_time: + num_connections: type: integer - - reaction: - type: object - properties: - user: - type: string - description: User ID who performed this event + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer reaction: - type: string - description: The only reaction that we need is a heart emoji - item_user: - type: string - description: User ID that created the original item that has been reacted to - item: type: object properties: - channel: + user: + type: string + description: User ID who performed this event + reaction: + type: string + description: The only reaction that we need is a heart emoji + item_user: type: string - description: Channel information of original message - ts: + 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: Timestamp information of original message - event_ts: - type: string - description: Reaction timestamp -`} + description: Reaction timestamp `} From c2b66d86741f064bb2fd0e6452e9739d50defb58 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Tue, 26 Dec 2023 11:33:08 +0530 Subject: [PATCH 25/30] Fix indentation --- pages/docs/tutorials/websocket/index.md | 213 ++++++++++++------------ 1 file changed, 106 insertions(+), 107 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 291e8a37d16e..36b21efde716 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -68,18 +68,18 @@ The WebSocket URL is generated by invoking the -{` asyncapi: '3.0.0' - info: - title: Create an AsyncAPI Document for a Slackbot with WebSockets - version: '1.0.0' - description: | - The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data - servers: - production: - host: wss-primary.slack.com - pathname: /link - protocol: wss - description: Slack's server in Socket Mode for real-time communication `} +{`asyncapi: '3.0.0' +info: + title: Create an AsyncAPI Document for a Slackbot with WebSockets + version: '1.0.0' + description: | + The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data +servers: + production: + host: wss-primary.slack.com + pathname: /link + protocol: wss + description: Slack's server in Socket Mode for real-time communication `} ## Define messages and schemas @@ -106,7 +106,6 @@ The `payload` attribute specifies the name, format, and description of all the e type: type: string description: A hello string confirming WebSocket connection - const: "hello" connection_info: type: object properties: @@ -208,113 +207,113 @@ Your Slack application is designed to be notified of events within your workspac 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: Create an AsyncAPI Document for a Slackbot with WebSockets - version: '1.0.0' - description: | - The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data. - servers: - production: - host: wss-primary.slack.com - pathname: /link - protocol: wss - description: Slack's server in Socket Mode for real-time communication - channels: - root: - address: / - messages: - hello: - $ref: '#/components/messages/hello' - reaction: - $ref: '#/components/messages/reaction' - bindings: - ws: - query: - type: object - description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API - properties: - ticket: - type: string - description: Temporary token generated when connection is initiated - const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' - app_id: - type: string - description: Unique identifier assigned to the Slack app - const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' - operations: - helloListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/hello' - reactionListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/reaction' - components: - messages: - reaction: - summary: Action triggered when the channel receives a new reaction-added event - payload: - $ref: '#/components/schemas/reaction' - hello: - summary: Action triggered when a successful WebSocket connection is established - payload: - $ref: '#/components/schemas/hello' - schemas: +{` +asyncapi: '3.0.0' +info: + title: Create an AsyncAPI Document for a Slackbot with WebSockets + version: '1.0.0' + description: | + The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data. +servers: + production: + host: wss-primary.slack.com + pathname: /link + protocol: wss + description: Slack's server in Socket Mode for real-time communication +channels: + root: + address: / + messages: hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' + bindings: + ws: + query: + type: object + description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API + properties: + ticket: + type: string + description: Temporary token generated when connection is initiated + const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' + app_id: + type: string + description: Unique identifier assigned to the Slack app + const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' +operations: + helloListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/hello' + reactionListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' +components: + messages: + reaction: + summary: Action triggered when the channel receives a new reaction-added event + payload: + $ref: '#/components/schemas/reaction' + hello: + summary: Action triggered when a successful WebSocket connection is established + payload: + $ref: '#/components/schemas/hello' +schemas: + hello: + type: object + properties: + type: + type: string + description: A hello string confirming WebSocket connection + connection_info: type: object properties: - type: + app_id: type: string - description: A hello string confirming WebSocket connection - const: "hello" - connection_info: + num_connections: + type: integer + debug_info: type: object properties: - app_id: + host: + type: string + started: type: string - num_connections: + build_number: + type: integer + approximate_connection_time: type: integer - debug_info: - type: object - properties: - host: - type: string - started: - type: string - build_number: - type: integer - approximate_connection_time: - type: integer + reaction: + 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 + item_user: + type: string + description: User ID that created the original item that has been reacted to + item: type: object properties: - user: + channel: type: string - description: User ID who performed this event - reaction: - type: string - description: The only reaction that we need is a heart emoji - 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: + description: Channel information of original message + ts: type: string - description: Reaction timestamp `} + description: Timestamp information of original message + event_ts: + type: string + description: Reaction timestamp `} From 2e5952762be595dbd696eddcb8df1eaa14d64fd5 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Tue, 26 Dec 2023 11:38:26 +0530 Subject: [PATCH 26/30] Fix indentation --- pages/docs/tutorials/websocket/index.md | 175 ++++++++++++------------ 1 file changed, 87 insertions(+), 88 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 36b21efde716..b5d1c4480925 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -89,65 +89,65 @@ Your AsyncAPI document needs to be very clear on the type of event it is expecte The `payload` attribute specifies the name, format, and description of all the expected properties. `Heart-Counter` starts the popularity count of a message by validating if the `reaction` property set in the `reaction` schema definition corresponds to "heart". -{` components: - messages: +{`components: + messages: + reaction: + summary: Action triggered when the channel receives a new reaction-added event + payload: + $ref: '#/components/schemas/reaction' + hello: + summary: Action triggered when a successful WebSocket connection is established + payload: + $ref: '#/components/schemas/hello' + schemas: + hello: + type: object + properties: + type: + type: string + description: A hello string confirming WebSocket connection + connection_info: + type: object + properties: + app_id: + type: string + num_connections: + type: integer + debug_info: + type: object + properties: + host: + type: string + started: + type: string + build_number: + type: integer + approximate_connection_time: + type: integer reaction: - summary: Action triggered when the channel receives a new reaction-added event - payload: - $ref: '#/components/schemas/reaction' - hello: - summary: Action triggered when a successful WebSocket connection is established - payload: - $ref: '#/components/schemas/hello' - schemas: - hello: type: object properties: - type: + user: type: string - description: A hello string confirming WebSocket connection - connection_info: - type: object - properties: - app_id: - type: string - num_connections: - type: integer - debug_info: + description: User ID who performed this event + reaction: + type: string + description: The only reaction that we need is a heart emoji + item_user: + type: string + description: User ID that created the original item that has been reacted to + item: type: object properties: - host: + channel: type: string - started: + description: Channel information of original message + ts: type: string - build_number: - type: integer - approximate_connection_time: - type: integer - reaction: - 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 - 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 `} + description: Timestamp information of original message + event_ts: + type: string + description: Reaction timestamp `} ## Define channels and bindings @@ -157,28 +157,28 @@ The `channels` attribute defines a communication channel for the event. The `add The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. -{` channels: - root: - address: / - messages: - hello: - $ref: '#/components/messages/hello' - reaction: - $ref: '#/components/messages/reaction' - bindings: - ws: - query: - type: object - description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API - properties: - ticket: - type: string - description: Temporary token generated when connection is initiated - const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' - app_id: - type: string - description: Unique identifier assigned to the Slack app - const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' `} +{`channels: + root: + address: / + messages: + hello: + $ref: '#/components/messages/hello' + reaction: + $ref: '#/components/messages/reaction' + bindings: + ws: + query: + type: object + description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API + properties: + ticket: + type: string + description: Temporary token generated when connection is initiated + const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f' + app_id: + type: string + description: Unique identifier assigned to the Slack app + const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' `} ## Define operations @@ -189,26 +189,25 @@ In this example, the `helloListener` operation keeps an eye out for the message 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: - helloListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/hello' - reactionListener: - action: receive - channel: - $ref: '#/channels/root' - messages: - - $ref: '#/channels/root/messages/reaction' `} +{`operations: + helloListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/hello' + reactionListener: + action: receive + channel: + $ref: '#/channels/root' + messages: + - $ref: '#/channels/root/messages/reaction' `} You've now completed the tutorial! Putting these blocks together gives you your AsyncAPI document all ready to go. -{` -asyncapi: '3.0.0' +{`asyncapi: '3.0.0' info: title: Create an AsyncAPI Document for a Slackbot with WebSockets version: '1.0.0' From 014be36f38009324a896defd5a4b3ea8adcd4b9d Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 15 Jan 2024 19:41:44 +0530 Subject: [PATCH 27/30] Added highlighted code --- pages/docs/tutorials/websocket/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index b5d1c4480925..936fd6c359e8 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -88,7 +88,7 @@ Your AsyncAPI document needs to be very clear on the type of event it is expecte The `payload` attribute specifies the name, format, and description of all the expected properties. `Heart-Counter` starts the popularity count of a message by validating if the `reaction` property set in the `reaction` schema definition corresponds to "heart". - + {`components: messages: reaction: @@ -188,7 +188,7 @@ In this example, the `helloListener` operation keeps an eye out for the message 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: helloListener: action: receive From 09b0df6cd49ff682cb8c471f2f2e5a5163144b95 Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 15 Jan 2024 19:46:19 +0530 Subject: [PATCH 28/30] Added highlighted code --- pages/docs/tutorials/websocket/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 936fd6c359e8..74f2c5eb5374 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -156,7 +156,7 @@ The `channels` attribute defines a communication channel for the event. The `add The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. - + {`channels: root: address: / From cd3ab4f3f4c1f0c0af44b641e912ef3720dbefec Mon Sep 17 00:00:00 2001 From: VaishnaviNandakumar Date: Mon, 15 Jan 2024 19:52:18 +0530 Subject: [PATCH 29/30] Added highlighted code --- pages/docs/tutorials/websocket/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index 74f2c5eb5374..bbdc01b429e6 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -156,7 +156,7 @@ The `channels` attribute defines a communication channel for the event. The `add The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. - + {`channels: root: address: / From d3054370ecb3258b4c88f96f16eed940db229b7a Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 6 Feb 2024 18:03:12 -0800 Subject: [PATCH 30/30] editorial fixes --- pages/docs/tutorials/websocket/index.md | 30 ++++++++++++------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/pages/docs/tutorials/websocket/index.md b/pages/docs/tutorials/websocket/index.md index bbdc01b429e6..ef5c049f6509 100644 --- a/pages/docs/tutorials/websocket/index.md +++ b/pages/docs/tutorials/websocket/index.md @@ -1,15 +1,15 @@ --- -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. +title: Create an AsyncAPI document for a Slackbot with WebSocket. +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 WebSocket protocol. weight: 210 --- ## Introduction -In this tutorial, you will learn how to write 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. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a WebSocket server. You will also learn why the AsyncAPI bindings feature exist and how to use it. +In this tutorial, you will learn how to write 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. You will learn how to write an AsyncAPI document for a consumer-only application receiving a stream of messages from a WebSocket server. You will also learn why the AsyncAPI bindings feature exists and how to use it. -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. +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 channels, but doing this manually would be difficult. To simplify this process, you will build a Slackbot called `Heart-Counter` that actively monitors reactions added to a message and determines its popularity by counting the reactions of the “heart” emoji. -Here’s a visual representation of how `Heart-Counter` should work: +Here’s a visual representation of how the `Heart-Counter` should work: ```mermaid sequenceDiagram @@ -42,7 +42,7 @@ Note left of Heart-Counter: Event received ``` ## Background context -[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. +[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 @@ -59,9 +59,9 @@ In Slack, WebSocket is employed as part of its [Socket Mode](https://api.slack.c ## 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`. +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 `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`. +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`. The WebSocket URL is generated by invoking the apps.connections.open method from Slack’s API. You use the authentication tokens obtained during the configuration of your Slackbot to generate this URL. @@ -70,7 +70,7 @@ The WebSocket URL is generated by invoking the {`asyncapi: '3.0.0' info: - title: Create an AsyncAPI Document for a Slackbot with WebSockets + title: Create an AsyncAPI document for a Slackbot with WebSocket version: '1.0.0' description: | The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data @@ -154,7 +154,7 @@ The `payload` attribute specifies the name, format, and description of all the e 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` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, 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. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and partially to WebSocket, which uses HTTP to connect client and server. Since this is protocol-specific information, you must use an AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside the AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. {`channels: @@ -182,11 +182,11 @@ The WebSocket URL generated for `Heart-Counter` includes authentication tokens. ## Define operations -The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how `Heart-Counter` interacts with Slack. +The `operation` property is all about defining specific tasks your application can perform. Essentially, it's how the `Heart-Counter` interacts with Slack. In this example, the `helloListener` operation 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. +Your Slack application is designed to be notified of events within your workspace. It subscribes to a specific event type and uses Slack's Event API. In this case, both operations' `action` property is set to `receive` events. {`operations: @@ -204,12 +204,12 @@ Your Slack application is designed to be notified of events within your workspac - $ref: '#/channels/root/messages/reaction' `} -You've now completed the tutorial! Putting these blocks together gives you your AsyncAPI document all ready to go. +Congratulations, you've completed the tutorial! Putting these blocks together gives you an AsyncAPI document all ready to go. {`asyncapi: '3.0.0' info: - title: Create an AsyncAPI Document for a Slackbot with WebSockets + title: Create an AsyncAPI document for a Slackbot with WebSocket version: '1.0.0' description: | The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data. @@ -318,4 +318,4 @@ schemas: ## 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 facilitate bidirectional real-time data exchange, such as chatbots and live-streaming platforms.