InteractionRequest — Interaction Pipeline

Full Schema Reference

Field	Type	Required	Description
`interactionId`	string (UUID)	Auto	Generated by the pipeline on publish. Do not set manually.
`type`	InteractionTypeKey	Yes	Built-in: `"approval"`, `"confirmation"`, `"form"`, `"picker"`, `"notification"`. Custom types are allowed.
`targetUserId`	string	Yes	User ID of the recipient, or a role key (e.g., `"role:finance-managers"`).
`title`	string	Yes	Short title shown in the UI component header. Keep under 80 characters.
`description`	string	No	Optional longer description shown below the title.
`payload`	object	Yes	Type-specific payload. Schema is validated by the response validation hook.
`timeoutMs`	number	Yes	Milliseconds until timeout fires. Minimum: 1000. Maximum: 7 days (604800000).
`callbackTopic`	string	No	Override the default callback topic. Default: `interactions.callback.{interactionId}`.
`correlationId`	string	No	Attach a workflow execution ID or tracing key. Returned unchanged in the response.
`priority`	"normal" \| "high"	No	High-priority interactions appear first in the WorkDesk HIL inbox. Default: `"normal"`.
`metadata`	Record<string,string>	No	Arbitrary string key/value pairs — for hooks and audit log enrichment. Not shown in UI.

TypeScript Interface

import { InteractionTypeKey } from 'edge-interact-core';

interface InteractionRequest<TPayload = unknown> {
  /** Auto-generated — do not set */
  interactionId?: string;

  /** Interaction type key — determines which UI component renders */
  type: InteractionTypeKey;

  /** Target user ID or role key */
  targetUserId: string;

  /** Short title for the UI component header */
  title: string;

  /** Optional longer description */
  description?: string;

  /** Type-specific payload — must match the schema for the type */
  payload: TPayload;

  /** Timeout in milliseconds */
  timeoutMs: number;

  /** Override callback topic — defaults to interactions.callback.{interactionId} */
  callbackTopic?: string;

  /** Correlation ID for tracing — returned unchanged in response */
  correlationId?: string;

  /** Display priority in HIL inbox */
  priority?: 'normal' | 'high';

  /** Arbitrary metadata for hooks */
  metadata?: Record<string, string>;
}

Typed Request Examples

Approval Request

import {
  InteractionRequest,
  ApprovalPayload
} from 'edge-interact-core';

const request: InteractionRequest<ApprovalPayload> = {
  type: 'approval',
  targetUserId: 'user-abc-123',
  title: 'Purchase Order Approval',
  description: 'A purchase order has been submitted and requires your approval.',
  payload: {
    context: 'PO-2026-0099 from Acme Corp for $45,000.',
    fields: [
      { key: 'vendor',   label: 'Vendor',   value: 'Acme Corp' },
      { key: 'amount',   label: 'Amount',   value: '$45,000.00' },
      { key: 'category', label: 'Category', value: 'Hardware' }
    ]
  },
  timeoutMs: 86_400_000, // 24 hours
  correlationId: 'workflow-exec-7f3a91bc',
  priority: 'high'
};

Form Request

const request: InteractionRequest<FormPayload> = {
  type: 'form',
  targetUserId: 'user-abc-123',
  title: 'Enter Shipping Details',
  payload: {
    formId: 13001, // Atlas Form ID
    initialValues: {
      recipientName: 'Jane Smith',
      country: 'US'
    }
  },
  timeoutMs: 600_000 // 10 minutes
};

Validation Rules

The InteractionPipeline validates the request before publishing:

type must be a registered interaction type (built-in or custom)
targetUserId must not be empty
timeoutMs must be between 1,000 and 604,800,000 (7 days)
title must not be empty and must be under 200 characters
payload must match the schema for the declared type (validated by the response validation hook)

Do Not Re-Use interactionId Each call to PublishAsync creates a new interaction with a new UUID. If you retry a failed publish, a new interactionId is generated — never reuse an ID from a previous attempt.

Server-Side C# Class

// Server-side equivalent (C#)
public record InteractionRequest
{
    public string InteractionId { get; init; } = Guid.NewGuid().ToString();
    public required string Type { get; init; }
    public required string TargetUserId { get; init; }
    public required string Title { get; init; }
    public string? Description { get; init; }
    public required object Payload { get; init; }
    public required int TimeoutMs { get; init; }
    public string? CallbackTopic { get; init; }
    public string? CorrelationId { get; init; }
    public string Priority { get; init; } = "normal";
    public Dictionary<string, string> Metadata { get; init; } = new();
}

← Pipeline Overview Next: Targeting →