Skip to main content

Documentation: FlowContextSchema Interface

The FlowContextSchema interface defines the structure of the context of an interactive flow, including the current stage (step) and the general information of the flow (flow).

Definition​

export const FlowContextSchema = {
  status: "ok" | "error",
  flow: FlowSchema,
  step: StepSchema,
};

Properties​

1. status​

  • Type: string
  • Description: Represents the status of the context. Possible values:
    • "ok": The context is valid and ready to be processed.
    • "error": The context is invalid or contains errors.

2. flow​

  • Type: FlowSchema
  • Description: Represents the general information of the flow.

Properties of FlowSchema:​

  • id (string): Unique identifier of the flow.
  • organizationId (string): Identifier of the organization that owns the flow.
  • updatedAt (string): Date and time when the flow was last updated.
  • stages (array): List of stages in the flow.
    • id (string): Unique identifier of the stage.
    • name (string): Descriptive name of the stage.

3. step​

  • Type: StepSchema
  • Description: Represents the current stage of the interactive flow.

Properties of StepSchema:​

  • id (string): Unique identifier of the stage.
  • title (string, optional): Descriptive title of the stage.
  • description (string, optional): Description of the stage.
  • stageId (string, optional): Identifier of the stage within the flow.
  • state (object, optional): Represents the state associated with the stage.
  • fields (array, optional): List of defined fields in the stage (detailed below).
  • actions (array, optional): List of available actions in the stage (detailed below).
  • error (object, optional): Represents an error associated with the stage.
  • result (object, optional): Represents the result of the stage.
  • isFinal (boolean, optional): Indicates if this stage is the last in the flow.

Details of fields​

  • Type: StepFieldSchema[]
  • Description: Defines the interactive fields that a user must complete or interact with in a stage.

Properties of StepFieldSchema:​

  • name (string): Name of the field.
  • label (string): Descriptive label of the field.
  • type (enum): Data type of the field. Possible values include:
    • "text", "boolean", "number", "email", "phone", "mobile_phone", "date", "time", "datetime", "password", "url", "void", "location", "availability".
  • component (enum, optional): UI component used to represent the field. Examples:
    • "input", "textarea", "select", "radio", "checkbox", "map", etc.
  • selectionMode (enum, optional): Selection mode for selection fields.
    • "single": A single option (default).
    • "multiple": Multiple options.
  • placeholder (string, optional): Suggested text to help the user.
  • options (array, optional): List of options for selection fields.
    • label (string): Text of the option.
    • value (any, optional): Value corresponding to the field type.
    • image (URL, optional): Associated image.
    • description (string, optional): Additional description of the option.
    • disabled (boolean, optional): Indicates if the option is disabled.
  • required (boolean, optional): Indicates if the field is mandatory.
  • configuration (object, optional): Specific configuration for advanced field types.
  • customError (object, optional): Customize validation error messages for the field:
    • required (string): Message shown when a required field is empty.
    • invalid (string): Message shown when the field value is invalid.
    • minLength (string): Message shown when text length is below minimum.
    • maxLength (string): Message shown when text length exceeds maximum.
    • minValue (string): Message shown when numeric value is below minimum.
    • maxValue (string): Message shown when numeric value exceeds maximum.
    • mismatch (string): Message shown when field value doesn't match related field.

Details of actions​

  • Type: StepActionSchema[]
  • Description: Defines the actions that a user can execute in the stage.

Properties of StepActionSchema:​

  • id (string): Unique identifier of the action.
  • type (enum): Type of action. Possible values:
    • "submit": Submit data.
    • "forward": Move to the next step.
    • "link": Redirect to an external URL.
    • "iCall": Open iCall service.
  • label (string): Descriptive label of the action.
  • variant (enum): Visual variant of the action. Values:
    • "primary", "secondary", "success", "danger", "warning", "info".
  • url (string, optional): URL associated with link type actions.

Details of state​

  • Type: object
  • Description: Represents the state associated with the stage.

