Targeting — Interaction Pipeline

Single-User Targeting

The simplest and most common targeting mode. Set targetUserId to the exact user ID of the recipient:

const request: InteractionRequest = {
  type: 'approval',
  targetUserId: 'usr_7f3a91bc',  // exact user ID
  title: 'Approve Leave Request',
  payload: { ... },
  timeoutMs: 86_400_000
};

The pipeline publishes the request to interactions.usr_7f3a91bc. Only WebSocket sessions authenticated as that user will receive it. The user sees the interaction in their HIL inbox on all their active devices/tabs simultaneously.

Multi-Session Fan-Out If the user has multiple active sessions (e.g., desktop + mobile), all sessions receive the interaction. The first session to respond wins — the remaining sessions receive a dismissal signal.

Role Targeting

Role targeting is used when any member of a team can respond — for example, "any Finance Manager can approve this PO." Set targetUserId to a role key prefixed with role::

const request: InteractionRequest = {
  type: 'approval',
  targetUserId: 'role:finance-managers',  // role key
  title: 'Emergency Purchase Approval',
  payload: { ... },
  timeoutMs: 7_200_000 // 2 hours
};

Role resolution: The InteractionPipeline queries the Passport IAM service to resolve role:finance-managers to a list of user IDs. It then publishes to each user's individual interactions.{userId} topic. Users not in the role at publish time do not receive the interaction.

First-to-Respond Wins

For role-targeted interactions, only one response is accepted. When the first user responds:

First Response Arrives

The InteractionResponse from user A arrives on the callback topic. The pipeline marks the interaction as responded.

Lock Other Responses

The pipeline atomically locks the interaction. Any subsequent response from user B (or other sessions of user A) is rejected with InteractionAlreadyRespondedException.

Dismiss All Other Recipients

EdgeInteract publishes a dismissal signal to the interactions.dismiss.{userId} topic for every other recipient. Their UI removes the interaction from the inbox.

Targeting Modes Comparison

Mode	targetUserId value	Who receives	Who can respond
Single user	`"usr_7f3a91bc"`	One user, all their sessions	That user only
Role	`"role:finance-managers"`	All role members at publish time	First to respond (any role member)

Offline Users

If the targeted user has no active EdgeStream session when the interaction is published:

The interaction is stored in the pipeline state store with status: "pending"
When the user connects (or reconnects), EdgeInteract delivers any pending interactions immediately as part of the EdgeStream session reconnect flow
The timeout continues running even while the user is offline — if they reconnect after the timeout has fired, the interaction is not delivered (it is already timed_out)

Set Generous Timeouts for Offline Scenarios If targeted users may be offline (e.g., approval flows sent to managers overnight), set a timeout that allows for their expected offline window. A 24-hour timeout is typical for approval interactions.

Group Targeting (Future)

Group targeting (send to a specific list of user IDs, require N of M to respond) is planned for a future release. For now, use role targeting as the multi-user mechanism.

← InteractionRequest Next: Display Stage →