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:
- Name —
Echo WS - URL —
wss://echo.websocket.org - Transport — WebSocket (default)
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:
- Set Name to
WS Echo Source. - Set Data source type to WebSocket.
- Set Connection to
Echo WS. - 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.
- Data source —
WS Echo Source(already selected if you came from step 2)
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:
- Name —
WS Echo Send - Type — WebSocket
- Connection —
Echo WS(the same link as the source) - Message events — leave the default
message(used for Socket.IO-style transports; on raw WebSocket the message is sent directly)
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:
- Data destination —
WS Echo Send - Text to send — leave it empty so the app sends the current value (the string from the Lua action)
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.
- The Lua action formats the current time (for example
2026-07-02 14:30:05). - Trigger data destination sends it through
WS Echo Send. - The echo server returns the same text over the open WebSocket.
WS Echo Sourcereceives it and updatesvalue.- 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:
- Open WebSocket connections →
Echo WSand check the connection log (you should see Connected (WebSocket) after the Socket.IO fallback). - On the "Data sources" screen, confirm
WS Echo Sourcehas a green status dot. - The echo server limits messages to 64 KB and closes idle connections after about 10 minutes — tap again or reconnect if needed.
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.
- Get started: HTTP POST on tap — outgoing HTTP with a JSON response on the data piece
- Get started: HTTP GET — incoming HTTP data and transformers
- Tap actions — build richer send chains (Lua, expressions, multiple actions)
- Data sources (incoming) — Socket.IO event filters, SSE, and rooms
- Data destinations (outgoing) — MQTT publish and HTTP outbound