xapps

xApps

xApps are interactive in-conversation mini-apps: you render an HTML page or an Adaptive Card to the user, they interact, and their submitted data flows back into the conversation. xApps are built as flow nodes managed with manage_flow_nodes (extension @cognigy/basic-nodes).

Two hard rules

1. xApp: Init Session (initAppSession) must run before any other xApp node. It creates the session and populates input.apps.url (session URL) and input.apps.baseUrl. Every other xApp node depends on a live session. Creating an xApp node without a preceding initAppSession in the flow returns a _hints.warning — add Init Session first.
2. Data comes back via input/context, not a return value — see "Accessing xApp data".

Where xApp nodes go

Like all manage_flow_nodes nodes, xApp nodes live inside a tool branch — never before the AI Agent Job node (see the flow-nodes guide). "Init Session at the beginning" means the beginning of the xApp sequence inside the tool branch, not the flow's absolute start.

Typical chain inside a tool:

tool node ──appendChild──▶ initAppSession
          ──append──────▶ showXAppAdaptiveCard { waitForInput: true, storeResultInContext: true, contextKey: "result" }
          ──append──────▶ code / say  (reads context.result or input.data._cognigy._app.payload)
                          ▶ Resolve Tool Action

Workflow

1. Create a tool — create_tool { aiAgentId, toolType: 'tool', name: 'Collect Details', config: { toolId: 'collect_details', description: 'Collect details via an xApp' } } → toolNodeId
2. Init the session — manage_flow_nodes { operation: 'create', flowId, parentNodeId: '<toolNodeId>', mode: 'appendChild', nodeType: 'initAppSession', label: 'xApp: Init Session' }
3. Show a UI + wait — manage_flow_nodes { operation: 'create', flowId, parentNodeId: '<initSessionNodeId>', mode: 'append', nodeType: 'showXAppAdaptiveCard', label: 'xApp: Show Card', config: { card: { ... }, waitForInput: true, storeResultInContext: true, contextKey: 'result' } }
4. Use the result — add a code/say node after it that reads context.result or input.data._cognigy._app.payload
5. List nodes — manage_flow_nodes { operation: 'list', flowId }