Segment

1. Overview

Segment is a leading Customer Data Platform (CDP) that helps you collect, clean, and control your customer data. It provides a single API to track user data and send it to hundreds of tools for marketing, analytics, and data warehousing.

The Segment node in GoInsight allows you to integrate Segment's tracking capabilities directly into your automation workflows. You can programmatically capture user behaviors and identity data, enabling you to:

• Identify users: Tie a user to their actions and record traits about them (like email, name, or account type).
• Track events: Record actions users perform, such as "Order Completed" or "Article Read", along with rich properties.
• Track page views: Record website page views with associated context.
• Manage groups: Associate users with specific groups or organizations (e.g., for B2B account tracking).

2. Prerequisites

Before using the Segment node, please ensure you have the following:

• A valid Segment account.
• A Source created in your Segment workspace (typically a "HTTP API" or "Server" source).
• The Write Key for that source, which is required to authenticate your requests.

3. Credentials

For detailed guidelines on how to acquire and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Events, Groups, Identities, and Pages within Segment.

Operation Details

Track an Event

Record an event performed by a user using Segment track HTTP API.

Input Parameters:

• Event: The name of the event to track. Use 'Object + Past Tense Verb' format (e.g., 'Product Viewed', 'Order Completed'). Common examples: 'Product Viewed' (view product), 'Product Added' (add to cart), 'Order Completed' (complete order), 'Email Opened' (open email). Refer to Segment documentation for complete event naming conventions.

Options:

• UserId: The unique identifier of the user. If left empty, the system will automatically generate a random UUID as AnonymousId for visitor tracking.
• Properties: Event properties (key-value pairs) for recording detailed event information. Common property examples: 'product_id' (Product ID), 'price' (Price), 'currency' (Currency code like USD, CNY), 'category' (Product category). Refer to Segment documentation for complete property specifications.
• Context: Context values for providing additional environmental information. Common context fields: 'ip' (IP address), 'locale' (locale code), 'timezone' (timezone), 'userAgent' (user agent string). Refer to Segment documentation for complete context field specifications.
• AnonymousId: Anonymous user ID. Used when UserId cannot be obtained (e.g., visitor behavior tracking). Note: At least one of UserId or AnonymousId must be provided. If both are empty, the system will automatically generate a random UUID as AnonymousId.
• Timestamp: ISO 8601 format timestamp for the event occurrence time. If not provided, the system will use the current time. Format: 'YYYY-MM-DDTHH:MM:SS.sssZ' or 'YYYY-MM-DDTHH:MM:SS+HH:MM'.
• MessageId: Unique message identifier for deduplication. If not provided, Segment will automatically generate one.

Output:

• ResponseBody (object): The JSON response body returned by Segment API. Success structure: {"success": true}. Failure structure may contain error details (format depends on error type).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add a User to a Group

Add a user to a group in Segment using the HTTP API.

Input Parameters:

• GroupId: The unique identifier of the group in Segment.
  • Option 1: Call 'Segment - Create a Group' action to get a new group ID
  • Option 2: Use your existing group identifier from your CRM/database
  • Option 3: Use a consistent naming convention (e.g., 'company_{company_id}')

Options:

• UserId: The unique identifier of the user to add to the group. Required unless using anonymous tracking.
  • Each API call will generate a NEW anonymous user (no user tracking across calls)
  • Anonymous users cannot be merged with identified users later
  • Recommendation: Only use anonymous tracking for public/guest user scenarios (e.g., website visitors before login)
• Traits: Attributes related to the group (key-value pairs). Use this to enrich group data with business context.

  {
    "name": "Acme Inc",
    "industry": "Technology",
    "employees": 50,
    "plan": "enterprise",
    "website": "https://acme.com"
  }
  

• Context: Additional context information for the tracking event (key-value pairs). Used for device info, location, campaign tracking, etc.
  • Server-side API calls: You MUST manually provide ip, locale, timezone (Segment cannot auto-detect)
  • Browser/Mobile SDK: Leave empty, SDK will auto-detect all fields
  • Override defaults: Fill this only if you need to override SDK's auto-detected values

  {
    "ip": "192.168.1.1",
    "locale": "en-US",
    "timezone": "America/New_York",
    "campaign": {
      "source": "google",
      "medium": "cpc"
    }
  }
  

