Skip to content

WebSocket Trigger Block

The WebSocket Trigger block creates a WebSocket API endpoint using AWS API Gateway. It enables real-time, bidirectional communication between clients and your workflow.

AWS Service: Amazon API Gateway WebSocket APIs

Configuration Options

The WebSocket Trigger block currently has no additional configuration options. It creates a WebSocket endpoint that handles connection events.

How WebSockets Work

Unlike HTTP APIs (request-response), WebSocket APIs maintain persistent connections:

Client                          Server
   |                               |
   |------- Connect ($connect) --->|
   |                               |
   |<------ Message --------------->|
   |<------ Message --------------->|
   |<------ Message --------------->|
   |                               |
   |------- Disconnect ----------->|
   |                               |

WebSocket Routes

Route Description
$connect Triggered when a client establishes a connection
$disconnect Triggered when a client disconnects
$default Handles messages that don't match other routes

Use Cases

Real-Time Chat

WebSocket Trigger --> Function (process message) --> Function (broadcast)

Clients connect and send messages that are broadcast to other connected users.

Live Notifications

WebSocket Trigger --> Function (subscribe)
                 --> Function (send notification)

Push notifications to connected clients in real-time.

Live Dashboards

WebSocket Trigger --> Function (stream updates)

Stream live data updates to dashboard clients.

Collaborative Editing

WebSocket Trigger --> Function (sync changes)

Synchronize document changes between multiple users in real-time.

AI Thinking Feedback

WebSocket Trigger --> Function (LLM thinking steps)

Send intermediate thinking steps from AI models to clients for enhanced user experience.

Message Format

Incoming Messages

Messages from clients are received as JSON in the Function block:

// Example incoming message
{
  "ctx": {
    "webSocket": {
      "routeKey": "$default",
      "connectionId": "abc123",
      "domainName": "example.com",
      "stage": "prod"
    },
  }
  "payload": "Hello, World!"
}

Sending Messages to Clients

To send messages back to connected clients, use the connection ID:

send("Your message", { webSocket: {connectionId: "your-connection-id" }});

Connection Management

Connection ID

Each client connection has a unique connectionId that identifies it. You can send this id to other blocks, or store it to target specific clients.

AWS Reference

Quotas and Limits

Limit Value
Max message size 128 KB
Connection duration 2 hours (idle timeout: 10 minutes)
Max connections per API 500 (soft limit, can be increased)

Best Practices

  1. Store connection IDs: Use DynamoDB to track active connections
  2. Handle disconnects gracefully: Clean up resources on $disconnect
  3. Implement heartbeats: Keep connections alive with periodic pings
  4. Use connection-scoped data: Store user context with connection ID
  5. Handle errors: Implement retry logic for failed message sends
  6. Scale appropriately: Consider connection limits for high-traffic applications