WebSockets

Warning

The current page still doesn’t have a translation for this language.

But you can help translating it: Contributing.

You can use WebSockets with FastAPI.

Install WebSockets

First you need to install WebSockets:

WebSockets - 图1

WebSockets client

In production

In your production system, you probably have a frontend created with a modern framework like React, Vue.js or Angular.

And to communicate using WebSockets with your backend you would probably use your frontend’s utilities.

Or you might have a native mobile application that communicates with your WebSocket backend directly, in native code.

Or you might have any other way to communicate with the WebSocket endpoint.

But for this example, we’ll use a very simple HTML document with some JavaScript, all inside a long string.

This, of course, is not optimal and you wouldn’t use it for production.

In production you would have one of the options above.

But it’s the simplest way to focus on the server-side of WebSockets and have a working example:

  1. from fastapi import FastAPI, WebSocket
  2. from fastapi.responses import HTMLResponse
  4. app = FastAPI()
  6. html = """
  7. <!DOCTYPE html>
  8. <html>
  9.     <head>
  10.         <title>Chat</title>
  11.     </head>
  12.     <body>
  13.         <h1>WebSocket Chat</h1>
  14.         <form action="" onsubmit="sendMessage(event)">
  15.             <input type="text" id="messageText" autocomplete="off"/>
  16.             <button>Send</button>
  17.         </form>
  18.         <ul id='messages'>
  19.         </ul>
  20.         <script>
  21.             var ws = new WebSocket("ws://localhost:8000/ws");
  22.             ws.onmessage = function(event) {
  23.                 var messages = document.getElementById('messages')
  24.                 var message = document.createElement('li')
  25.                 var content = document.createTextNode(event.data)
  26.                 message.appendChild(content)
  27.                 messages.appendChild(message)
  28.             };
  29.             function sendMessage(event) {
  30.                 var input = document.getElementById("messageText")
  31.                 ws.send(input.value)
  32.                 input.value = ''
  33.                 event.preventDefault()
  34.             }
  35.         </script>
  36.     </body>
  37. </html>
  38. """
  41. @app.get("/")
  42. async def get():
  43.     return HTMLResponse(html)
  46. @app.websocket("/ws")
  47. async def websocket_endpoint(websocket: WebSocket):
  48.     await websocket.accept()
  49.     while True:
  50.         data = await websocket.receive_text()
  51.         await websocket.send_text(f"Message text was: {data}")

Create a websocket

In your FastAPI application, create a websocket:

  1. from fastapi import FastAPI, WebSocket
  2. from fastapi.responses import HTMLResponse
  4. app = FastAPI()
  6. html = """
  7. <!DOCTYPE html>
  8. <html>
  9.     <head>
  10.         <title>Chat</title>
  11.     </head>
  12.     <body>
  13.         <h1>WebSocket Chat</h1>
  14.         <form action="" onsubmit="sendMessage(event)">
  15.             <input type="text" id="messageText" autocomplete="off"/>
  16.             <button>Send</button>
  17.         </form>
  18.         <ul id='messages'>
  19.         </ul>
  20.         <script>
  21.             var ws = new WebSocket("ws://localhost:8000/ws");
  22.             ws.onmessage = function(event) {
  23.                 var messages = document.getElementById('messages')
  24.                 var message = document.createElement('li')
  25.                 var content = document.createTextNode(event.data)
  26.                 message.appendChild(content)
  27.                 messages.appendChild(message)
  28.             };
  29.             function sendMessage(event) {
  30.                 var input = document.getElementById("messageText")
  31.                 ws.send(input.value)
  32.                 input.value = ''
  33.                 event.preventDefault()
  34.             }
  35.         </script>
  36.     </body>
  37. </html>
  38. """
  41. @app.get("/")
  42. async def get():
  43.     return HTMLResponse(html)
  46. @app.websocket("/ws")
  47. async def websocket_endpoint(websocket: WebSocket):
  48.     await websocket.accept()
  49.     while True:
  50.         data = await websocket.receive_text()
  51.         await websocket.send_text(f"Message text was: {data}")

