---
title: "ws"
description: "The ws namespace — the engine's Luau API reference for ws."
section: "API Reference"
slug: "api-ws"
canonical: "https://origozero.ai/docs/api-ws"
updated: "2026-09-04T19:42:51.507603349+00:00"
tags: ["api", "reference"]
---

# ws

The `ws` namespace — 5 functions.

## ws/close {#ws-close}

```lua
ws.close(handle)
```

Close the connection. Pending ws.recv promises resolve with {kind='closed'}.

**Parameters**

- `handle` `number` — Connection handle

## ws/connect {#ws-connect}

```lua
ws.connect(url, headers?) -> string
```

Open a WebSocket. Returns a promise id — use task.await + ws.poll. Headers is an optional table of {name=value} string pairs.

**Parameters**

- `url` `string` — WebSocket URL (ws:// or wss://)
- `headers` `table` _(optional)_ — Request headers (string→string)

**Returns** `string` — Promise id for ws.poll()

## ws/poll {#ws-poll}

```lua
ws.poll(promise_id) -> table | nil
```

Poll one ws.connect / ws.recv promise. Returns nil while pending. On resolution returns one of {kind='connected', handle}, {kind='connect_failed', error}, {kind='frame', text|bytes}, {kind='closed', reason}, {kind='recv_failed', error}.

**Parameters**

- `promise_id` `string` — Promise id from ws.connect() or ws.recv()

**Returns** `table | nil` — Resolved result, or nil if still pending

## ws/recv {#ws-recv}

```lua
ws.recv(handle) -> string
```

Async-wait for one frame on an open connection. Returns a promise id — ws.poll resolves with {kind='frame', text|bytes} or {kind='closed', reason} or {kind='recv_failed', error}.

**Parameters**

- `handle` `number` — Connection handle from ws.poll on a previous ws.connect

**Returns** `string` — Promise id for ws.poll()

## ws/send {#ws-send}

```lua
ws.send(handle, text)
```

Send a text frame on an open connection. Silent no-op if the handle is unknown / closed. Binary frames not yet supported by this surface.

**Parameters**

- `handle` `number` — Connection handle
- `text` `string` — Frame payload (UTF-8)