Data Formatting

Format your unstructured data — chats, calls, reviews, emails — as message objects that Dimension can ingest, enrich, and report on.

A minimal valid message looks like this:

{
  "text": "I want to know where to track my deliveries",
  "userId": "7675836189527716",
  "incoming": true,
  "conversationId": "conv-88213407",
  "sessionId": "1434868331",
  "dimensionlabs_timestamp": 1703240320000
}

The rest of this page explains each field, the optional metadata that improves enrichment quality, and complete example payloads.

Prerequisites

Before you format your data, make sure you have:

• Retrieved the raw data from your source platform. See Retrieving your data.
• A Dimension Labs API key. See Generating a Dimension Labs API Key.
• A plan for where you will send the formatted data. See Sending your data to Dimension.

1. Add the required fields

Every message must include these six fields:

2. Identify the participants

userId identifies who sent the message:

• Bot conversations. Use the end user's ID for both incoming and outgoing messages — not the bot's ID.
• Multi-participant conversations. In a live chat with a human agent and a customer, use each participant's own ID.
• Omni-channel integrations. When records from multiple channels are included in a single integration.

incoming marks the direction. Regardless of integration source, incoming: true always represents the portion of a record or transcript that comes from the customer or end user; incoming: false covers messages from your bot, system, or human agents.

Direction also determines which endpoint you post to. See Sending your data to Dimension.

3. Group messages into conversations and sessions

conversationId and sessionId work together but answer different questions:

The two fields often cover the same span of messages and almost always will share a value. As a result these sometimes appear duplicative, however, each are necessary.

🧵

Always send conversationId. Without it, sessions fragment each time the userId changes — for example, when a human agent joins a live chat.

4. Set the timestamp

dimensionlabs_timestamp is a UNIX timestamp in milliseconds.

⏱️

A seconds-based timestamp will be interpreted as a date in 1970. The realtime endpoints require a timestamp within 24 hours of the time of sending; this does not apply to file uploads, which go directly to the historical endpoint.

To use your server's receive time instead of a message-level timestamp, see Setting Timestamps.

5. Attach optional metadata

You are likely already collecting metadata such as intents, events, scores, and contextual attributes. None of it is required, but passing it through produces higher-fidelity enrichments, insights, and visualizations.

Optional: Platform metadata

platformJson is a catch-all for any metadata you wish to share about the record: platform-specific message JSON, CSAT or NPS scores, experience ratings, weather conditions, game series — anything broadly relevant to the data.

{
  "platformJson": {
    "channel": "webchat",
    "csatScore": 4,
    "weatherConditions": "rain",
    "gameSeries": "home-opener"
  }
}

• platformJson is viewable in transcripts. Reporting on this data requires the Enterprise plan.
• platformJson is required if you are ingesting structured metadata for the Agentic workflow.

Optional: User attributes

Send user-specific attributes — name, locale, zipcode, A/B test group — in platformUserJson. Example fields to include:

{
  "platformUserJson": {
    "firstName": "Dana",
    "lastName": "Nguyen",
    "locale": "en-CA",
    "timezone": "America/Toronto",
    "customerTier": "silver"
  }
}

• Some 1-click integrations (e.g., Intercom/Fin) include information in PlatformUserJson automatically.

📌

platformJson is the general-purpose container — it is the preferred location for all metadata and fields beyond those required at the top level. platformUserJson is specifically for attributes of the person/customer in limited instances when keeping this information separate is meaningful or relevant.

Optional: Intent metadata

The intent object describes the recognized intent for a message. Intents are an optional, advanced feature — for the full guide, including the universal NotHandled intent and event tracking, see Tracking Intents and Events.

Each object in inputs has two fields:

{
  "intent": {
    "name": "TRACK_ORDER",
    "confidence": 0.948014021,
    "inputs": [
      {
        "name": "orderNumber",
        "value": "DM34137KMX"
      }
    ]
  }
}

Optional: Rich content

If your messages include images or interactive elements, format them as follows.

{
  "images": [
    { "url": "https://example.com/product-photo.jpg" }
  ]
}

{
  "buttons": [
    {
      "id": "btn-track",
      "label": "Track my order",
      "value": "TRACK_ORDER"
    }
  ]
}

{
  "postback": {
    "buttonClick": {
      "buttonId": "btn-track"
    }
  }
}

Complete examples

The intent objects below include confidence for illustration. It is optional — omit it if your platform does not produce a confidence score.

[
  {
    "text": "hey",
    "userId": "7675836189527716",
    "incoming": true,
    "conversationId": "conv-88213407",
    "sessionId": "1434868331",
    "dimensionlabs_timestamp": 1703240310000,
    "intent": {
      "name": "HELLO",
      "confidence": 0.963456013
    }
  },
  {
    "text": "Hi! How can I help you?",
    "userId": "7675836189527716",
    "incoming": false,
    "conversationId": "conv-88213407",
    "sessionId": "1434868331",
    "dimensionlabs_timestamp": 1703240315000,
    "intent": {
      "name": "HELLO_RESPONSE"
    }
  },
  {
    "text": "I want to know where to track my deliveries",
    "userId": "7675836189527716",
    "incoming": true,
    "conversationId": "conv-88213407",
    "sessionId": "1434868331",
    "dimensionlabs_timestamp": 1703240320000,
    "intent": {
      "name": "TRACK_ORDER",
      "confidence": 0.948014021
    }
  },
  {
    "text": "You can track your order anytime at example.com/orders.",
    "userId": "7675836189527716",
    "incoming": false,
    "conversationId": "conv-88213407",
    "sessionId": "1434868331",
    "dimensionlabs_timestamp": 1703240325000,
    "intent": {
      "name": "TRACK_ORDER_RESPONSE"
    }
  }
]

🔒

If your data contains personally identifiable information it is possible to redact it before sending. See PII Redaction Information.

Next steps