Technical Details

You could also use from starlette.websockets import WebSocket.

FastAPI provides the same WebSocket directly just as a convenience for you, the developer. But it comes directly from Starlette.

Await for messages and send messages

In your WebSocket route you can await for messages and send messages.

  1. from fastapi import FastAPI, WebSocket
  2. from fastapi.responses import HTMLResponse
  4. app = FastAPI()
  6. html = """
  7. <!DOCTYPE html>
  8. <html>
  9.     <head>
  10.         <title>Chat</title>
  11.     </head>
  12.     <body>
  13.         <h1>WebSocket Chat</h1>
  14.         <form action="" onsubmit="sendMessage(event)">
  15.             <input type="text" id="messageText" autocomplete="off"/>
  16.             <button>Send</button>
  17.         </form>
  18.         <ul id='messages'>
  19.         </ul>
  20.         <script>
  21.             var ws = new WebSocket("ws://localhost:8000/ws");
  22.             ws.onmessage = function(event) {
  23.                 var messages = document.getElementById('messages')
  24.                 var message = document.createElement('li')
  25.                 var content = document.createTextNode(event.data)
  26.                 message.appendChild(content)
  27.                 messages.appendChild(message)
  28.             };
  29.             function sendMessage(event) {
  30.                 var input = document.getElementById("messageText")
  31.                 ws.send(input.value)
  32.                 input.value = ''
  33.                 event.preventDefault()
  34.             }
  35.         </script>
  36.     </body>
  37. </html>
  38. """
  41. @app.get("/")
  42. async def get():
  43.     return HTMLResponse(html)
  46. @app.websocket("/ws")
  47. async def websocket_endpoint(websocket: WebSocket):
  48.     await websocket.accept()
  49.     while True:
  50.         data = await websocket.receive_text()
  51.         await websocket.send_text(f"Message text was: {data}")

You can receive and send binary, text, and JSON data.

Try it

If your file is named main.py, run your application with:

WebSockets - 图2

Open your browser at http://127.0.0.1:8000.

You will see a simple page like:

WebSockets - 图3

You can type messages in the input box, and send them:

WebSockets - 图4

And your FastAPI application with WebSockets will respond back:

WebSockets - 图5

You can send (and receive) many messages:

WebSockets - 图6

And all of them will use the same WebSocket connection.

Using Depends and others

In WebSocket endpoints you can import from fastapi and use:

  • Depends
  • Security
  • Cookie
  • Header
  • Path
  • Query

They work the same way as for other FastAPI endpoints/path operations:

