Hilo Customer Support DESIGN DOC

Hilo Customer Support - Design Document

Purpose: Problem in, action out - with context as the connective tissue.

Section 1: System Overview

What CS does - problem in, action out

Problem CS Internal Actions External Actions Device User Policy / KB

A problem comes in. CS reasons over device, user, and policy context, and emits a single action - either internal (operational) or external (customer-facing).

Problem · input CS · decision Context · information Action · output

Section 2: Actual Components

The same picture, with real systems - Intercom + Shopify + NetSuite + Hilo telemetry

Intercom Inbox email · chat · in-app · EN / FR / DE / IT · Intercom + Canvas Kit Internal Actions • Escalate / reassign - Intercom team routing • Engineering ticket - Jira • Complaint / fraud log - internal DB • KB gap capture - Intercom Articles • Resolve · no-action - close conversation • Agent note - Canvas Kit submit External Actions • Customer reply - Intercom message • Refund - Shopify refund API • RMA - NetSuite RMA module • Replacement order - NetSuite / Shopify • Remote device action - Hilo backend • Account / subscription - Shopify customer Hilo Telemetry serial · firmware battery · last sync Shopify customer · orders subscription · warranty NetSuite RMA · replacement inventory · refund post Knowledge Base / Policy SOPs · Intercom Articles · warranty & refund rules

Customer reaches Intercom. The Canvas Kit panel inside Intercom pulls device data (Hilo telemetry), commercial data (Shopify), and fulfilment data (NetSuite) - plus policy from the KB - and the agent picks one internal or external action.

Intercom Inbox · input Intercom + Canvas Kit · CS hub Telemetry · Shopify · NetSuite · KB · context Action systems · output

Section 3: Current State - Request Path

Freshdesk + manual lookups - what happens today, end-to-end, when a customer writes in. Identity threads through email only; context is gathered tab-by-tab. The diagram shows the round-trip for a typical "my cuff isn't syncing" ticket that becomes an RMA + refund.

Rendering…

Why this hurts:

  • 5+ systems, no shared identity. Agent re-keys email/serial across Freshdesk, Shopify, NetSuite, the Hilo admin, and the KB. Nothing auto-links.
  • Context lives in the agent's head. Device telemetry, order, warranty, prior RMAs - all pulled by hand, every time.
  • Customer is the bottleneck. Many tickets stall waiting on the customer to find the serial number on the back of the device.
  • Copy-paste is the integration layer. RMA #, addresses, refund amounts - all manually pasted between NetSuite, Shopify, and Freshdesk replies.
  • Multi-day wall-clock for a "simple" case. 5–15 min of agent time per touch, plus return shipping, then a separate touch to refund or ship a replacement.