Advanced Widget Configuration

1) Overview

When a visitor starts a chat, the Flow Widget typically collects their name, email address, and other details through workflow form_field or collect_info nodes. If your application already knows who this person is — because they are logged in, have completed an order, or you have CRM data — you can pass that information to the widget so the chat experience is immediate and personalised.

Advanced widget configuration provides two complementary capabilities:

Both features work together: you pass a single context object, and the system handles what is shown to operators versus what is used to skip workflow steps.

2) Visitor Context Data

Visitor context is a JSON object you attach to the widget embed. It is securely transmitted to the server when the visitor starts a chat session and stored against both the active session and the permanent chat log.

What operators see

In the dashboard chat panel, operators see all supplied context key–value pairs in a dedicated Visitor Context panel before and during the conversation. This gives them instant background — for example, the visitor's account tier or their last support ticket — without asking the customer to repeat themselves.

Where data is stored

Context data is persisted in two database columns (both as sanitised JSON):

• activesessions.visitor_context_data — visible during the live chat
• chatlogs.visitor_context_data — retained on the closed chat transcript

Example context object

{
  "account_id":   "USR-84920",
  "plan":         "Pro",
  "last_order":   "#ORD-20241122",
  "ims_username": "Jane Smith",
  "ims_email":    "jane@example.com"
}

Any key you supply (other than the reserved ims_* keys) is treated as informational metadata displayed to the operator. The ims_* keys are additionally used to pre-fill workflow fields — see section 4.

3) How to Pass Context

There are two ways to supply visitor context data. Choose whichever fits your stack.

Option A — data-visitor-context attribute Recommended

Add a data-visitor-context attribute to your widget embed script tag. Set its value to a JSON string. This is the simplest approach and requires no extra JavaScript configuration.

<script
  src="https://dashboard.imsupporting.com/public_FlowWidget/popover_assets/js/flowwidget.js"
  data-siteid="YOUR_SITEID"
  data-mode="popover"
  data-visitor-context='{"account_id":"USR-84920","plan":"Pro","ims_username":"Jane Smith","ims_email":"jane@example.com"}'
></script>

When generating this server-side, always HTML-encode the JSON string and use single quotes for the attribute so that double quotes inside the JSON are safe:

<?php
$context = json_encode([
    'account_id'   => $user->id,
    'plan'         => $user->plan,
    'ims_username' => $user->full_name,
    'ims_email'    => $user->email,
]);
?>
<script
  src="https://dashboard.imsupporting.com/public_FlowWidget/popover_assets/js/flowwidget.js"
  data-siteid="YOUR_SITEID"
  data-mode="popover"
  data-visitor-context='<?= htmlspecialchars($context, ENT_QUOTES, 'UTF-8') ?>'
></script>

Option B — window.imsFlowConfig object

Define a global configuration object before the widget script tag. Useful if your page generates JavaScript configuration dynamically or needs to integrate with a content-security-policy nonce.

<script>
  window.imsFlowConfig = {
    siteid: 'YOUR_SITEID',
    mode:   'popover',
    visitorContext: {
      account_id:   'USR-84920',
      plan:         'Pro',
      ims_username: 'Jane Smith',
      ims_email:    'jane@example.com'
    }
  };
</script>
<script src="https://dashboard.imsupporting.com/public_FlowWidget/popover_assets/js/flowwidget.js"></script>

4) Pre-Fill Keys (ims_*)

Any key that begins with ims_ is treated as a reserved field by the workflow engine. When the visitor reaches a step that would normally ask for one of these values, the step is automatically skipped — the field is answered silently using the pre-filled value.

This means a logged-in user who is already known to your system will jump straight to the conversation, bypassing prompts like "What is your name?".

Reserved pre-fill keys

Non-reserved keys

Any key that does not start with ims_ is treated as informational metadata — stored and shown to the operator, but not used to skip workflow steps. Use any key name you like, for example: account_id, plan, company, crm_ref.

Key naming rules

• Keys may contain letters, numbers, underscores (_), and hyphens (-).
• Spaces and special characters are not permitted and will be rejected by the server.
• Keys are case-sensitive: ims_email and ims_Email are different. Always use lowercase ims_* keys.
• Values must be strings. Numbers and booleans are accepted but converted to strings automatically.
• Maximum key length: 100 characters. Maximum value length: 500 characters.
• Maximum total context object size: 20,000 characters (base64-encoded).

