Sync Custom Data of Contacts to Knoon

Keep your agents informed with up‑to‑date customer context at the start of every conversation. Custom Data Sync attaches lightweight profile data to a Knoon Contact (e.g., purchase status, signup date) that agents and automations can read when a chat session begins.

IMPORTANT

Data is fetched once when the user signs in and may be stale while the conversation is ongoing. If the data changes frequently (e.g., order status, delivery ETA), use a Tool to fetch it on demand during the conversation instead of Data Sync.

What you can store

• Non‑sensitive profile attributes that help agents personalize support.

• Examples: purchaseStatus, plan, trialEndsAt, signedUpAtDateTime, hasActiveSubscription, ticketsOpen.

TERMS OF USE
You may include only limited identifying information necessary for user lookup — specifically, External ID (your system’s user ID) and email address. Beyond these, you must not store any sensitive Personally Identifiable Information (PII), including but not limited to residential addresses, bank account numbers, credit card details, or any similar financial identifiers.

Avoid collecting or transmitting government-issued IDs, medical information, or any data that could directly or indirectly identify a person beyond what is essential for support or user verification.

All stored data must comply with applicable privacy regulations and Knoon’s Terms of Use.

How it works (High‑level)

1. Knoon calls your endpoint at the start of a conversation with:

   • Authorization: Bearer <secret> header

   • JSON body containing externalId — your user’s ID in your system.

2. Your server validates the Bearer token, looks up the user by externalId, and returns a JSON payload with allowed fields.

3. Knoon attaches the returned fields to the Contact for agent visibility during the session.

Set up in Knoon (UI)

1. Go to Admin > Data Sync.

2. In “URL”, enter your HTTPS endpoint (e.g. https://api.example.com/knoon/_dataSync).

3. In “Request Headers”, add:

   • Key: Authorization

   • Value: Bearer <YOUR_DATA_SYNC_SECRET>

4. Save. (Your endpoint must accept POST requests with JSON.)

Tip: Rotate the secret periodically and treat it like a production credential. Store it in your server’s config as KNOON_SUPPORT_DATA_SYNC_SECRET (or similar).

Request (From Knoon → Your server)

Method: POST
Headers:

Authorization: Bearer <YOUR_DATA_SYNC_SECRET>
Content-Type: application/json

Body:

{
  "externalId": "USER_ID_IN_YOUR_SYSTEM"
}

• externalId should be a stable, unique identifier you can look up (e.g., Firebase UID, internal user ID).

Response (Your server → Knoon)

Return 200 OK with JSON:

{
  "status": "ok",
  "externalId": "USER_ID_IN_YOUR_SYSTEM",
  "displayName": "Optional Name",
  "photoURL": "https://.../avatar.png",
  "customData": {
    "purchaseStatus": "active",
    "plan": "Signature",
    "signedUpAtDateTime": "2024-05-01T12:34:56Z"
  }
}

Field rules

• status must be ok for successful responses.

• externalId mirrors the request value you resolved.

• displayName, photoURL are optional convenience fields.

• customData is an object of simple values (strings, numbers, booleans, ISO‑8601 timestamps). Keep it small and human‑readable.

Minimal server example (Node/Express‑style pseudocode)

// env: KNOON_SUPPORT_DATA_SYNC_SECRET
app.post('/knoon/_dataSync', async (req, res) => {
  const auth = req.get('Authorization') || ''
  const token = auth.startsWith('Bearer ') ? auth.split(' ')[1] : null
  if (!token || token !== process.env.KNOON_SUPPORT_DATA_SYNC_SECRET) {
    return res.status(403).json({ status: 'forbidden' })
  }

  const uid = req.body?.externalId
  if (!uid) return res.status(400).json({ status: 'bad_request' })

  // Look up your user (DB/Auth service)
  const user = await findUser(uid) // implement
  if (!user) return res.status(400).json({ status: 'bad_request' })

  const response = {
    status: 'ok',
    externalId: uid,
    displayName: user.name,
    photoURL: user.avatarUrl,
    customData: {
      purchaseStatus: user.purchase?.status ?? 'none',
      signedUpAtDateTime: user.createdAt?.toISOString?.()
    }
  }

  return res.json(response)
})

Mapping to Knoon Contact

• The externalId is used to associate the returned data with the corresponding Contact in Knoon.

• displayName and photoURL enhance the Contact’s profile card for agents.

• customData appears as key/value pairs accessible to agents and templates.

When to use a Tool instead

Use a Tool for dynamic data that changes during a chat (e.g., order status moving from processing → shipped). Tools can be invoked multiple times mid‑conversation, ensuring the agent (or AI) sees the latest values.