Receiving Interaction Requests

The interactions.{userId} Topic

Every user has a dedicated interaction inbox topic: interactions.{userId}. This topic is:

• Per-user: Only that user's authenticated sessions can subscribe
• Server-write-only: Only the EdgeInteract server can publish to this topic
• Persistent: Messages published while the user is offline are retained until the timeout expires

InteractionSubscriber — How It Works

// InteractionSubscriber wraps EdgeStream subscription (simplified internal implementation)
class InteractionSubscriber {
  private subscription: EdgeStreamSubscription | null = null;

  async start(userId: string, queue: InteractionQueue): Promise<void> {
    // Subscribe to the user's interaction inbox
    this.subscription = await edgeStreamClient.subscribe(
      `interactions.${userId}`,
      async (message) => {
        const request = JSON.parse(message.body) as InteractionRequest;

        // Validate the message structure
        if (!isValidInteractionRequest(request)) {
          console.warn('Received malformed InteractionRequest', request);
          return;
        }

        // Add to the interaction queue — InteractionContainer will render it
        queue.enqueue(request);

        // Notify the server that the client displayed the interaction
        await this.sendDisplayedStatus(request.interactionId);
      }
    );
  }

  async stop(): Promise<void> {
    await this.subscription?.unsubscribe();
    this.subscription = null;
  }
}

Message Format on the Topic

Messages on interactions.{userId} are always serialized InteractionRequest JSON. The client identifies the message type by the type field inside the JSON body:

// Example message body on interactions.usr_abc123
{
  "interactionId": "8f4a91bc-...",
  "type": "approval",
  "targetUserId": "usr_abc123",
  "title": "Invoice Approval Required",
  "description": "Invoice #INV-2026-0042 requires your approval.",
  "payload": {
    "context": "...",
    "fields": [...]
  },
  "timeoutMs": 86400000,
  "priority": "high",
  "correlationId": "wf-exec-7f3a",
  "metadata": {}
}

Reconnect Behavior

If the user's session disconnects and reconnects:

• The InteractionSubscriber automatically re-subscribes via EdgeStream's reconnect mechanism
• Any pending interactions (published during the disconnect window, not yet timed out) are replayed by EdgeStream
• Interactions that timed out during the disconnect are not replayed — the server sends dismissal signals for them instead

Interaction Queue Priority

When multiple interactions are pending, they are displayed in this priority order:

1. priority: "high" interactions first (FIFO within high)
2. priority: "normal" interactions (FIFO within normal, sorted by arrival time)