slackapi · seratch · Jan 12, 2021 · Nov 22, 2020 · Dec 2, 2020 · Dec 3, 2020
@@ -9,7 +9,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     timeout-minutes: 10
     strategy:
       matrix:
@@ -25,7 +25,7 @@ jobs:
       run: |
         pip install -U pip wheel
         pip install -e ".[testing]"
-        pip install "aiohttp>=3,<4"
+        pip install -e ".[optional]"
     - name: Run validation
       run: |
         python setup.py validate

@@ -17,6 +17,7 @@ The **Python Slack SDK** allows interaction with:
 - `slack_sdk.web`: for calling the Slack Web API methods ([API Docs site][api-methods])
 - `slack_sdk.webhook`: for utilizing the Incoming Webhooks and `response_url`s in payloads
 - `slack_sdk.signature`: for verifying incoming requests from the Slack API server
+- `slack_sdk.socket_mode`: for receiving and sending messages over [Socket Mode](https://api.slack.com/socket-mode) connections
 - `slack_sdk.oauth`: for implementing the Slack OAuth flow
 - `slack_sdk.models`: for constructing UI components using easy-to-use builders
 - `slack_sdk.rtm`: for utilizing the [RTM API][rtm-docs]

@@ -2,7 +2,7 @@ coverage:
   status:
     project:
       default:
-        threshold: 0.3%
+        threshold: 2.0%
     patch:
       default:
         target: 50%
@@ -6,6 +6,7 @@
      installation/index
      web/index
      webhook/index
+     socket-mode/index
      oauth/index
      real_time_messaging
      faq
@@ -26,6 +27,8 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa
 | Webhooks / response_url        | Send a message using Incoming Webhooks or response_url                                        | ``slack_sdk.webhook``              |
 |                                |                                                                                               | ``slack_sdk.webhook.async_client`` |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
+| Socket Mode                    | Receive and send messages over Socket Mode connections.                                       | ``slack_sdk.socket_mode``          |
++--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
 | OAuth                          | Setup the authentication flow using V2 OAuth for Slack apps.                                  | ``slack_sdk.oauth``                |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
 | RTM API                        | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | ``slack_sdk.rtm```                 |

@@ -0,0 +1,149 @@
+==============================================
+Socket Mode Client
+==============================================
+
+Socket Mode is a method of connecting your app to Slack’s APIs using WebSockets instead of HTTP. You can use  ``slack_sdk.socket_mode.SocketModeClient`` for managing `Socket Mode <https://api.slack.com/socket-mode>`_ connections and performing interactions with Slack.
+
+SocketModeClient
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First off, let's start with enabling Socket Mode. Visit `the Slack App configuration page <http://api.slack.com/apps>`_, choose the app you're working on, and go to **Settings** on the left pane. There are a few things to do on the page.
+
+* Go to **Settings** > **Basic Information**, then add a new **App-Level Token** with the `connections:write` scope
+* Go to **Settings** > **Socket Mode**, then turn on **Enable Socket Mode**
+
+You will be using the app-level token that starts with ``xapp-`` prefix. Note that the token here is not the ones starting with either ``xoxb-`` or ``xoxp-``.
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.web import WebClient
+    from slack_sdk.socket_mode import SocketModeClient
+
+    # Initialize SocketModeClient with an app-level token + WebClient
+    client = SocketModeClient(
+        # This app-level token will be used only for establishing a connection
+        app_token=os.environ.get("SLACK_APP_TOKEN"),  # xapp-A111-222-xyz
+        # You will be using this WebClient for performing Web API calls in listeners
+        web_client=WebClient(token=os.environ.get("SLACK_BOT_TOKEN"))  # xoxb-111-222-xyz
+    )
+
+    from slack_sdk.socket_mode.response import SocketModeResponse
+    from slack_sdk.socket_mode.request import SocketModeRequest
+
+    def process(client: SocketModeClient, req: SocketModeRequest):
+        if req.type == "events_api":
+            # Acknowledge the request anyway
+            response = SocketModeResponse(envelope_id=req.envelope_id)
+            client.send_socket_mode_response(response)
+
+            # Add a reaction to the message if it's a new message
+            if req.payload["event"]["type"] == "message" \
+                and req.payload["event"].get("subtype") is None:
+                client.web_client.reactions_add(
+                    name="eyes",
+                    channel=req.payload["event"]["channel"],
+                    timestamp=req.payload["event"]["ts"],
+                )
+
+    # Add a new listener to receive messages from Slack
+    # You can add more listeners like this
+    client.socket_mode_request_listeners.append(process)
+    # Establish a WebSocket connection to the Socket Mode servers
+    client.connect()
+    # Just not to stop this process
+    from threading import Event
+    Event().wait()
+
+--------
+
+Supported Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This SDK offers its own simple WebSocket client covering only required features for Socket Mode. In addition to that, ``SocketModeClient`` is implemented with a few 3rd party open-source libraries. If you prefer any of the following, you can use it over the built-in one.
+
+.. list-table::
+   :header-rows: 1
+
+   * - PyPI Project
+     - SocketModeClient
+   * - `slack_sdk <https://pypi.org/project/slack-sdk/>`_
+     - `slack_sdk.socket_mode.SocketModeClient <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/socket_mode/builtin/client.py>`_
+   * - `websocket_client <https://pypi.org/project/websocket_client/>`_
+     - `slack_sdk.socket_mode.websocket_client.SocketModeClient <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/socket_mode/websocket_client/client.py>`_
+   * - `aiohttp <https://pypi.org/project/aiohttp/>`_ (asyncio-based)
+     - `slack_sdk.socket_mode.aiohttp.SocketModeClient <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/socket_mode/aiohttp/client.py>`_
+   * - `websockets <https://pypi.org/project/websockets/>`_ (asyncio-based)
+     - `slack_sdk.socket_mode.websockets.SocketModeClient <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/socket_mode/websockets/client.py>`_
+
+
+To use the `websocket_client <https://pypi.org/project/websocket_client/>`_ based one, all you need to do are to add `websocket_client <https://pypi.org/project/websocket_client/>`_ dependency and to change the import as below.
+
+.. code-block:: python
+
+    # Note that the pockage is different
+    from slack_sdk.socket_mode.websocket_client import SocketModeClient
+
+    client = SocketModeClient(
+        app_token=os.environ.get("SLACK_APP_TOKEN"),  # xapp-A111-222-xyz
+        web_client=WebClient(token=os.environ.get("SLACK_BOT_TOKEN"))  # xoxb-111-222-xyz
+    )
+
+You can pass a few additional arguments that are specific to the library. Apart from that, all the functionalities work in the same way with the built-in version.
+
+--------
+
+Asyncio Based Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use the asyncio-based ones such as aiohttp, your app needs to be compatible with asyncio's async/await programming model. The `SocketModeClient` only works with `AsyncWebClient` and async listeners.
+
+.. code-block:: python
+
+    import asyncio
+    import os
+    from slack_sdk.web.async_client import AsyncWebClient
+    from slack_sdk.socket_mode.aiohttp import SocketModeClient
+
+    # Initialize SocketModeClient with an app-level token + AsyncWebClient
+    client = SocketModeClient(
+        # This app-level token will be used only for establishing a connection
+        app_token=os.environ.get("SLACK_APP_TOKEN"),  # xapp-A111-222-xyz
+        # You will be using this AsyncWebClient for performing Web API calls in listeners
+        web_client=AsyncWebClient(token=os.environ.get("SLACK_BOT_TOKEN"))  # xoxb-111-222-xyz
+    )
+
+    # Use async method
+    async def main():
+        from slack_sdk.socket_mode.response import SocketModeResponse
+        from slack_sdk.socket_mode.request import SocketModeRequest
+
+        # Use async method
+        async def process(client: SocketModeClient, req: SocketModeRequest):
+            if req.type == "events_api":
+                # Acknowledge the request anyway
+                response = SocketModeResponse(envelope_id=req.envelope_id)
+                # Don't forget having await for method calls
+                await client.send_socket_mode_response(response)
+
+                # Add a reaction to the message if it's a new message
+                if req.payload["event"]["type"] == "message" \
+                    and req.payload["event"].get("subtype") is None:
+                    await client.web_client.reactions_add(
+                        name="eyes",
+                        channel=req.payload["event"]["channel"],
+                        timestamp=req.payload["event"]["ts"],
+                    )
+
+        # Add a new listener to receive messages from Slack
+        # You can add more listeners like this
+        client.socket_mode_request_listeners.append(process)
+        # Establish a WebSocket connection to the Socket Mode servers
+        await client.connect()
+        # Just not to stop this process
+        await asyncio.sleep(float("inf"))
+
+    # You can go with other way to run it. This is just for easiness to try it out.
+    asyncio.run(main())
+
+.. include:: ../metadata.rst
@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>
@@ -215,19 +221,23 @@ <h1>Python Slack SDK<a class="headerlink" href="#product-name" title="Permalink
 <td><p><code class="docutils literal notranslate"><span class="pre">slack_sdk.webhook</span></code>
 <code class="docutils literal notranslate"><span class="pre">slack_sdk.webhook.async_client</span></code></p></td>
 </tr>
-<tr class="row-even"><td><p>OAuth</p></td>
+<tr class="row-even"><td><p>Socket Mode</p></td>
+<td><p>Receive and send messages over Socket Mode connections.</p></td>
+<td><p><code class="docutils literal notranslate"><span class="pre">slack_sdk.socket_mode</span></code></p></td>
+</tr>
+<tr class="row-odd"><td><p>OAuth</p></td>
 <td><p>Setup the authentication flow using V2 OAuth for Slack apps.</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">slack_sdk.oauth</span></code></p></td>
 </tr>
-<tr class="row-odd"><td><p>RTM API</p></td>
+<tr class="row-even"><td><p>RTM API</p></td>
 <td><p>Listen for incoming messages and a limited set of events happening in Slack, using WebSocket.</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">slack_sdk.rtm`</span></code></p></td>
 </tr>
-<tr class="row-even"><td><p>Request Signature Verification</p></td>
+<tr class="row-odd"><td><p>Request Signature Verification</p></td>
 <td><p>Verify incoming requests from the Slack API servers.</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">slack_sdk.signature</span></code></p></td>
 </tr>
-<tr class="row-odd"><td><p>UI Builders</p></td>
+<tr class="row-even"><td><p>UI Builders</p></td>
 <td><p>Construct UI components using easy-to-use builders.</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">slack_sdk.models</span></code></p></td>
 </tr>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="../webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="../socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="../socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="../oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="../oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../oauth/index.html#token-lookup">Token Lookup</a></li>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="../webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="../socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="../socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#token-lookup">Token Lookup</a></li>

@@ -143,6 +143,12 @@
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#socketmodeclient">SocketModeClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#supported-libraries">Supported Libraries</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socket-mode/index.html#asyncio-based-libraries">Asyncio Based Libraries</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>