Acoustic Connect can consume behavior signals originating from external systems in near real-time. These signals are processed just like native signals generated by the Connect library.

You can use external signals on their own without integrating our library into your application, or as an addition to native Connect signals. This is useful for merging signals from multiple sources when the Connect library doesn't have access to parts of the user journey that rely on third-party components (payment processors, ticket management solutions, etc.).

Requirements

Signal limits

Import signals supported by your Connect subscription.

Signal	Pro	Premium & Ultimate
Add-to-cart	✅	✅
Browse abandonment	❌	✅
Cart abandonment	❌	✅
Error	❌	✅
Identification	✅	✅
On-site search	❌	✅
Order	✅	✅
Page view	❌	✅
Product configuration	❌	✅
Product view	❌	✅
Rich media interaction	❌	✅

Contact mapping

Each signal must map to a contact using one of these attributes:

Contact key (for existing contacts)
Email address
Phone number (SMS or WhatsApp channel)

Batch size

Maximum 500 signals per mutation

Before you begin

Get your application key (it maps imported signals to an application).

Connect Pro: Key provided during onboarding
Connect Premium and Ultimate: Generate through Connect interface (see Get an application key for the Connect library)

Running the mutation

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Mutation arguments

signals (required): Array of objects - Create an object for each signal you want to import. See Signal object fields below.

Signal object

appKey (required): String - Your application identifier in Connect
identifiableAttributes (required): Object - Contact mapping attribute (see Identifiable attributes object below)
sessionId: String - Session ID for grouping signals from the same contact
signalContent (required): JSON object - Signal content
test: Boolean - Flag for importing test signals (default: false). For details, the How it works section at the bottom.

Identifiable attributes object

Use one of these fields to map signals to contacts:

contactKey: String - Contact key associated with the contact
email: String - Email address associated with the contact
sms: String - Phone number in SMS channel associated with the contact
whatsapp: String - Phone number in WhatsApp channel associated with the contact

Signal content object

The structure of the signalContent object depends on the type of signal you are importing.

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: "SESS-789456123AB"
        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-11-01T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

currency: String - Price currency. Valid values: ISO 4217 currency codes. Examples: "USD", "EUR", "GBP".
itemQuantity: Number - Quantity of product added to cart. Use integers.
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. We suggest using positive for all add-to-cart actions.
name: String - Signal name to differentiate from other signals. Max length - 256 chars.
productCategory: String - Product category name 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-11-01T08: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-789456123AB"
        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: Enum - 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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08: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 represent products the user viewed or interacted with. Supported fields:

discount: Number - Discount applied to the item
imageUrls: Array of strings - URLs of product images
inventoryQuantity: Number - Available inventory quantity
itemQuantity: Number - Quantity of items
productCategory: String - Product category name based on catalog
productCategoryId - String - Product category identifier
productDescription: String - Description of the product
productId (required): String - Unique product identifier
productName (required): String - Name of the product
productUrls: Array of strings - URLs of product pages
promotionId: String - Associated promotion identifier
shoppingCartUrl: String - URL of the shopping cart
unitPrice (required): Number - Price per unit
virtualCategory: 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-789456123AB"
        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-01T08:29:30.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: Enum - Reason for abandonment. Valid values: APPLICATION_ERROR, LARGEST_CONTENTFUL_PAINT, CUMULATIVE_LAYOUT_SHIFT, FIRST_INPUT_DELAY, RAGE_CLICK, USER_ERRORS, EXCESSIVE_SCROLLING. See the descriptions in the browse abandonment signal above.
abandonmentReasonDescription: String - Additional description of the abandonment reason.
abandonedItems: Array of objects - List of items abandoned in 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, "Cart abandonment on checkout page"). Max length: 256 chars.
shoppingCartUrl: String - URL of the shopping cart page
signalTimestamp: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.

Abandoned items object

Objects in the abandonedItems array represent products left in the cart. Supported fields:

discount: Number - Discount applied to the item
imageUrls: Array of strings - Product image URLs
itemQuantity: Number - Quantity of product added to cart
productCategory: String - Product category name based on catalog
productCategoryId: String - Product category identifier
productDescription: String - Product description
productId (required): String - Product identifier (may match SKU)
productName (required): String - Product name
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
unitPrice (required): Number - Price per unit
virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")

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: "SESS-789456123AB"
        signalContent: {
          signalType: "error"
          category: "Behavior"
          name: "Shopping cart error"
          effect: "negative"
          errorText: "This promo code is invalid."
          errorType: "USER"
          errorIdentifier: "promoCode"
          signalTimestamp: "2025-11-01T08: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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.

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: "SESS-789456123AB"
        signalContent: {
          signalType: "identification" 
          category: "Behavior"
          name: "Identification from login"
          effect: "positive"
          identifierName: "email"
          identifierValue: "[email protected]" 
          identificationFromLogin: true
          signalTimestamp: "2025-11-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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.

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: "SESS-789456123AB"
        signalContent: {
          signalType: "onSiteSearch"
          category: "Behavior"
          name: "Product search in online store"
          effect: "positive"
          searchTerm: "paint with satin finish"
          numberOfResults: 9
          signalTimestamp: "2025-11-01T08:29:30.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

numberOfResults: Number - Number of results matching the search term. Use integers.
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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.

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: "SESS-789456123AB"
        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-11-01T08: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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.

Ordered items object

Objects in the orderedItems array represent purchased products. Supported fields:

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 name based on product 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")

📘
Note
Create one object per product type, not per instance—three identical items should be one object with itemQuantity: 3.

Page view signal

Registers page views as users browse your website.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        identifiableAttributes: { whatsapp: "+14035549090" }
        sessionId: "SESS-789456123AB"
        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-11-01T08: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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.

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: "SESS-789456123AB"
        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-11-01T08: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 - Number of units available. Use integers.
name: String (up to 256 characters) - Signal name to differentiate from other signals
productCategory: String - Product category name based on 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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.
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: "SESS-789456123AB"
        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-11-01T08: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: Date - 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 - Number of units available. Use integers.
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 name 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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.
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: "SESS-789456123AB"
        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-01T08:29: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: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2025-11-01T08:29:30.001Z.
url: String - URL of page where media file is embedded

Response fields

The mutation returns a JSON response containing:

data: Object - The root data object containing the mutation results
- createSignals: Object - Contains the results of the signal creation operation
  - signalIds: Array of strings - UUIDs for each successfully imported signal (share with support for troubleshooting)

Verification methods

Method 1: Contact details

Log in to Acoustic Connect.
Navigate to Data management > Audience.
Select contact from All contacts tab.
Find signals in activity feed.

Notes:

Activity feed shows 5 most recent signals per session (identification signal not displayed)
Displays last 1000 signals or signals from last 30 days
Newly added signals may not be immediately visible

Method 2: Signal management

Navigate to Behavioral management > Signal management.
View all signal types supported by your subscription.
Click on signal types to see details.

Method 3: Sessions (Connect Ultimate only)

For Ultimate subscriptions with replay-able sessions generated by Connect library:

Navigate to Insights > Sessions > Session search.
Find session by ID and select it.
Click Inspect signals.
Review imported signal content.

🚧
Important
Sessions with external system-generated IDs are not searchable.

How it works

Required vs. optional fields

If any required field is missing or invalid, the entire signal will be discarded.
Optional fields enhance the signal but won't prevent processing if omitted or invalid. However, if you add optional arrays such as orderedItems for the order signal, they must contain all required fields.

Test signals

When test is set to true:

Signals go through standard validation
No impact on campaigns
Not visible in activity feed, Segmentation, or Insights

Session ID behavior

When you provide a sessionId:

System registers the session as if generated by Connect library
Signals included in aggregate reports and in-market interest calculation
System appends a timestamp to ensure uniqueness (e.g., OOII97671461Jgfa9999 becomes OOII97671461Jgfa9999.1751479037630)

When you skip sessionId:

Signals appear in contacts' activity feed
Signals aren't used for aggregate reports

Contact mapping behavior

When Connect receives a signal, it processes the value in the identifiableAttributes object to determine how to handle the signal:

Existing contact found: If there's a contact with that identifiable attribute (contact key, email, or phone number), the system maps the signal to that contact.
New contact w/ addressable attribute: If no contact exists but the identifiable attribute is addressable (email or phone number), the system creates a new contact in the audience and maps the signal to it.
New contact w/ contact key only: If no contact exists and the identifiable attribute is a contact key, the signal gets discarded (contact keys alone cannot create reachable contacts).

🚧
Important
All signal processing and contact mapping relies entirely on the identifiable attributes you provide. The system cannot process signals without proper identifiable attributes.

Requirements

Signal limits

Contact mapping

Batch size

Before you begin

Running the mutation

Mutation arguments

Signal object

Identifiable attributes object

Signal content object

Add-to-cart signal

Required fields

Optional fields

Browse abandonment signal

Required fields

Optional fields

Cart abandonment signal

Required fields

Optional fields

Error signal

Required fields

Optional fields

Identification signal

Required fields

Optional fields

On-site search signal

Required fields

Optional fields

Order signal

Required fields

Optional fields

📘Note

Page view signal

Required fields

Optional fields

Product configuration signal

Required fields

Optional fields

Product view signal

Required fields

Optional fields

Rich media interaction signal

Required fields

Optional fields

Response fields

Verification methods

Method 1: Contact details

Method 2: Signal management

Method 3: Sessions (Connect Ultimate only)

🚧Important

How it works

Required vs. optional fields

Test signals

Session ID behavior

Contact mapping behavior

🚧Important

Related pages

📘
Note

🚧
Important

🚧
Important