Details of error​

  • Type: object
    • message (string): Error message.
    • code (string): Error code.
    • fields (FieldsError[]): List of fields with errors.
      • name (string): Name of the field.
      • type (string): Type of field.
      • value (any): Value of field.
      • error (string): Error message.
  • Description: Represents an error associated with the stage.

Error Codes​

  • "INVALID_DATA": Invalid form data.
  • "INVALID_ACTION": Invalid submitted action.
  • "STEP_NOT_FOUND": Next step not found.
  • "UNKNOWN_ERROR": Unknown error.
  • "APPOINTMENT_INVALID_DATA": Invalid appointment data.
  • "APPOINTMENT_BUSY_SLOT": Slot is already booked or blocked.
  • "APPOINTMENT_OUT_OF_DATE": Slot is out of date range.
  • "APPOINTMENT_FAILED": Appointment creation failed.
  • "APPOINTMENT_UNKNOWN_ERROR": Unknown appointment error.
  • "LEAD_INVALID_DATA": Invalid lead data.
  • "LEAD_UNKNOWN_ERROR": Unknown lead error.
  • "CONTENT_INVALID_DATA": Invalid content data.
  • "CONTENT_UNKNOWN_ERROR": Unknown content error.
  • "CONTACT_INVALID_DATA": Invalid contact data.
  • "CONTACT_UNKNOWN_ERROR": Unknown contact error.
  • "LOST_OPPORTUNITY_INVALID_DATA": Invalid opportunity data.
  • "LOST_OPPORTUNITY_UNKNOWN_ERROR": Unknown opportunity error.
  • "CALENDAR_INVALID_DATA": Invalid calendar data.
  • "CALENDAR_UNKNOWN_ERROR": Unknown calendar error.
  • "OTP_VALIDATION_INVALID_DATA": Invalid OTP validation data.
  • "OTP_VALIDATION_UNKNOWN_ERROR": Unknown OTP validation error.

Structure Example​

Success context response​

const flowContext = {
  status: "ok",
  step: {
    id: "step123",
    title: "Registration Form",
    description: "Please complete the following fields.",
    fields: [
      {
        name: "name",
        label: "Name",
        type: "text",
        required: true,
      },
      {
        name: "acceptTOS",
        label: "I accept the terms and conditions",
        type: "boolean",
        component: "checkbox",
        required: true,
      },
    ],
    actions: [
      {
        id: "submitForm",
        type: "submit",
        label: "Submit",
        variant: "primary",
      },
    ]
  },
  flow: {
    id: "flow456",
    organizationId: "123e4567-e89b-12d3-a456-426614174000",
    updatedAt: "2025-01-17T10:00:00Z",
    stages: [
      { id: "stage1", name: "Start" },
      { id: "stage2", name: "Confirmation" },
    ],
  },
};

Error context response​

const flowContext = {
  status: "error",
  step: {
    id: "step123",
    title: "Registration Form",
    description: "Please complete the following fields.",
    fields: [
      {
        name: "name",
        label: "Name",
        type: "text",
        required: true,
      },
      {
        name: "acceptTOS",
        label: "I accept the terms and conditions",
        type: "boolean",
        component: "checkbox",
        required: true,
      },
    ],
    actions: [
      {
        id: "submitForm",
        type: "submit",
        label: "Submit",
        variant: "primary",
      },
    ],
    error: {
      code: "INVALID_DATA",
      message: "Please fill in all required fields.",
      fields: [
        {
          name: "name",
          type: "text",
          value: "",
          error: "Name is required",
        },
      ],
    },
  },
  flow: {
    id: "flow456",
    organizationId: "123e4567-e89b-12d3-a456-426614174000",
    updatedAt: "2025-01-17T10:00:00Z",
    stages: [
      { id: "stage1", name: "Start" },
      { id: "stage2", name: "Confirmation" },
    ],
  },
};

Notes​

  • The FlowContextSchema interface is used to represent the current state of the flow and its general context.
  • StepSchema and its subcomponents (fields and actions) are critical to defining user interaction at each stage of the flow.