Python 3.9+Python 3.6+Python 3.10+ non-AnnotatedPython 3.6+ non-Annotated

  1. from typing import Annotated
  3. from fastapi import (
  4.     Cookie,
  5.     Depends,
  6.     FastAPI,
  7.     Query,
  8.     WebSocket,
  9.     WebSocketException,
  10.     status,
  11. )
  12. from fastapi.responses import HTMLResponse
  14. app = FastAPI()
  16. html = """
  17. <!DOCTYPE html>
  18. <html>
  19.     <head>
  20.         <title>Chat</title>
  21.     </head>
  22.     <body>
  23.         <h1>WebSocket Chat</h1>
  24.         <form action="" onsubmit="sendMessage(event)">
  25.             <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
  26.             <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
  27.             <button onclick="connect(event)">Connect</button>
  28.             <hr>
  29.             <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
  30.             <button>Send</button>
  31.         </form>
  32.         <ul id='messages'>
  33.         </ul>
  34.         <script>
  35.         var ws = null;
  36.             function connect(event) {
  37.                 var itemId = document.getElementById("itemId")
  38.                 var token = document.getElementById("token")
  39.                 ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
  40.                 ws.onmessage = function(event) {
  41.                     var messages = document.getElementById('messages')
  42.                     var message = document.createElement('li')
  43.                     var content = document.createTextNode(event.data)
  44.                     message.appendChild(content)
  45.                     messages.appendChild(message)
  46.                 };
  47.                 event.preventDefault()
  48.             }
  49.             function sendMessage(event) {
  50.                 var input = document.getElementById("messageText")
  51.                 ws.send(input.value)
  52.                 input.value = ''
  53.                 event.preventDefault()
  54.             }
  55.         </script>
  56.     </body>
  57. </html>
  58. """
  61. @app.get("/")
  62. async def get():
  63.     return HTMLResponse(html)
  66. async def get_cookie_or_token(
  67.     websocket: WebSocket,
  68.     session: Annotated[str | None, Cookie()] = None,
  69.     token: Annotated[str | None, Query()] = None,
  70. ):
  71.     if session is None and token is None:
  72.         raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
  73.     return session or token
  76. @app.websocket("/items/{item_id}/ws")
  77. async def websocket_endpoint(
  78.     *,
  79.     websocket: WebSocket,
  80.     item_id: str,
  81.     q: int | None = None,
  82.     cookie_or_token: Annotated[str, Depends(get_cookie_or_token)],
  83. ):
  84.     await websocket.accept()
  85.     while True:
  86.         data = await websocket.receive_text()
  87.         await websocket.send_text(
  88.             f"Session cookie or query token value is: {cookie_or_token}"
  89.         )
  90.         if q is not None:
  91.             await websocket.send_text(f"Query parameter q is: {q}")
  92.         await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
  1. from typing import Annotated, Union
  3. from fastapi import (
  4.     Cookie,
  5.     Depends,
  6.     FastAPI,
  7.     Query,
  8.     WebSocket,
  9.     WebSocketException,
  10.     status,
  11. )
  12. from fastapi.responses import HTMLResponse
  14. app = FastAPI()
  16. html = """
  17. <!DOCTYPE html>
  18. <html>
  19.     <head>
  20.         <title>Chat</title>
  21.     </head>
  22.     <body>
  23.         <h1>WebSocket Chat</h1>
  24.         <form action="" onsubmit="sendMessage(event)">
  25.             <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
  26.             <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
  27.             <button onclick="connect(event)">Connect</button>
  28.             <hr>
  29.             <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
  30.             <button>Send</button>
  31.         </form>
  32.         <ul id='messages'>
  33.         </ul>
  34.         <script>
  35.         var ws = null;
  36.             function connect(event) {
  37.                 var itemId = document.getElementById("itemId")
  38.                 var token = document.getElementById("token")
  39.                 ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
  40.                 ws.onmessage = function(event) {
  41.                     var messages = document.getElementById('messages')
  42.                     var message = document.createElement('li')
  43.                     var content = document.createTextNode(event.data)
  44.                     message.appendChild(content)
  45.                     messages.appendChild(message)
  46.                 };
  47.                 event.preventDefault()
  48.             }
  49.             function sendMessage(event) {
  50.                 var input = document.getElementById("messageText")
  51.                 ws.send(input.value)
  52.                 input.value = ''
  53.                 event.preventDefault()
  54.             }
  55.         </script>
  56.     </body>
  57. </html>
  58. """
  61. @app.get("/")
  62. async def get():
  63.     return HTMLResponse(html)
  66. async def get_cookie_or_token(
  67.     websocket: WebSocket,
  68.     session: Annotated[Union[str, None], Cookie()] = None,
  69.     token: Annotated[Union[str, None], Query()] = None,
  70. ):
  71.     if session is None and token is None:
  72.         raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
  73.     return session or token
  76. @app.websocket("/items/{item_id}/ws")
  77. async def websocket_endpoint(
  78.     *,
  79.     websocket: WebSocket,
  80.     item_id: str,
  81.     q: Union[int, None] = None,
  82.     cookie_or_token: Annotated[str, Depends(get_cookie_or_token)],
  83. ):
  84.     await websocket.accept()
  85.     while True:
  86.         data = await websocket.receive_text()
  87.         await websocket.send_text(
  88.             f"Session cookie or query token value is: {cookie_or_token}"
  89.         )
  90.         if q is not None:
  91.             await websocket.send_text(f"Query parameter q is: {q}")
  92.         await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
  1. from typing import Union
  3. from fastapi import (
  4.     Cookie,
  5.     Depends,
  6.     FastAPI,
  7.     Query,
  8.     WebSocket,
  9.     WebSocketException,
  10.     status,
  11. )
  12. from fastapi.responses import HTMLResponse
  13. from typing_extensions import Annotated
  15. app = FastAPI()
  17. html = """
  18. <!DOCTYPE html>
  19. <html>
  20.     <head>
  21.         <title>Chat</title>
  22.     </head>
  23.     <body>
  24.         <h1>WebSocket Chat</h1>
  25.         <form action="" onsubmit="sendMessage(event)">
  26.             <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
  27.             <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
  28.             <button onclick="connect(event)">Connect</button>
  29.             <hr>
  30.             <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
  31.             <button>Send</button>
  32.         </form>
  33.         <ul id='messages'>
  34.         </ul>
  35.         <script>
  36.         var ws = null;
  37.             function connect(event) {
  38.                 var itemId = document.getElementById("itemId")
  39.                 var token = document.getElementById("token")
  40.                 ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
  41.                 ws.onmessage = function(event) {
  42.                     var messages = document.getElementById('messages')
  43.                     var message = document.createElement('li')
  44.                     var content = document.createTextNode(event.data)
  45.                     message.appendChild(content)
  46.                     messages.appendChild(message)
  47.                 };
  48.                 event.preventDefault()
  49.             }
  50.             function sendMessage(event) {
  51.                 var input = document.getElementById("messageText")
  52.                 ws.send(input.value)
  53.                 input.value = ''
  54.                 event.preventDefault()
  55.             }
  56.         </script>
  57.     </body>
  58. </html>
  59. """
  62. @app.get("/")
  63. async def get():
  64.     return HTMLResponse(html)
  67. async def get_cookie_or_token(
  68.     websocket: WebSocket,
  69.     session: Annotated[Union[str, None], Cookie()] = None,
  70.     token: Annotated[Union[str, None], Query()] = None,
  71. ):
  72.     if session is None and token is None:
  73.         raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
  74.     return session or token
  77. @app.websocket("/items/{item_id}/ws")
  78. async def websocket_endpoint(
  79.     *,
  80.     websocket: WebSocket,
  81.     item_id: str,
  82.     q: Union[int, None] = None,
  83.     cookie_or_token: Annotated[str, Depends(get_cookie_or_token)],
  84. ):
  85.     await websocket.accept()
  86.     while True:
  87.         data = await websocket.receive_text()
  88.         await websocket.send_text(
  89.             f"Session cookie or query token value is: {cookie_or_token}"
  90.         )
  91.         if q is not None:
  92.             await websocket.send_text(f"Query parameter q is: {q}")
  93.         await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")