Output:

• ResponseBody (object): The parsed JSON response from Segment API.
  • code (string): Error code (e.g., 'invalid_write_key', 'missing_field')
  • message (string): Human-readable error message
  • field (string): The problematic field name (optional)

  {"success": true}
  

  {
    "code": "invalid_write_key",
    "message": "Write key is invalid or does not exist"
  }
  

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create an Identity

Identify a user in Segment by sending user traits to the identify API endpoint.

Options:

• UserId: The unique identifier of the user in your system (e.g., user123). Optional: If not provided, the system will automatically generate an anonymous ID (anonymousId) for tracking.
  • Required for logged-in users to link their behavior across devices/sessions
  • Leave empty for anonymous visitors (system generates UUID automatically)
• Email: User's email address. Commonly used unique identifier. Will be included in Traits.email automatically.

Example: user@example.com

• Name: User's full name. Will be included in Traits.name automatically.

Example: John Doe

• Traits: User attributes dictionary (key-value pairs). Used to identify user's business attributes and characteristics.
  • name: User's full name
  • email: Email address
  • phone: Phone number
  • plan: Subscription plan (free/pro/enterprise)
  • company: Company name
  • title: Job title
  • createdAt: Account creation time (ISO 8601 format)
  • address: Address object {city, country, postalCode}
  • Values can be: string, number, boolean, null, or nested objects/arrays
  • Maximum nesting depth: 3 levels (recommended by Segment)
  • Date values should use ISO 8601 format strings
• Context: Optional context information (key-value pairs). Used to supplement environmental data for better attribution and analysis.
  • ip: User's IP address (for geolocation)
  • userAgent: Browser User-Agent string
  • locale: Language region code (e.g., en-US, zh-CN)
  • timezone: Timezone (e.g., America/New_York)
  • app: Application info object {name, version, build}
  • device: Device info object {id, manufacturer, model}
  • os: Operating system info {name, version}
  • screen: Screen info {width, height, density}
  • Values can be: string, number, boolean, null, or nested objects/arrays
  • Maximum nesting depth: 3 levels (recommended by Segment)
  • Date values should use ISO 8601 format strings
• Timestamp: Optional event timestamp in ISO 8601 format. Used for backfilling historical data or specifying when the event occurred.
  • UTC time: 2024-01-15T10:30:00Z
  • With timezone: 2024-01-15T10:30:00-08:00
• MessageId: Optional message unique identifier (UUID format). Prevents duplicate data submissions.
  • When retrying failed requests (network timeout, etc.)
  • When bulk importing data to avoid duplicates
  • Leave empty for normal single submissions (system treats each call as new)

Output:

• Sent (bool): Indicates whether the HTTP request was actually sent to the Segment API.
• ResponseBody (object): The parsed JSON payload returned by the Segment API.
  • success (bool): Always true on success
  • success (bool): Always false on error
  • message (string): Human-readable error message
  • code (string): Machine-readable error code (e.g., invalid_writekey, invalid_payload)

  {"success": true}
  

  {
    "success": false,
    "message": "Invalid writeKey",
    "code": "invalid_writekey"
  }
  

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Track a Page

Record a page view event by sending page information to Segment page HTTP API.

Use Cases:

• Track user navigation across website pages
• Analyze popular content and user journey
• Measure page performance and engagement

User Identification:

• UserId: For logged-in users (recommended)
• AnonymousId: For anonymous visitors
• If both are empty, a random UUID will be auto-generated (not recommended for tracking)

Common Properties:

• url: Full page URL
• title: Page title
• referrer: Source page URL
• path: Page path (e.g., /pricing)
• search: URL query parameters

Options:

• UserId: Unique identifier of the logged-in user. If both UserId and AnonymousId are empty, system will auto-generate a random UUID as AnonymousId. Recommended to provide at least one identifier for accurate user tracking.
• AnonymousId: Unique identifier for anonymous users (not logged in). If both UserId and AnonymousId are empty, system will auto-generate a random UUID. Common use case: tracking visitors before they sign up or log in.
• Name: Name of the page being viewed. Use short, human-readable identifiers.
  • 'Home' (homepage)
  • 'Pricing' (pricing page)
  • 'Product Detail' (product details)
  • 'Checkout' (checkout page)
