Skip to main content

websocket

Library

Provides functions for interacting with WebSocket servers.

Functions​

connect​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
websocket.connect(
url: string--

The WebSocket URL to connect to (must start with ws:// or wss://).

) → WebSocketConnection?--

The WebSocketConnection object on success, or nil if the connection failed (e.g., invalid URL, timeout, server unreachable).

Establishes a connection to a WebSocket server.

This function initiates the connection attempt and yields the current thread until the connection is established or fails. The connection attempt times out after 30 seconds.

Usage
local wsUrl = "wss://echo.websocket.org" -- Example echo server
local connection = websocket.connect(wsUrl)

if connection then
    print("WebSocket connected!")

    connection.OnMessage:Connect(function(message)
        print("Received:", message)
        -- Echo the message back after 1 second
        task.delay(1, function()
            connection:Send("Echo: " .. message)
        end)
    end)

    connection.OnClose:Connect(function()
        print("WebSocket disconnected.")
    end)

    -- Send an initial message
    connection:Send("Hello from Luau!")

    -- Close after 10 seconds
    task.delay(10, function()
        print("Closing connection...")
        connection:Close()
    end)
else
    print("WebSocket connection failed for:", wsUrl)
end

Errors

TypeDescription
invalid websocket urlThe provided URL does not start with `ws://` or `wss://`.
Show raw api
{
    "functions": [
        {
            "name": "connect",
            "desc": "Establishes a connection to a WebSocket server.\n\nThis function initiates the connection attempt and yields the current thread until the connection is established or fails. The connection attempt times out after 30 seconds.\n\n\n:::tip Usage\n```lua\nlocal wsUrl = \"wss://echo.websocket.org\" -- Example echo server\nlocal connection = websocket.connect(wsUrl)\n\nif connection then\n    print(\"WebSocket connected!\")\n\n    connection.OnMessage:Connect(function(message)\n        print(\"Received:\", message)\n        -- Echo the message back after 1 second\n        task.delay(1, function()\n            connection:Send(\"Echo: \" .. message)\n        end)\n    end)\n\n    connection.OnClose:Connect(function()\n        print(\"WebSocket disconnected.\")\n    end)\n\n    -- Send an initial message\n    connection:Send(\"Hello from Luau!\")\n\n    -- Close after 10 seconds\n    task.delay(10, function()\n        print(\"Closing connection...\")\n        connection:Close()\n    end)\nelse\n    print(\"WebSocket connection failed for:\", wsUrl)\nend\n```\n:::",
            "params": [
                {
                    "name": "url",
                    "desc": "The WebSocket URL to connect to (must start with `ws://` or `wss://`).",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The `WebSocketConnection` object on success, or `nil` if the connection failed (e.g., invalid URL, timeout, server unreachable).",
                    "lua_type": "WebSocketConnection?"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid websocket url",
                    "desc": "The provided URL does not start with `ws://` or `wss://`."
                }
            ],
            "yields": true,
            "source": {
                "line": 53,
                "path": "impl/Libraries/websocket.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "websocket",
    "desc": "Provides functions for interacting with WebSocket servers.",
    "tags": [
        "Library"
    ],
    "source": {
        "line": 6,
        "path": "impl/Libraries/websocket.luau"
    }
}