HilPresentationRequestEnvelope

Server → Browser  ·  Version 1.3  ·  Phase 1 (Suspension)

Structure

HilPresentationRequestEnvelope ├── Session { EngageSessionID, NodeKey, WorkflowID, TenantID, CorrelationID, ReplyToID?, ResumeCallbackURL } ├── HilType "form" | "chat" | "approval" | "custom" ├── Title string ├── Description string? ├── Deadline string? (ISO 8601 UTC) │ ├── Assignees[] { ActorID, ActorType, DisplayName, Email, AvatarURL } ├── Channels[] { ChannelType, Name, ChannelFormat, IsPrimary, ChannelConfig{} } ├── Presentations[] ordered steps — usually 1 │ └── { PresentationType, Order, Title?, │ FormID?, FormSchemaJson?, PrePopulate{}, │ PromptMessage?, SummaryText?, ContextDocURL?, │ Actions[] ← per-step buttons (overrides envelope Actions[] for this step) │ CustomData{} } ├── Actions[] default buttons — used when Presentation.Actions[] is empty ├── ReplyOptions { EnableSteppedDataReturn=true, EnableFlatDataReturn=true } ├── CustomData{} global context — employee record, invoice, etc. └── Metadata{} correlation IDs, trace, schema version

Action Resolution Rule

Per step, the UI engine evaluates:
If Presentation.Actions is non-empty → use those buttons for this step.
If Presentation.Actions is empty → fall back to the envelope-level Actions[].

Single-step flows (99%): set only envelope-level Actions[], leave Presentation.Actions empty.
Multi-step flows with different buttons per step: set Presentation.Actions on each step.

HilSessionContext

EngageSessionIDintIdentifies the HIL session. Echoed in reply.
NodeKeystringWorkflow node identifier.
WorkflowIDstringParent workflow identifier.
TenantIDintMulti-tenant isolation key.
CorrelationIDstringGUID assigned by server for distributed tracing. Echoed unchanged in reply. Enables request-reply pairing and deduplication.
ReplyToIDstring?Optional reference to a prior request or message this HIL continues. Used for conversation threading. Echoed in reply.
ResumeCallbackURLstringEndpoint where reply is POSTed. Format: /api/hil/respond/{EngageSessionID}

HilReplyOptions

Both flags default to true — zero configuration required. The reply always contains both DataSteps[] and Data{} unless explicitly disabled.
FlagDefaultEffect on reply Payload
EnableSteppedDataReturntruePayload.DataSteps[] populated — one entry per step, each with its own Data{} and CompletedAt.
EnableFlatDataReturntruePayload.Data{} populated — all step data merged flat (last-step-wins on key collision).

HilPresentation — PresentationType

TypeKey fields usedInput collected
"form"FormID, FormSchemaJson, PrePopulate{}Form field values → DataSteps[N].Data{}
"chat"PromptMessage, ThreadIDReply text → Payload.ReplyText + DataSteps[N].Data.ReplyText
"approval"SummaryText, ContextDocURLComment / Reason → Payload.Comment + DataSteps[N].Data.Comment
"info"Any display fieldsNone — read-only display step

Standard Action Sets by HIL Type

These are the default envelope-level Actions[] each node sets. For multi-step forms, override per step via Presentation.Actions[].

HilTypeActionKeyLabelStyleRequiresInputInputLabel
approvalapprovedApproveprimary——
rejectedRejectdangeryesReason for rejection
escalatedEscalatesecondaryoptionalEscalation reason
abstainedAbstainghost——
formsubmittedSubmitprimary——
cancelledCancelghost——
chatrepliedReplyprimaryyesYour reply

Multi-step Action Pattern

JSON — Presentations[] with per-step actions
"Presentations": [
  {
    "PresentationType": "form", "Order": 1, "Title": "Step 1 — Personal Details",
    "FormID": 13005,
    "Actions": [
      { "ActionKey": "next",      "Label": "Next",   "Style": "primary", "Order": 1 },
      { "ActionKey": "cancelled", "Label": "Cancel", "Style": "ghost",   "Order": 2 }
    ]
  },
  {
    "PresentationType": "form", "Order": 2, "Title": "Step 2 — Performance Rating",
    "FormID": 13006,
    "Actions": [
      { "ActionKey": "submitted", "Label": "Submit", "Style": "primary", "Order": 1 },
      { "ActionKey": "cancelled",  "Label": "Cancel", "Style": "ghost",   "Order": 2 }
    ]
  }
],
// Envelope-level Actions[] as fallback (used only if a step's Actions is empty)
"Actions": [
  { "ActionKey": "cancelled", "Label": "Cancel", "Style": "ghost", "Order": 1 }
]

C# Model

C#
public class HilPresentationRequestEnvelope
{
    public HilSessionContext             Session       { get; set; } = new();
    public string                         HilType       { get; set; } = string.Empty;
    public string                         Title         { get; set; } = string.Empty;
    public string?                        Description   { get; set; }
    public string?                        Deadline      { get; set; }
    public List<HilPresentationAssignee>  Assignees     { get; set; } = new();
    public List<HilPresentationChannel>   Channels      { get; set; } = new();
    public List<HilPresentation>         Presentations { get; set; } = new();
    public List<HilPresentationAction>   Actions       { get; set; } = new(); // envelope-level default
    public HilReplyOptions               ReplyOptions  { get; set; } = new();
    public Dictionary<string, object>   CustomData    { get; set; } = new();
    public Dictionary<string, object>   Metadata      { get; set; } = new();
}

public class HilPresentation
{
    public string  PresentationType { get; set; } = string.Empty;
    public int     Order            { get; set; } = 1;
    public string? Title            { get; set; }
    public int?    FormID           { get; set; }
    public string? FormSchemaJson   { get; set; }
    public Dictionary<string, object> PrePopulate { get; set; } = new();
    public string? PromptMessage    { get; set; }
    public string? ThreadID         { get; set; }
    public string? SummaryText      { get; set; }
    public string? ContextDocURL    { get; set; }
    public List<HilPresentationAction> Actions { get; set; } = new(); // per-step override
    public Dictionary<string, object> CustomData { get; set; } = new();
}

public class HilSessionContext
{
    public int     EngageSessionID   { get; set; }
    public string  NodeKey           { get; set; } = string.Empty;
    public string  WorkflowID        { get; set; } = string.Empty;
    public int     TenantID          { get; set; }
    public string  CorrelationID     { get; set; } = string.Empty;
    public string? ReplyToID         { get; set; }
    public string  ResumeCallbackURL { get; set; } = string.Empty;
}

public class HilReplyOptions
{
    public bool EnableSteppedDataReturn { get; set; } = true;
    public bool EnableFlatDataReturn    { get; set; } = true;
}

Channel Formats

ChannelTypeChannelFormat valuesChannelConfig keys
webmodal, inlineinboxView
slackslack-blocksSlackChannelID
emailhtml-email, plain-text-emailToAddress, TemplateID
mobilepushPushTokens
teamsteams-adaptive-cardTeamsChannelID