API reference
Help centerCommunityDevelopersAcademyStatus

Prepare signal content for real-time import to Connect

To import behavioral signals generated by external libraries to Connect, make sure they meet the predefined format. This is the same format that native signals from the Connect library follow.

The mutation is described in Enable real-time import of behavior signals for contacts.

Signal types and subscription availability

All subscriptions (Pro, Premium, Ultimate)

  • Add-to-cart signal
  • Identification signal
  • Order signal

Premium and Ultimate only

  • Browse abandonment signal
  • Cart abandonment signal
  • Error signal
  • On-site search signal
  • Page view signal
  • Product configuration signal
  • Product view signal
  • Rich media interaction signal

Add-to-cart signal

Triggered when a visitor adds products to their cart. 

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "addToCart"
          category: "Behavior"
          name: "Add product to cart in online store"
          effect: "positive"
          currency: "USD"
          productId: "AC-PNT-WHT-SM"
          productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
          itemQuantity: 2
          unitPrice: 39.99
          discount: 7
          productCategory: "Painting & Decorating / Paint"
          productUrls: [
            "https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint"
            "https://www.example.com/painting-and-decorating/must-haves/awesome-colors-interior-satin-paint"
          ]
          imageUrls: ["https://www.example.com/images/awesome-colors-paint.jpg"]
          shoppingCartUrl: "https://www.example.com/cart"
          signalTimestamp: "2025-08-31T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • currency: String - Price currency. Valid values: ISO 4217 currency codes. Examples: "USD", "EUR", "GBP".
  • itemQuantity: Number (integer) - Quantity of product added to cart
  • productId: String - Product identifier (may match SKU)
  • productName: String - Product name
  • signalType: String - Signal type (valid value: addToCart)
  • unitPrice: Number - Unit price of the product

Optional fields

  • category: String - Signal category (valid values: Behavior)
  • description: String - Description of the signal
  • discount: Number - Discount amount or difference between original and current price
  • imageUrls: Array of strings - Product image URLs
  • effect: String - Signal engagement effect (valid values: negative, positive).
  • name: String - Signal name to differentiate from other signals. Max length - 256 chars.
  • productCategory: String - Product category based on catalog
  • productCategoryId: String - Product category identifier
  • productDescription: String - Product description
  • productUrls: Array of strings - Product page URLs
  • promotionId: String - ID from marketing campaigns (hero images, CTAs) that led to this action
  • shoppingCartUrl: String - Shopping cart URL
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-08-31T08:29:30.001Z.
  • virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")

Browse abandonment signal