Tip

Prefer to use the Annotated version if possible.

  1. from fastapi import (
  2.     Cookie,
  3.     Depends,
  4.     FastAPI,
  5.     Query,
  6.     WebSocket,
  7.     WebSocketException,
  8.     status,
  9. )
  10. from fastapi.responses import HTMLResponse
  12. app = FastAPI()
  14. html = """
  15. <!DOCTYPE html>
  16. <html>
  17.     <head>
  18.         <title>Chat</title>
  19.     </head>
  20.     <body>
  21.         <h1>WebSocket Chat</h1>
  22.         <form action="" onsubmit="sendMessage(event)">
  23.             <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
  24.             <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
  25.             <button onclick="connect(event)">Connect</button>
  26.             <hr>
  27.             <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
  28.             <button>Send</button>
  29.         </form>
  30.         <ul id='messages'>
  31.         </ul>
  32.         <script>
  33.         var ws = null;
  34.             function connect(event) {
  35.                 var itemId = document.getElementById("itemId")
  36.                 var token = document.getElementById("token")
  37.                 ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
  38.                 ws.onmessage = function(event) {
  39.                     var messages = document.getElementById('messages')
  40.                     var message = document.createElement('li')
  41.                     var content = document.createTextNode(event.data)
  42.                     message.appendChild(content)
  43.                     messages.appendChild(message)
  44.                 };
  45.                 event.preventDefault()
  46.             }
  47.             function sendMessage(event) {
  48.                 var input = document.getElementById("messageText")
  49.                 ws.send(input.value)
  50.                 input.value = ''
  51.                 event.preventDefault()
  52.             }
  53.         </script>
  54.     </body>
  55. </html>
  56. """
  59. @app.get("/")
  60. async def get():
  61.     return HTMLResponse(html)
  64. async def get_cookie_or_token(
  65.     websocket: WebSocket,
  66.     session: str | None = Cookie(default=None),
  67.     token: str | None = Query(default=None),
  68. ):
  69.     if session is None and token is None:
  70.         raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
  71.     return session or token
  74. @app.websocket("/items/{item_id}/ws")
  75. async def websocket_endpoint(
  76.     websocket: WebSocket,
  77.     item_id: str,
  78.     q: int | None = None,
  79.     cookie_or_token: str = Depends(get_cookie_or_token),
  80. ):
  81.     await websocket.accept()
  82.     while True:
  83.         data = await websocket.receive_text()
  84.         await websocket.send_text(
  85.             f"Session cookie or query token value is: {cookie_or_token}"
  86.         )
  87.         if q is not None:
  88.             await websocket.send_text(f"Query parameter q is: {q}")
  89.         await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")

