Implementation:Mage ai Mage ai Intercom Transform

Knowledge Sources	Mage Integrations Intercom API
Domains	Data_Integration, Intercom, Transform
Last Updated	2026-02-09 00:00 GMT

Overview

Data transformation functions for the Mage Intercom source connector, handling de-nesting of list nodes, conversation parts extraction, datetime conversion, and schema-based time normalization.

Description

This module provides a set of pure transformation functions used to reshape Intercom API response data into flat record structures suitable for Singer output. Key transformations include:

• denest_list_nodes - De-nests list-type nodes (e.g., companies, segments, social_profiles, tags) by replacing nested {node: {node: [...]}} structures with flat arrays at the record level.
• transform_conversation_parts - Extracts conversation parts from conversations, enriching each part with parent conversation metadata (conversation_id, conversation_created_at, conversation_updated_at, conversation_total_parts).
• transform_json - Orchestrates stream-specific transformations, applying different de-nesting strategies for users, companies, conversations, and conversation_parts.
• find_datetimes_in_schema - Recursively traverses a JSON schema tree to discover all date-time formatted fields, returning arrays of key paths.
• transform_times - Normalizes datetime values (strings, epoch seconds, epoch milliseconds) to a consistent epoch milliseconds format, handling nested and array paths.

Usage

Called during the sync process to transform raw API response data before Singer record emission.

Code Reference

Source Location

• Repository: mage-ai
• File: mage_integrations/mage_integrations/sources/intercom/transform.py
• Lines: 1-135

Signature

def denest_list_nodes(this_json, data_key, list_nodes):
def transform_conversation_parts(this_json, data_key):
def transform_json(this_json, stream_name, data_key):
def find_datetimes_in_schema(schema):
def transform_times(record, schema_datetimes):

Import

from mage_integrations.sources.intercom.transform import (
    transform_json, transform_times, find_datetimes_in_schema,
)

I/O Contract

Inputs

Function	Parameters	Description
denest_list_nodes	this_json (dict), data_key (str), list_nodes (list)	JSON response, data key, list of node names to de-nest
transform_conversation_parts	this_json (dict), data_key (str)	Conversations JSON response and data key
transform_json	this_json (dict), stream_name (str), data_key (str)	Raw JSON, stream name for routing, data extraction key
find_datetimes_in_schema	schema (dict)	JSON schema with properties and format fields
transform_times	record (dict), schema_datetimes (list)	Record to transform and list of datetime key paths

Outputs

Function	Return Type	Description
denest_list_nodes	dict	Modified JSON with flattened list nodes
transform_conversation_parts	list	Flat list of conversation part records with parent metadata
transform_json	list/dict	Transformed records extracted from the data_key
find_datetimes_in_schema	list[list]	Array of key-path arrays to datetime fields
transform_times	None	Modifies record in-place, normalizing datetimes to epoch milliseconds

Stream-Specific Transformations

Stream	De-nested Nodes
users	companies, segments, social_profiles, tags
companies	segments, tags
conversations	tags, contacts
conversation_parts	Extracted from conversations with parent metadata

Usage Examples

from mage_integrations.sources.intercom.transform import transform_json, transform_times, find_datetimes_in_schema

# Transform raw API response for users stream
transformed = transform_json(api_response, 'users', 'users')

# Normalize datetimes
schema_datetimes = find_datetimes_in_schema(stream_schema)
for record in transformed:
    transform_times(record, schema_datetimes)

Related Pages

Implements Principle

• Principle:Mage_ai_Mage_ai_Singer_Message_Emission

Requires Environment

• Environment:Mage_ai_Mage_ai_Python_3_9_Runtime