Get started: WebSocket send and receive

This tutorial builds a small dashboard that receives messages over WebSocket and sends messages back on tap. You'll create one shared WebSocket connection, an incoming WebSocket data source, an outgoing WebSocket data destination, and a tap action so tapping the data piece sends a test message.

The public WebSocket echo server at wss://echo.websocket.org echoes back every message you send — ideal for testing without your own backend. Right after you connect, the server also sends a one-line welcome message such as Request served by 4d896d95b55478 (the id changes each time).

Before you begin

You need one data section on the home screen. If you already completed Get started: HTTP GET, reuse that section; otherwise create one (Add data section manually on the empty home screen, or from the menu).

1. Create a WebSocket connection

Open the menu (top-right) → WebSocket connections → Add WebSocket connection.

On the New WebSocket connection screen:

Leave the reconnect interval and advanced settings at their defaults. The app may try Socket.IO first and automatically fall back to plain WebSocket — the echo server speaks raw WebSocket.

Tap Test in the top-right (next to the save tick) to try the connection with your current settings. A sheet shows Connecting… and then Connected. once it succeeds, or an error if it fails. You don't need to save first.

Tap the save tick in the top-right.

See Data sources (incoming) — shared connections.

2. Create a WebSocket data source (receive)

Open the menu → Data sources → Add data source, or start from Add data piece → Data source → Add data source.

On the "New data source" screen:

  1. Set Name to WS Echo Source.
  2. Set Data source type to WebSocket.
  3. Set Connection to Echo WS.
  4. Leave Message events empty, so every incoming message is accepted (raw WebSocket ignores the filter list anyway).

Tap the save tick in the top-right.

While at least one data piece uses this source, the connection stays open, and new messages update value. The first message you receive is often the server's welcome line (Request served by …). Details about the message itself — event name, mode, connection URL — are available in transformers as ctx.transport. See Lua and JSONPath.

3. Add a data piece

On an empty section, tap Add data piece manually or Ask AI assistant to add data piece. Or turn on Edit layout, tap Add at the top, then Add data piece. In the library, pick Design your own data piece.

Set WS Echo Source as the data piece root data source. Add a Label — it inherits that source.

Set Touches on the Label to Capture so tap actions in later steps run when you tap the Label on the dashboard.

Tap the save tick in the top-right.

Once the link is up, the Label usually shows the connect-time welcome from the echo server (for example Request served by 4d896d95b55478) before you tap to send anything. The connection status dot on the source row should turn connected.

4. Create a WebSocket data destination (send)

Open the menu → Data destinations → Add data destination.

On the "New data destination" screen:

Tap the save tick in the top-right.

See Data destinations (outgoing) for the full list of WebSocket send options.

5. Build the message with Lua

On the home screen, turn on Edit layout, tap the data piece, then tap its menu button and choose Edit.

Select the Label, then open Events → On tap and tap Add... → under Data actions, choose Lua.

Enter a one-line script that returns the current local date and time as text:

return os.date("%Y-%m-%d %H:%M:%S")

Each tap builds a fresh timestamp for the next action. For UTC instead, use os.date("!%Y-%m-%dT%H:%M:%SZ") — see Lua.

6. Trigger the WebSocket send

Tap Add... → under Data actions, choose Trigger data destination.

Set:

WebSocket sends don't return a response to the tap actions. The echoed text arrives back through your WebSocket data source instead.

Save the data piece.

Your tap actions, in order:

Category Action Role
Data actions Lua return os.date(...) — the current time as text
Data actions Trigger data destination Sends that string over the connection

7. Tap the Label on the dashboard

Back on the home screen, tap the Label. Tapping elsewhere on the data piece does nothing.

  1. The Lua action formats the current time (for example 2026-07-02 14:30:05).
  2. Trigger data destination sends it through WS Echo Send.
  3. The echo server returns the same text over the open WebSocket.
  4. WS Echo Source receives it and updates value.
  5. The data piece shows the echoed timestamp (replacing the connect-time welcome if it was still showing).

Tap again to send another message. Each tap sends a new timestamp and replaces the displayed text with the latest echo.

Connection diagnostics

If the data piece stays empty or shows an error:

What you built

Part Role
WebSocket connection Shared link to wss://echo.websocket.org
WebSocket data source Receives the connect welcome and echoed messages into value
WebSocket data destination Sends outgoing text on tap
Data piece A Label shows the latest received message
Lua Builds a timestamp string on each tap
Trigger data destination Sends the current value to the echo server

Next steps

This tutorial uses a reusable destination so other data pieces can send the same way. For a send that belongs on this component only, use WebSocket send instead. Events and Text to send can include {{ value?.field }} when the tap runs.