write-flow

Write & Deploy Architect Flows

Create Genesys Cloud Architect flows as TypeScript, typecheck them, and deploy them via the deploy_flow MCP tool.

Prerequisites

The user's project must have the Architect Scripting SDK installed for type checking:

npm install --save-dev purecloud-flow-scripting-api-sdk-javascript

Deploy only (existing flow file)

If the user already has a flow file and just wants to deploy it, skip straight to step 5 — call the deploy_flow MCP tool with the file path. Only fall back to steps 1–4 if deployment fails or the user asks for help writing/fixing the flow.

Workflow

1. Understand the requirement

Ask the user:

• Flow type: inbound call, inbound chat, inbound email, inbound message (SMS), or workflow
• What it should do: routing, menus, greetings, queue transfers, data lookups, etc.
• Flow name: what to name the flow in Architect

Only ask about queue names if the user's description involves queue transfers. Not every flow routes to a queue.

2. Read the relevant references

Before writing any flow code, read these reference files from this skill:

1. Always read: references/sdk-patterns.md — core SDK patterns and the buildFlow contract
2. Always read: references/gotchas.md — SDK quirks that cause silent failures
3. Always read: references/action-reference.md — available action types
4. Read when the flow uses expressions: references/expression-reference.md — expression language syntax, functions, operators, data types, and common patterns. Read this whenever the flow involves conditional logic, dynamic text, variable manipulation, date/time calculations, or any setExpression() / expression property usage.
5. Read the matching example from references/examples/:
   • inbound-call.md — IVR with menus and queue transfers
   • inbound-chat.md — chat greeting and queue transfer
   • inbound-email.md — auto-reply and queue transfer
   • inbound-message.md — SMS auto-reply and queue transfer
   • workflow.md — callback workflow

3. Write the flow file

Write a TypeScript file in the user's project that exports a buildFlow function:

import type { ArchitectScripting } from "purecloud-flow-scripting-api-sdk-javascript";

export async function buildFlow(scripting: ArchitectScripting): Promise<void> {
    const { archFactoryFlows, archFactoryActions } = scripting.factories;

    const flow = await archFactoryFlows.createFlowInboundCallAsync(
        "Flow Name",
        "Flow Description",
    );

    // Build the flow...

    await flow.checkInAsync();
}

Rules:

• The function receives the SDK as a parameter — never require() the SDK in the flow file
• Only use import type from the SDK (stripped at runtime)
• Always call flow.checkInAsync() at the end to save the flow
• Use the exact patterns from the reference docs — the SDK is quirky

4. Typecheck

Run the TypeScript compiler against the flow file directly (the user's project may not have a tsconfig.json):

npx tsc --noEmit --strict --moduleResolution bundler --module ES2022 --target ES2022 --allowImportingTsExtensions --skipLibCheck path/to/flow.ts

--skipLibCheck is required because the SDK's own types.d.ts has internal errors (duplicate identifiers, missing type references). Without it, tsc fails on the SDK — not on your flow code.

Fix any errors before deploying.

5. Deploy

Use the deploy_flow MCP tool:

Tool: deploy_flow
Input: { "flowFile": "./path/to/flow.ts" }

The tool spawns an isolated process that:

1. Starts an authenticated SDK session using the plugin's Genesys credentials
2. Imports the flow file and calls buildFlow(scripting)
3. Returns success/failure with SDK logs

If deployment fails, read the error logs carefully — the SDK has three error channels (logging callback, TRACE lines, HTTP errors) and the deploy runner captures all of them.