Developer Guide: Workflow Client Integration

This guide explains how to integrate your custom chat client with the Automatically workflow engine, specifically handling real-time events and data collection.

SignalR Events

To provide a seamless experience, your client should listen for the following SignalR events. These events allow the UI to react to the back-and-forth progress of an automated task.

| Event | Payload | Description | | :--- | :--- | :--- | | WorkflowStarted | workflowId, name | The agent has begun an automated task. Use this to update the UI header. | | WorkflowStepStarted | stepId, message | A specific action has begun. Use this to show a loading or "shimmer" state. | | WorkflowInterventionRequired | stepId, message, dataPoints | The workflow matches a step requiring customer input. Render a form based on dataPoints. | | WorkflowStepCompleted| stepId | An action finished successfully. | | WorkflowStepFailed | stepId, error | An action failed. Use this to show a retry or error message. | | WorkflowCompleted | workflowId | The entire task is finished. |

Responding to Interventions

When a WorkflowInterventionRequired event is received, your client must present a structured form to the user. Once the user submits the form, you should call the /api/chat/resume-workflow endpoint with the collected values.

The dataPoints array includes the schema for the required fields:

• key: The unique ID for the field.
• label: The human-readable label to display.
• type: The input type (e.g., Text, Email, Select).

State Management & Reconnection

The workflow engine maintains internal state for each conversation. If a user refreshes their page or loses their connection, the current state remains active. When the client re-establishes the connection and fetches the chat history, the ActiveWorkflow status allows the UI to restore the current step and any pending input forms.

Execution Safety

• Linear Progression: Workflows follow a strictly sequential path to ensure data integrity.
• Fail-Fast: If a critical step fails, the workflow gracefully halts to prevent inconsistent results, allowing for human intervention if necessary.
• Timeouts: Actions have built-in safety timeouts to ensure the conversation never hangs.