• Properties: Page-related properties (key-value pairs). Used to record additional metadata about the page.
  • url: Page URL (e.g., 'https://example.com/pricing')
  • title: Page title (e.g., 'Pricing Page')
  • path: URL path (e.g., '/pricing')
  • referrer: Referring page URL
  • search: Query parameters
• Context: Context information (key-value pairs). Used to record environment-related data.
  • ip: User's IP address (e.g., '8.8.8.8')
  • locale: Language code (e.g., 'en-US', 'zh-CN')
  • timezone: Timezone (e.g., 'Asia/Shanghai')
  • userAgent: Browser User-Agent string
  • campaign: Marketing campaign info (object)
  • name: Campaign name
  • source: Traffic source (e.g., 'google', 'facebook')
  • medium: Marketing medium (e.g., 'cpc', 'email')
  • term: Search keywords
  • content: Ad content identifier

Output:

• Sent (bool): Indicates whether the HTTP request was successfully sent to the Segment API (true) or failed before sending (false).
• ResponseBody (object): The JSON response body returned by Segment API.

Success response (HTTP 200):

{

"success": true

}

Error response (HTTP 4xx/5xx):

{

"error": {

"code": "invalid_request_error",

"message": "userId or anonymousId is required"

}

}

Returns empty object {} if response contains no JSON or parsing fails.

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a workflow to track a critical business event, such as a user completing an order. This is one of the most common use cases for Segment.

Workflow Overview: Start -> Segment (Track an Event) -> Answer

Step-by-Step Guide:

1. Add the Tool Node:
   • In your workflow canvas, click the "+" button to add a new node.
   • Select the "Tools" tab.
   • Search for and select Segment.
   • From the list of supported operations, choose Track an Event. This will add the node to your canvas.
2. Configure the Node:
   • Click on the Track an Event node to open its configuration panel.
   • Credentials: Select your configured Segment credentials (containing your Source Write Key).
   • Parameter Configuration:
   • Event: Enter a clear, past-tense event name, such as Order Completed.
   • UserId: Map this to the user's ID from your previous workflow steps (e.g., user_12345). This links the event to a specific user.
   • Properties: Enter a JSON object containing details about the order. For example:

   {
     "order_id": "ord_987",
     "total": 99.00,
     "currency": "USD",
     "products": [
       { "product_id": "prod_1", "sku": "sku_abc", "price": 99.00 }
     ]
   }
   

3. Run and Verify:
   • Ensure all required fields are filled and the error indicator disappears.
   • Click the "Run" button in the top right corner.
   • Once executed, check the node's logs. A successful operation will return a StatusCode of 200 and a ResponseBody containing {"success": true}. You should also see this event appear in the "Debugger" tab of your Segment workspace almost immediately.

Summary:

After completing these steps, your workflow will automatically send an "Order Completed" event to Segment whenever it runs, allowing you to analyze revenue and user behavior in your downstream tools.

6. FAQs

Q: Why am I not seeing my data in the Segment Debugger?

A: Please check the following:

• Write Key: Ensure you are using the correct Write Key for the specific Source you are checking.
• Environment: Verify you are looking at the correct workspace environment (e.g., Dev vs. Prod).
• Error Logs: Check the ErrorMessage output in the GoInsight node logs for any API rejection messages.

Q: What is the difference between UserId and AnonymousId?

A: They serve different tracking purposes:

• UserId: Used for identified, logged-in users. It should be a stable ID from your database.
• AnonymousId: Used for visitors who haven't logged in yet. Segment uses this to track sessions before a user identifies.

Q: Can I send custom data with my events?

A: Yes.

• Use the Properties field in Track an Event or Track a Page to send event-specific data (e.g., price, category).
• Use the Traits field in Create an Identity or Add a User to a Group to send user-specific data (e.g., email, age).

7. Official Documentation

Segment Official API Documentation