Tip

Prefer to use the Annotated version if possible.

  1. from typing import Union
  3. from fastapi import (
  4.     Cookie,
  5.     Depends,
  6.     FastAPI,
  7.     Query,
  8.     WebSocket,
  9.     WebSocketException,
  10.     status,
  11. )
  12. from fastapi.responses import HTMLResponse
  14. app = FastAPI()
  16. html = """
  17. <!DOCTYPE html>
  18. <html>
  19.     <head>
  20.         <title>Chat</title>
  21.     </head>
  22.     <body>
  23.         <h1>WebSocket Chat</h1>
  24.         <form action="" onsubmit="sendMessage(event)">
  25.             <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
  26.             <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
  27.             <button onclick="connect(event)">Connect</button>
  28.             <hr>
  29.             <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
  30.             <button>Send</button>
  31.         </form>
  32.         <ul id='messages'>
  33.         </ul>
  34.         <script>
  35.         var ws = null;
  36.             function connect(event) {
  37.                 var itemId = document.getElementById("itemId")
  38.                 var token = document.getElementById("token")
  39.                 ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
  40.                 ws.onmessage = function(event) {
  41.                     var messages = document.getElementById('messages')
  42.                     var message = document.createElement('li')
  43.                     var content = document.createTextNode(event.data)
  44.                     message.appendChild(content)
  45.                     messages.appendChild(message)
  46.                 };
  47.                 event.preventDefault()
  48.             }
  49.             function sendMessage(event) {
  50.                 var input = document.getElementById("messageText")
  51.                 ws.send(input.value)
  52.                 input.value = ''
  53.                 event.preventDefault()
  54.             }
  55.         </script>
  56.     </body>
  57. </html>
  58. """
  61. @app.get("/")
  62. async def get():
  63.     return HTMLResponse(html)
  66. async def get_cookie_or_token(
  67.     websocket: WebSocket,
  68.     session: Union[str, None] = Cookie(default=None),
  69.     token: Union[str, None] = Query(default=None),
  70. ):
  71.     if session is None and token is None:
  72.         raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
  73.     return session or token
  76. @app.websocket("/items/{item_id}/ws")
  77. async def websocket_endpoint(
  78.     websocket: WebSocket,
  79.     item_id: str,
  80.     q: Union[int, None] = None,
  81.     cookie_or_token: str = Depends(get_cookie_or_token),
  82. ):
  83.     await websocket.accept()
  84.     while True:
  85.         data = await websocket.receive_text()
  86.         await websocket.send_text(
  87.             f"Session cookie or query token value is: {cookie_or_token}"
  88.         )
  89.         if q is not None:
  90.             await websocket.send_text(f"Query parameter q is: {q}")
  91.         await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")

