Connect Kustomer

Bring Kustomer conversations, messages, and customer records into Fibric as governed events, and let operators write notes and status changes back idempotently. This guide covers creating a role-scoped API key, installing the cn-kustomer connector, granting capabilities, verifying that events flow, and diagnosing the failures you are most likely to hit.

The cn-kustomer connector runs in production today under BearScope, Fibric's flagship product, on live specialty-commerce conversations. It senses conversations and messages as they arrive and change, customer records with order and contact history, and SLA state, satisfaction scores, and reopen events. Acting, it writes notes to a conversation, updates status and assignment, and syncs call status from your voice platform onto the customer timeline. Every write is idempotent: a retried note is a safe no-op, never a duplicate. See Connectors for the general model.

#Prerequisites

In Kustomer, go to Settings → Security → API Keys and create a new key. Kustomer keys carry roles, and each role expands to a set of org permissions. Do not use an admin key: create a key whose roles grant exactly the permissions below and nothing more. The connector fails closed on anything it was not granted, so an over-scoped key buys no capability, only risk.

#Required permissions

Name the key so its purpose is obvious in an audit six months from now, for example fibric-connector-prod. Copy the key once at creation; Kustomer does not show it again.

Add cn-kustomer from the marketplace and bind it to the support role. Operators ask for support capabilities such as conversation.note.write, never for Kustomer by name, so a later move to another support platform is a rebinding, not a rewrite. The CLI walks the handshake the connector's auth declares: an API key prompt, because the connector is defined with auth: apiKey(). The key goes directly into your tenant's secret store; the CLI never writes it to disk.

# find the connector, then install it bound to the support role
fibric connectors search kustomer
fibric connectors add cn-kustomer --as support \
    --connection kustomer-prod \
    --config '{"subdomain":"acme"}'

#Configuration parameters

Non-secret configuration is passed with --config and lands in the connector's ctx.config. Credentials never go here.

Installing a connector exposes capabilities; it grants nothing. An operator gets exactly the capabilities you list in its manifest, and the deterministic executor blocks anything else by omission. List what the connection now exposes:

fibric capabilities ls

Grant an operator the read capabilities it senses through and only the writes its job needs. A triage analyst that reads conversations and leaves notes needs two capabilities, not five. The Capabilities page covers the indirection in full; Build an ops analyst is a worked example against this connector.

Writes also need a trust policy. Policy is fail-closed: an action with no matching rule is blocked, and you get the blocking rule by omission rather than by writing it. Apply and validate before anything runs live:

# governs writes back into Kustomer. default is deny.
policy: support-writes
rules:
  - allow: conversation.note.write
    limit:
      per: hour
      max: 100
    single_flight: conversation_id   # one write in flight per conversation
  - allow: conversation.status.write
    limit:
      per: hour
      max: 25
default: deny

fibric policy apply ./policy.yaml
fibric policy validate support-writes

Send a test message into any Kustomer conversation, then tail the event stream. Each Kustomer change arrives as a tenant-scoped event envelope with source: "kustomer" and a dotted event_type.

fibric events tail --source kustomer

#Emitted event types

Then confirm the write path with a dry run. Side-effecting tools dry-run by default: input validation and the trust evaluation execute, the handler does not.

fibric connectors test cn-kustomer note.write \
    --connection kustomer-prod \
    --args '{"conversation_id":"cnv_63k1","body":"connectivity check"}'

The connector's event streams declare a delivery kind, webhook or poll, in the connector definition. Webhooks are the primary path for conversation and message events: Kustomer pushes changes as they happen, and Fibric verifies and deduplicates each delivery. The poll backfill runs alongside at poll_interval and covers what webhooks structurally miss: changes made while a webhook endpoint was unreachable, resources with no webhook topic, and the initial history read when backfill_since is set.

Both paths feed the same envelope stream, and deduplication keys on the underlying resource change, so a change seen by both paths lands once. You do not choose between them; you tune the poll interval. A shorter interval narrows the worst-case gap for poll-only streams at the cost of more API calls against your Kustomer rate limit. For webhook endpoint mechanics and signature verification, see Receive webhooks reliably.

#Common failures

Every failure below is visible in fibric connectors test output or in receipts; the connector's probe reports the first three on install.

#Next steps

• Build an ops analyst: an operator that reads these conversations and reports what it sees.
• Catch order risk early: pair Kustomer with Magento so conversation context meets order state. Connect the store with Connect Magento.
• Write guardrails that hold: the trust policy patterns behind step 3.
• Events API: the same stream, programmatically.
• Tenancy & isolation: how every envelope stays walled inside your tenant.