5) Workflow Integration

The pre-fill system works automatically with any workflow step that collects user identity data. No change is required to your workflow configuration — if the relevant ims_* key is present, the step is silently skipped.

Supported node types

Workflow design recommendations

• Keep data-collection nodes in the workflow even for authenticated users. The node is skipped automatically when context is supplied; it is still shown for anonymous visitors.
• Use form_field nodes with field_name set to visitor_name, visitor_email, or visitor_phone to benefit from pre-fill automatically.
• Custom field names will not be auto-mapped to the ims_* pre-fill keys. Stick to the documented field names or test custom mappings in the Workflow Preview tool.

6) PHP Server-Side Example

A production-ready PHP snippet that reads data from the current user session and outputs the widget with visitor context. Adapt the property names to match your application's user model.

Generic PHP

<?php
/**
 * IMSupporting Flow Widget — server-side context injection.
 * Place this in your page template after the user is authenticated.
 */

$widgetContext = [];

if (isset($_SESSION['user'])) {
    $u = $_SESSION['user'];

    // Reserved ims_* keys trigger workflow pre-fill
    $widgetContext['ims_username']  = $u['display_name'];
    $widgetContext['ims_email']     = $u['email'];
    $widgetContext['ims_telephone'] = $u['phone'] ?? '';

    // Any other keys are shown to operators as metadata
    $widgetContext['account_id'] = $u['id'];
    $widgetContext['plan']       = $u['subscription_tier'];
    $widgetContext['company']    = $u['company_name'] ?? '';
    $widgetContext['last_login'] = date('Y-m-d H:i', strtotime($u['last_login']));
}

// Encode safely for HTML attribute output
$contextJson = json_encode($widgetContext, JSON_UNESCAPED_UNICODE);
$contextAttr = htmlspecialchars($contextJson, ENT_QUOTES | ENT_HTML5, 'UTF-8');
?>

<!-- Widget embed — output near closing </body> tag -->
<script
  src="https://dashboard.imsupporting.com/public_FlowWidget/popover_assets/js/flowwidget.js"
  data-siteid="<?= htmlspecialchars($yourSiteId, ENT_QUOTES, 'UTF-8') ?>"
  data-mode="popover"
  <?php if (!empty($widgetContext)): ?>
  data-visitor-context='<?= $contextAttr ?>'
  <?php endif; ?>
></script>

WordPress / WooCommerce

<?php
/**
 * Add to your theme's functions.php or a site-specific plugin.
 * Outputs the IMSupporting widget in wp_footer with WP user context.
 */
add_action('wp_footer', 'imsupporting_widget_output');

function imsupporting_widget_output() {
    $siteid  = 'YOUR_SITEID'; // replace with your site ID
    $context = [];

    if (is_user_logged_in()) {
        $user = wp_get_current_user();

        $context['ims_username'] = $user->display_name;
        $context['ims_email']    = $user->user_email;
        $context['wp_user_id']   = $user->ID;
        $context['wp_role']      = implode(', ', $user->roles);

        // WooCommerce: add last order number if available
        if (function_exists('wc_get_customer_last_order')) {
            $last_order = wc_get_customer_last_order($user->ID);
            if ($last_order) {
                $context['last_order'] = '#' . $last_order->get_order_number();
            }
        }
    }

    $attr = '';
    if (!empty($context)) {
        $attr = " data-visitor-context='"
              . esc_attr(json_encode($context, JSON_UNESCAPED_UNICODE))
              . "'";
    }

    echo '<script src="https://dashboard.imsupporting.com/public_FlowWidget/popover_assets/js/flowwidget.js"'
       . ' data-siteid="' . esc_attr($siteid) . '"'
       . ' data-mode="popover"'
       . $attr
       . '></script>' . "\n";
}
?>

7) Security & Validation

Visitor context is transmitted as a base64-encoded JSON payload attached to the widget's initialisation URL. The server applies several layers of validation before accepting or storing any data.

Server-side validation rules

What never gets exposed to other visitors

Visitor context data is tied to the individual chat session via the unique jsSessionId. It is:

• Stored per-session and never returned to client-side JavaScript after submission
• Scoped by siteid — operators on different sites cannot see each other's visitor data
• Excluded from end-user chat transcript emails — only the operator-facing dashboard displays visitor context

8) Frequently Asked Questions

Next Steps