Indicates strong interest in a product without addition to cart or purchasing. For example, a user viewed a product, selected a size but didn't take further action.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "SESS-789456123ABC"
        signalContent: {
          signalType: "browseAbandonment"
          category: "Behavior"
          name: "Browse abandonment on outdoor furniture"
          effect: "negative"
          currency: "USD"
          abandonmentReason: "EXCESSIVE_SCROLLING"
          abandonmentReasonDescription: "User scrolled through 35 products without engagement"
          promotionId: "SUMMER2025"
          abandonedItems: [
            {
              productId: "OUT-CHAIR-TEAK-001"
              productName: "Premium Teak Outdoor Dining Chair"
              productDescription: "Weather-resistant teak wood dining chair with cushions"
              unitPrice: 249.99
              inventoryQuantity: 24
              productCategory: "Outdoor Living / Furniture / Dining"
              productUrls: ["https://www.example.com/outdoor/furniture/dining/teak-chair"]
              imageUrls: [
                "https://www.example.com/images/teak-chair-front.jpg"
                "https://www.example.com/images/teak-chair-side.jpg"
              ]
            }
            {
              productId: "OUT-TABLE-ALU-002"
              productName: "Aluminum Extendable Patio Table 84 Inch"
              productDescription: "Rust-proof aluminum table extends to seat 8-10 people"
              unitPrice: 899.99
              inventoryQuantity: 8
              discount: 100.00
              productCategory: "Outdoor Living / Furniture / Dining"
              productUrls: ["https://www.example.com/outdoor/furniture/dining/aluminum-table-84"]
              imageUrls: [
                "https://www.example.com/images/alu-table-closed.jpg"
                "https://www.example.com/images/alu-table-extended.jpg"
              ]
              promotionId: "SUMMER2025"
            }
            {
              productId: "OUT-UMBERELLA-BLK-003"
              productName: "Cantilever Patio Umbrella 11 Foot Black"
              productDescription: "UV-resistant fabric with 360-degree rotation base"
              unitPrice: 329.99
              inventoryQuantity: 3
              productCategory: "Outdoor Living / Furniture / Accessories"
              productUrls: ["https://www.example.com/outdoor/furniture/accessories/cantilever-umbrella-11ft"]
              imageUrls: ["https://www.example.com/images/umbrella-black-11ft.jpg"]
            }
          ]
          signalTimestamp: "2025-11-10T16:22:15.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • currency: String - Price currency. Valid values: ISO 4217 currency code (for example, "USD", "EUR", "GBP").
  • signalType: String - Signal type. Valid value: browseAbandonment.

Optional fields

  • abandonmentReason: String - Reason for abandonment. Valid values: APPLICATION_ERROR, LARGEST_CONTENTFUL_PAINT, CUMULATIVE_LAYOUT_SHIFT, FIRST_INPUT_DELAY, RAGE_CLICK, USER_ERRORS, EXCESSIVE_SCROLLING.
  • abandonmentReasonDescription: String - Additional description of the abandonment reason
  • abandonedItems: Array of objects - List of items that the user interacted with but didn't add to the cart
  • category: String - Signal category. Valid value: Behavior.
  • description: String - Description of the signal
  • name: String - Name to differentiate this signal from others (for example, "Browse abandonment on product listing page"). Max length: 256 chars.
  • promotionId: String - Promotion identifier associated with the browse session
  • productCategoryId: String - Product category identifier
  • signalTimestamp: String - ISO 8601 timestamp when the signal occurred (for example, 2025-08-31T08:29:30.001Z).

Descriptions of the abandonment reasons:

  • APPLICATION_ERROR - The user encountered a technical error in the application such as "404 - Page not Found".
  • CUMULATIVE_LAYOUT_SHIFT - The page layout shifted unexpectedly, disrupting the user experience.
  • EXCESSIVE_SCROLLING - The user scrolled excessively, possibly searching for information or due to poor design.
  • FIRST_INPUT_DELAY - There was a significant delay between the user's first interaction and the app's response.
  • LARGEST_CONTENTFUL_PAINT - The page took too long to load frustrating the user.
  • RAGE_CLICK - The user repeatedly clicked on a UI element out of frustration.
  • USER_ERRORS - There were validation errors such as form entry mistakes which led to frustration.

Abandoned items object

Objects in the abandonedItems array can include the following fields:

  • discount (optional): Number - Discount applied to the item
  • imageUrls (optional): Array of strings - URLs of product images
  • inventoryQuantity (optional): Number - Available inventory quantity
  • itemQuantity (optional): Number - Quantity of items
  • productCategory (optional): String - Product category from catalog
  • productDescription (optional): String - Description of the product
  • productId (required): String - Unique product identifier
  • productName (required): String - Name of the product
  • productUrls (optional): Array of strings - URLs of product pages
  • promotionId (optional): String - Associated promotion identifier
  • shoppingCartUrl (optional): String - URL of the shopping cart
  • unitPrice (required): Number - Price per unit
  • virtualCategory (optional): String - Category based on navigation path (e.g., "New arrivals", "Sale")

Cart abandonment signal

Cart abandonment occurs when there is an add-to-cart behavior in a session without an order before the session expires. 

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "SESS-789456123ABD"
        signalContent: {
          signalType: "cartAbandonment"
          currency: "USD"
          abandonedCartValue: 159.97
          abandonmentReason: "USER_ERRORS"
          abandonmentReasonDescription: "Payment form validation errors"
          shoppingCartUrl: "https://www.example.com/cart"
          abandonedItems: [
            {
              productId: "AC-PNT-WHT-SM"
              productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
              productDescription: "Premium interior paint with satin finish"
              unitPrice: 39.99
              itemQuantity: 2
              discount: 5.00
              productCategory: "Painting & Decorating / Paint"
              productUrls: ["https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint"]
              imageUrls: ["https://www.example.com/images/awesome-colors-paint.jpg"]
              shoppingCartUrl: "https://www.example.com/cart"
            }
            {
              productId: "BR-2IN-PRO"
              productName: "Professional Paint Brush 2 Inch"
              productDescription: "High-quality synthetic bristle brush"
              unitPrice: 12.99
              itemQuantity: 3
              discount: 2.00
              productCategory: "Painting & Decorating / Tools"
              productUrls: ["https://www.example.com/painting-and-decorating/tools/professional-paint-brush-2in"]
              imageUrls: ["https://www.example.com/images/paint-brush-2in.jpg"]
              shoppingCartUrl: "https://www.example.com/cart"
            }
          ]
          signalTimestamp: "2025-11-07T14:45:22.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • abandonedCartValue: Number - Total value of the abandoned cart
  • currency: String - ISO 4217 currency code (for example, "USD", "EUR", "GBP").
  • signalType: String - Valid value: cartAbandonment.

Optional fields

  • abandonmentReason: String - Reason for abandonment. Valid values: APPLICATION_ERROR, LARGEST_CONTENTFUL_PAINT, CUMULATIVE_LAYOUT_SHIFT, FIRST_INPUT_DELAY, RAGE_CLICK, USER_ERRORS, EXCESSIVE_SCROLLING.
  • abandonmentReasonDescription: String - Additional description of the abandonment reason.
  • abandonedItems: Array of objects - List of items abandoned in the cart. Each object in the array can include:
    • productId: String - Product identifier (may match SKU)
    • productName: String - Product name
    • unitPrice: Number - Price per unit
    • productDescription: String - Product description
    • itemQuantity: Number - Quantity of product added to cart
    • discount: Number - Discount applied to the item
    • productCategory: String - Product category based on catalog
    • productUrls: Array of strings - Product page URLs
    • imageUrls: Array of strings - Product image URLs
    • shoppingCartUrl: String - Shopping cart URL
    • virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")
    • promotionId: String - ID from marketing campaigns (hero images, CTAs) that led to this action
    • productCategoryId: String - Product category identifier
  • category: String - Signal category. Valid value: Behavior.
  • description: String - Description of the signal
  • name: String - Name to differentiate this signal from others (for example, "Cart abandonment on checkout page"). Max length: 256 chars.
  • shoppingCartUrl: String - URL of the shopping cart page
  • signalTimestamp: String - ISO 8601 timestamp when the signal occurred (for example, 2025-08-31T08:29:30.001Z).

Descriptions of the abandonment reasons:

  • APPLICATION_ERROR - The user encountered a technical error in the application such as "404 - Page not Found".
  • CUMULATIVE_LAYOUT_SHIFT - The page layout shifted unexpectedly, disrupting the user experience.
  • EXCESSIVE_SCROLLING - The user scrolled excessively, possibly searching for information or due to poor design.
  • FIRST_INPUT_DELAY - There was a significant delay between the user's first interaction and the app's response.
  • LARGEST_CONTENTFUL_PAINT - The page took too long to load frustrating the user.
  • RAGE_CLICK - The user repeatedly clicked on a UI element out of frustration.
  • USER_ERRORS - There were validation errors such as form entry mistakes which led to frustration.

Error signal

Sent when a user encounters an error on your site. Focus on payment, promo code, and account registration errors that lead users away from the happy path.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "error"
          category: "Behavior"
          name: "Shopping cart error"
          effect: "negative"
          errorText: "This promo code is invalid."
          errorType: "USER"
          errorIdentifier: "promoCode"
          signalTimestamp: "2025-08-31T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • errorText: String - Error message content received
  • errorType: String - Error type (valid values: application, user) - Application errors are server-side/system errors; user errors occur when input doesn't pass validation.
  • signalType: String - Signal type (valid value: error)

Optional fields

  • category: String - Signal category (valid value: Behavior)
  • description: String - Description of the signal
  • effect: String - Signal engagement effect (valid values: negative, positive) - We suggest negative for all error signals.
  • errorIdentifier: String - Error identifier (e.g., "promoCode")
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Identification signal

Captures visitors' emails or client/contact IDs as they browse your website.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "identification" 
          category: "Behavior"
          name: "Identification from login"
          effect: "positive"
          identifierName: "email"
          identifierValue: "[email protected]" 
          identificationFromLogin: true
          signalTimestamp: "2025-10-01T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • identifierName: String - Identifier type (valid values: email, sms, contactKey)
  • identifierValue: String - Contact information associated with visitor (type depends on identifierName value)
  • signalType: String - Signal type (valid value: identification)

Optional fields

  • category: String - Signal category (valid value: Behavior)
  • description: String - Description of the signal
  • effect: String - Signal interpretation for engagement index scoring (valid values: negative, positive)
  • identificationFromLogin: Boolean - Set to true if identifierValue derives from user authentication, false if from cookie/query string (separates explicit vs implicit identification)
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

On-site search signal

Records search terms website visitors use and number of results they get.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { sms: "+37455190000" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "onSiteSearch"
          category: "Behavior"
          name: "Product search in online store"
          effect: "positive"
          searchTerm: "paint with satin finish"
          numberOfResults: 9
          signalTimestamp: "2025-08-31T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • numberOfResults: Number (integer) - Number of results matching the search term
  • searchTerm: String - Word or phrase the visitor searched for
  • signalType: String - Signal type (valid value: onSiteSearch)

Optional fields

  • category: String - Signal category (valid value: Behavior)
  • description: String - Description of the signal
  • effect: String - Signal engagement effect (valid values: negative, positive) - Send positive if search returns results, negative if no results.
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Order signal

Comes each time a contact places an order on your website. Includes total amount and detailed breakdown by product.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "order"
          category: "Behavior"
          name: "Online store order"
          effect: "positive"
          currency: "USD"
          orderId: "02937-2025-XIA"
          orderSubtotal: 89.47
          orderShippingHandling: 15.45
          orderTax: 4.47
          orderDiscount: 0
          orderValue: 98.44
          signalTimestamp: "2025-08-31T08:29:30.001Z"
          orderedItems: [
            {
              productId: "AC-PNT-WHT-SM"
              productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
              unitPrice: 39.99
              itemQuantity: 2
              currency: "USD"
              discount: 7
              productCategory: "Painting & Decorating / Paint"
              productUrls: [
                "https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint"
                "https://www.example.com/painting-and-decorating/bestsellers/awesome-colors-interior-satin-paint"
              ]
              shoppingCartUrl: "https://www.example.com/cart"
              virtualCategory: "Sale"
            }
            {
              productId: "AC-DBL-BRSH-6"
              productName: "AWESOME COLORS Double Thick Chip Paint Brush"
              unitPrice: 9.49
              itemQuantity: 1
              currency: "USD"
              discount: 0
              productCategory: "Painting & Decorating / Tools"
              productUrls: [
                "https://www.example.com/painting-and-decorating/tools/awesome-colors-double-brush"
                "https://www.example.com/painting-and-decorating/must-haves/awesome-colors-double-brush"
              ]
              shoppingCartUrl: "https://www.example.com/cart"
              virtualCategory: ""
            }
          ]
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • currency: String - Order currency (valid values: ISO 4217 currency codes)
  • orderId: String - Order identifier
  • signalType: String - Signal type (valid values: order)

Optional fields

  • category: String - Signal category (valid value: Behavior)
  • description: String - Description of the signal
  • effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all order signals.
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • orderDiscount: Number - Discount from original price
  • orderedItems: Array of objects - Products in the order (separate object per product, not per instance - three identical items = one object with quantity: 3)
  • orderShippingHandling: Number - Shipping and handling amount
  • orderSubtotal: Number - Subtotal amount (net of discount)
  • orderTax: Number - Tax amount
  • orderValue: Number - Total order value
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Ordered items object

  • discount: Number - Discount amount per unit
  • imageUrls: Array of strings - URLs of product images
  • itemQuantity: Number - Quantity of this product purchased
  • productCategory: String - Product category from catalog
  • productCategoryId: String - Product category identifier
  • productDescription: String - Description of the product
  • productId (required): String - Unique product identifier (may match SKU)
  • productName (required): String - Name of the product
  • productUrls: Array of strings - URLs of product pages
  • promotionId: String - ID from marketing campaigns that influenced the purchase
  • shoppingCartUrl: String - URL of the shopping cart
  • unitPrice (required): Number - Price the customer paid for one unit
  • virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")

Page view signal

Registers page views as users browse your website.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { whatsapp: "+14035549090" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "pageView"
          category: "Behavior"
          name: "Page view from online store"
          effect: "positive"
          url: "https://www.example.com/painting-and-decorating/tools/"
          pageCategory: "Painting & Decorating"
          pageGroup: "Product Categories"
          signalTimestamp: "2025-10-28T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • signalType: String - Signal type (valid value: pageView)
  • url: String - URL of page user opened

Optional fields

  • category: String - Signal category (valid values: Behavior)
  • description: String - Description of the signal.
  • effect: String - Signal interpretation for engagement index scoring (valid values: negative, positive)
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • pageCategory: String - Category the page belongs to
  • pageGroup: String - A grouping for related pages
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)

Product configuration signal

Tracks interactions on product pages (selecting clothing size, checking FAQs/reviews, etc.) that suggest customer engagement.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "productConfiguration"
          category: "Behavior"
          name: "Product configuration from online store"
          effect: "positive"
          currency: "USD"
          productId: "AC-DBL-BRSH-6"
          productName: "AWESOME COLORS Double Thick Chip Paint Brush"
          configurationType: "Size selection"
          unitPrice: 9.49
          productCategory: "Painting & Decorating / Tools"
          signalTimestamp: "2025-08-31T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • currency: String - Product price currency (valid values: ISO 4217 currency codes)
  • productId: String - Product identifier (may match SKU)
  • productName: String - Product name
  • signalType: String - Signal type (valid value: productConfiguration)

Optional fields

  • category: String - Signal category (valid value: Behavior)
  • configurationType: String - Interaction label (name product parameter like size/color/quantity or identify UI element like dropdown)
  • description: String - Description of the signal
  • discount: Number - Discount amount
  • effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all product configuration signals.
  • imageUrls: Array of strings - URLs of product images
  • inventoryQuantity: Number (integer) - Number of units available
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • productCategory: String - Product category from catalog
  • productCategoryId: String - Product category identifier
  • productDescription: String - Description of the product
  • productUrls: Array of strings - URLs of product pages
  • promotionId: String - ID from marketing campaigns that influenced the purchase
  • shoppingCartUrl: String - URL of the shopping cart
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)
  • unitPrice: Number - Unit price of the product
  • virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")

Product view signal

Records user activity on product pages. Provides insights into product and category attention, crucial for segmentation and tying product interest to identified visitors.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "productView"
          category: "Behavior"
          name: "Product view from online store"
          effect: "positive"
          productId: "AC-DBL-BRSH-6"
          productName: "AWESOME COLORS Double Thick Chip Paint Brush"
          currency: "USD"
          unitPrice: 9.49
          availability: "In Stock"
          brandName: "Awesome Colors"
          discount: 0
          productCategory: "Painting & Decorating / Tools"
          inventoryQuantity: 150
          signalTimestamp: "2025-08-31T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • productId: String - Product identifier (may match SKU)
  • productName: String - Product name
  • signalType: String - Signal type (valid values: productView)

Optional fields

  • availability: String - Product availability status (e.g., "In Stock", "Out of Stock", "Back Order")
  • brandDescription: String - Brand description
  • brandName: String - Product brand name
  • categories: String - Product categories
  • category: String - Signal category (valid value: Behavior)
  • currency: String - Product price currency on website (valid values: ISO 4217 currency codes)
  • dateAdded: DateTime string - When product was added to catalog (format: yyyy-MM-dd HH:mm:ss.SSS)
  • description: String - Description of the signal
  • discount: Number - Discount from original price
  • effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all product views
  • imageUrls: Array of strings - Product image URLs
  • inventoryQuantity: Number (integer) - Number of units available
  • model: String - Model number or description
  • msrp: Number (decimal/float) - Suggested retail price or original price. Must be a decimal or float.
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • productCategory: String - Product category based on catalog
  • productCategoryId: String - Product category identifier
  • productDescription: String - Product description
  • productRating: Number - Product rating
  • productStatus: String - Product lifecycle state (e.g., "Active", "Discontinued", "Upcoming")
  • productUrls: Array of strings - Product page URLs
  • promotionId: String - ID from marketing campaigns (hero images, CTAs) that led to this view
  • shoppingCartUrl: String - Shopping cart URL
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)
  • sku: String - SKU (if different from product ID)
  • tags: Array of strings - Tags assigned to the product
  • unitPrice: Number - Unit price of product
  • virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")

Rich media interaction signal

Records user interactions with video and audio content on your website. Valuable for audience segmentation based on product/category interest.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "richMediaInteraction"
          category: "Behavior"
          name: "Video review interaction in online store"
          effect: "positive"
          mediaId: "jhaf6r76a"
          interactionType: "LAUNCH"
          mediaCategory: "video"
          mediaName: "How I used AWESOME COLORS Brush to paint the ceiling"
          url: "https://www.example.com/opinions/painting-and-decorating/"
          signalTimestamp: "2025-11-04T08:32:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

  • mediaId: String - Media file URL
  • signalType: String - Signal type (valid values: richMediaInteraction)

Optional fields

  • category: String - Signal category (valid values: Behavior)
  • description: String - Description of the signal
  • effect: String - Signal engagement effect (valid values: negative, positive) - Usually rich media interactions are positive signals
  • interactionType: String - User interaction type (valid values: load, launch, pause, continue, complete, stop, enlarge)
  • mediaCategory: String - Media category (e.g., "video")
  • mediaName: String - Audio or video file title
  • name: String (up to 256 characters) - Signal name to differentiate from other signals
  • signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
  • signalTimestamp: DateTime string (ISO 8601) - When signal happened (if omitted, Connect uses time when signal was received)
  • url: String - URL of page where media file is embedded

Related pages