Info

As this is a WebSocket it doesn’t really make sense to raise an HTTPException, instead we raise a WebSocketException.

You can use a closing code from the valid codes defined in the specification.

Try the WebSockets with dependencies

If your file is named main.py, run your application with:

WebSockets - 图7

Open your browser at http://127.0.0.1:8000.

There you can set:

  • The “Item ID”, used in the path.
  • The “Token” used as a query parameter.

Tip

Notice that the query token will be handled by a dependency.

With that you can connect the WebSocket and then send and receive messages:

WebSockets - 图8

Handling disconnections and multiple clients

When a WebSocket connection is closed, the await websocket.receive_text() will raise a WebSocketDisconnect exception, which you can then catch and handle like in this example.

Python 3.9+Python 3.6+

  1. from fastapi import FastAPI, WebSocket, WebSocketDisconnect
  2. from fastapi.responses import HTMLResponse
  4. app = FastAPI()
  6. html = """
  7. <!DOCTYPE html>
  8. <html>
  9.     <head>
  10.         <title>Chat</title>
  11.     </head>
  12.     <body>
  13.         <h1>WebSocket Chat</h1>
  14.         <h2>Your ID: <span id="ws-id"></span></h2>
  15.         <form action="" onsubmit="sendMessage(event)">
  16.             <input type="text" id="messageText" autocomplete="off"/>
  17.             <button>Send</button>
  18.         </form>
  19.         <ul id='messages'>
  20.         </ul>
  21.         <script>
  22.             var client_id = Date.now()
  23.             document.querySelector("#ws-id").textContent = client_id;
  24.             var ws = new WebSocket(`ws://localhost:8000/ws/${client_id}`);
  25.             ws.onmessage = function(event) {
  26.                 var messages = document.getElementById('messages')
  27.                 var message = document.createElement('li')
  28.                 var content = document.createTextNode(event.data)
  29.                 message.appendChild(content)
  30.                 messages.appendChild(message)
  31.             };
  32.             function sendMessage(event) {
  33.                 var input = document.getElementById("messageText")
  34.                 ws.send(input.value)
  35.                 input.value = ''
  36.                 event.preventDefault()
  37.             }
  38.         </script>
  39.     </body>
  40. </html>
  41. """
  44. class ConnectionManager:
  45.     def __init__(self):
  46.         self.active_connections: list[WebSocket] = []
  48.     async def connect(self, websocket: WebSocket):
  49.         await websocket.accept()
  50.         self.active_connections.append(websocket)
  52.     def disconnect(self, websocket: WebSocket):
  53.         self.active_connections.remove(websocket)
  55.     async def send_personal_message(self, message: str, websocket: WebSocket):
  56.         await websocket.send_text(message)
  58.     async def broadcast(self, message: str):
  59.         for connection in self.active_connections:
  60.             await connection.send_text(message)
  63. manager = ConnectionManager()
  66. @app.get("/")
  67. async def get():
  68.     return HTMLResponse(html)
  71. @app.websocket("/ws/{client_id}")
  72. async def websocket_endpoint(websocket: WebSocket, client_id: int):
  73.     await manager.connect(websocket)
  74.     try:
  75.         while True:
  76.             data = await websocket.receive_text()
  77.             await manager.send_personal_message(f"You wrote: {data}", websocket)
  78.             await manager.broadcast(f"Client #{client_id} says: {data}")
  79.     except WebSocketDisconnect:
  80.         manager.disconnect(websocket)
  81.         await manager.broadcast(f"Client #{client_id} left the chat")
  1. from typing import List
  3. from fastapi import FastAPI, WebSocket, WebSocketDisconnect
  4. from fastapi.responses import HTMLResponse
  6. app = FastAPI()
  8. html = """
  9. <!DOCTYPE html>
  10. <html>
  11.     <head>
  12.         <title>Chat</title>
  13.     </head>
  14.     <body>
  15.         <h1>WebSocket Chat</h1>
  16.         <h2>Your ID: <span id="ws-id"></span></h2>
  17.         <form action="" onsubmit="sendMessage(event)">
  18.             <input type="text" id="messageText" autocomplete="off"/>
  19.             <button>Send</button>
  20.         </form>
  21.         <ul id='messages'>
  22.         </ul>
  23.         <script>
  24.             var client_id = Date.now()
  25.             document.querySelector("#ws-id").textContent = client_id;
  26.             var ws = new WebSocket(`ws://localhost:8000/ws/${client_id}`);
  27.             ws.onmessage = function(event) {
  28.                 var messages = document.getElementById('messages')
  29.                 var message = document.createElement('li')
  30.                 var content = document.createTextNode(event.data)
  31.                 message.appendChild(content)
  32.                 messages.appendChild(message)
  33.             };
  34.             function sendMessage(event) {
  35.                 var input = document.getElementById("messageText")
  36.                 ws.send(input.value)
  37.                 input.value = ''
  38.                 event.preventDefault()
  39.             }
  40.         </script>
  41.     </body>
  42. </html>
  43. """
  46. class ConnectionManager:
  47.     def __init__(self):
  48.         self.active_connections: List[WebSocket] = []
  50.     async def connect(self, websocket: WebSocket):
  51.         await websocket.accept()
  52.         self.active_connections.append(websocket)
  54.     def disconnect(self, websocket: WebSocket):
  55.         self.active_connections.remove(websocket)
  57.     async def send_personal_message(self, message: str, websocket: WebSocket):
  58.         await websocket.send_text(message)
  60.     async def broadcast(self, message: str):
  61.         for connection in self.active_connections:
  62.             await connection.send_text(message)
  65. manager = ConnectionManager()
  68. @app.get("/")
  69. async def get():
  70.     return HTMLResponse(html)
  73. @app.websocket("/ws/{client_id}")
  74. async def websocket_endpoint(websocket: WebSocket, client_id: int):
  75.     await manager.connect(websocket)
  76.     try:
  77.         while True:
  78.             data = await websocket.receive_text()
  79.             await manager.send_personal_message(f"You wrote: {data}", websocket)
  80.             await manager.broadcast(f"Client #{client_id} says: {data}")
  81.     except WebSocketDisconnect:
  82.         manager.disconnect(websocket)
  83.         await manager.broadcast(f"Client #{client_id} left the chat")

To try it out:

  • Open the app with several browser tabs.
  • Write messages from them.
  • Then close one of the tabs.

That will raise the WebSocketDisconnect exception, and all the other clients will receive a message like:

  1. Client #1596980209979 left the chat

Tip

The app above is a minimal and simple example to demonstrate how to handle and broadcast messages to several WebSocket connections.

But have in mind that, as everything is handled in memory, in a single list, it will only work while the process is running, and will only work with a single process.

If you need something easy to integrate with FastAPI but that is more robust, supported by Redis, PostgreSQL or others, check encode/broadcaster.

More info

To learn more about the options, check Starlette’s documentation for: