Realtime channels

Before you start

You need customer authentication in your app. A customer signs in through your authentication endpoint, then uses that login when requesting permission to connect. Your Twidget editor login is not a customer login. See Creating Authentication Endpoints.

Channels belong to the selected workspace. Set them up separately in Dev and Prod; using this feature does not create another workspace or increase your workspace allowance. Copying or promoting a workflow does not copy channel settings or overwrite Prod channels. Before releasing, create the required channel names with the intended access in Prod. Release review checks fixed channel names; review variable-based channel selections yourself. Missing or disabled channels stop the realtime command rather than sending to another audience.

Add a channel

1. Open Realtime in the sidebar.

2. Select Add channel.

3. Enter a name, such as order_updates. Use up to 64 letters, numbers, underscores or hyphens, starting with a letter or number. Names are case-sensitive.

4. Choose Access and leave State enabled when you are ready to use the channel.

5. Select Save channel. A notification at the bottom confirms saving.

A workspace supports up to 100 channels. Use the search, access and state filters to find an existing channel before adding another.

Choose private or shared updates

Private to each user is the default. Each connected customer receives only messages addressed to their customer ID. For example, send an order update to the customer who owns that order.

Shared with signed-in users lets authenticated customers who join the channel receive its shared messages. Use it for information intended for everyone in that audience. Do not put private order details in a shared message.

The app cannot choose another customer's identity when connecting. A private message's recipient is selected by your server workflow. Check the caller's permissions before allowing an action to publish someone else's information.

Give a customer permission to connect

Create an endpoint that requires customer authentication. Add Authorize Realtime, choose the channel name and set Return as, for example connection.

Return this result to the signed-in customer's app. It contains a one-use ticket, its expiresAt time, the channel and whether it belongs to a real call or a test.

The ticket lasts 60 seconds. The app sends it in the first message when opening the realtime connection; do not put it in the connection address or share it between customers. An expired or already-used ticket cannot be reused. Obtain a fresh ticket when reconnecting.

A page or an external app needs a realtime client connection to receive messages. Published Twidget pages include an optional TwidgetRealtime connection helper; see the integration example below. Adding a channel alone does not create a live feed or automatically connect your app. See the Realtime command reference for the workflow commands.

Send a message from a workflow

Add Publish Realtime Message to an endpoint, server function or event:

• channel: the configured channel name, such as order_updates.

• event: a short name for the update, such as order_ready.

• data: the information your app needs, for example an order ID and its new status.

• recipient_id: the customer's ID for a private channel. Leave this empty for a shared channel.

Use the normal variable selector to choose your workflow values. Set Return as to retain the result. A result of true means the message was submitted for live delivery; it does not confirm that a customer received or read it.

Keep messages small. A message must fit within 64 KiB, including its event details. A workspace supports up to 120 publish attempts per minute; each customer can request up to 20 connection tickets per minute.

Edit, disable or remove a channel

The channel list shows access, state, last update and version. Edit changes its settings. Renaming a channel means workflows and connected apps must use its new name. Changes to the channel require connected apps to obtain a fresh ticket and reconnect.

Disable a channel to stop new messages without removing its definition. Remove asks for confirmation before deleting the channel. If another editor changed it first, refresh and review the latest settings before trying again.

Test and troubleshoot

For a full connection check, use a synthetic customer account in your Dev workspace and call its authenticated API endpoint. This is a real API call in that Dev workspace, using the normal receiving address.

The editor's Test runner cannot issue connection tickets, even with Use live data enabled, because it does not carry a customer login. Publish commands run from editor tests use an isolated test audience and do not reach customers connected to real API calls.

If connection permission fails, check the customer's login, the channel name and whether the channel is enabled. A private publish also needs a valid recipient customer ID. After changing a channel, sign in again if needed and obtain a new ticket.

Connections last up to 15 minutes, or until the customer login expires if that happens sooner. They may close earlier when access changes or the connection is interrupted. Refresh the app's data after reconnecting.

This version supports authenticated live delivery. It does not offer anonymous channels, publishing directly from a client connection, online-member lists, message history or automatic replay of missed messages.

Connection limits

A workspace supports up to 32 active connections, with up to 5 for one customer. Each connection joins one channel. Your app's address must be allowed by the workspace's cross-origin settings; see API Settings. A different app address may need to be added before it can connect.

const path = '/twgt-realtime';

const handle = TwidgetRealtime.connect({

  url: 'wss://YOUR-API-HOST' + path,

  ticket: connection.ticket,

  onMessage(update) {

    // Use update.event and update.data to refresh the relevant app view.

  },

  onStatus(status) {

    // status.state is connecting, ready, closed or error.

  }

});

handle.ready.catch(() => {

  // Show a connection message; get a new ticket before trying again.

});

// Close when leaving the screen or signing out:

// handle.close();