Prepare signal content for import

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.

  • If you are importing signals from a file, see the JSON examples.
  • For real-time import via the API, see signalContent in the GraphQL version.

Add-to-cart signal

This signal is triggered when a visitor adds products to their cart.

The add-to-cart signal is included into all Connect subscriptions (Pro, Premium and Ultimate).

{
  "signalType": "addToCart",
  "name": "Add product to cart in online store",
  "category": "Behavior",
  "currency": "USD",
  "productId": "AC-PNT-WHT-SM",
  "productName": "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz",
  "effect": "positive",
  "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"]
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "addToCart"
          name: "Add product to cart in online store"
          category: "Behavior"
          currency: "USD"
          productId: "AC-PNT-WHT-SM"
          productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
          effect: "positive"
          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"
          ]
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior. The category of the signal
currencyString. Valid values - ISO 4217 currency codes.The currency in which the price of the product is represented
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

We suggest sending positive for all add-to-cart signals.
itemQuantityNumberThe quantity of the product added to the cart
nameString, up to 256 charactersAssign a name to the signal to differentiate it from other signals.
productIdStringThe identifier of the product. It may coincide with the SKU.
productNameStringThe name of the product
signalTypeString. Valid value -
addToCart.
The type of signal to import
unitPriceNumberThe unit price of the product

Optional fields

FieldValuesDefinition
discountNumberDiscount from the original price. If the exact amount is not provided, you could calculate the difference between the original and the current price.
imageUrlsArray of stringsThe URLs of product images
productCategoryStringThe category that the product falls in based on the product catalog
productDescriptionStringThe description of the product
productUrlsArray of stringsThe URLs of product pages
promotionIdStringFor the use case of on-site marketing like hero images and other calls-to-action, those calls-to-action would have a promotion ID that would "stick" to the behaviors after it.
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.
shoppingCartUrlStringThe URL of the shopping cart that the add-to-carts are contributing to
virtualCategoryStringThe category is based on how the visitor got to the page, for example from "New arrivals" or "Sale".

Error signal

This signal is sent when a user encounters an error on your site. We suggest focusing on payment, promo code, and account registration errors - anything that leads users away from the happy path and results in lost sales opportunities.

🚧

Important

The error signal doesn't replace an error monitoring solution. Its aim is to let marketers segment out users who have ran into issues during the order process. Also, marketers can set up the delivery of personalized messages triggered by the signal.

The error signal is supported by Premium and Ultimate subscriptions.

{
  "signalType": "error",
  "name": "Shopping cart error",
  "category": "Behavior", 
  "errorIdentifier": "promoCode", 
  "errorText": "This promo code is invalid.", 
  "errorType": "user", 
  "effect": "negative"
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "error"
          name: "Shopping cart error"
          category: "Behavior"
          errorIdentifier: "promoCode"
          errorText: "This promo code is invalid."
          errorType: "user"
          effect: "negative"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior.The category of the signal
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

We suggest sending negative for all error signals.
errorIdentifier StringAn identifier assigned to the error. Example: "promoCode".
errorText StringThe content of the error message received
errorType String. Valid values:

- application
- user
Application errors are server-side or system errors. User errors occur when user input doesn't pass client- or server-side validation.
nameString, up to 256 charactersAssign a name to the signal to differentiate it from other signals.
signalTypeString. Valid value -
error.
The type of signal to import

Optional fields

FieldValuesDefinition
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.

Identification signal

This signal captures visitors' emails or client/contact IDs as they are browsing your website.

The identification signal is supported by all types of Connect subscriptions (Pro, Premium and Ultimate).

{
  "signalType": "identification",
  "name": "Identification from login",
  "category": "Behavior", 
  "identifierName": "email",
  "identifierValue": "[email protected]",
  "identificationFromLogin": true,
  "effect": "positive" 
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "identification"
          name: "Identification from login"
          category: "Behavior"
          identifierName: "email"
          identifierValue: "[email protected]"
          identificationFromLogin: true
          effect: "positive"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior.The category of the signal.
effectString. Valid values:

- negative
- positive
Specify how to interpret the signal. The value will be used for engagement index scoring.
identifierNameString. Valid values:

- email
- sms
- contactKey
The type of the identifier to use for the signal
identifierValueStringThe contact information associated with a visitor. The type of identifier depends on the identifierName value.
nameString, up to 256 characters Assign a name to the signal to differentiate it from other signals.
signalTypeString. Valid value -
identification.
The type of signal to import

Optional fields

FieldValuesDefinition
identificationFromLoginBooleanIf the identifierValue derives from user authentication, set the value to true. If it is taken from a cookie or a query string, use false.

This lets you separate sessions where visitors identified themselves explicitly or implicitly.

On-site search signal

This signal records the search terms that your website visitors use and the number of results they get.

The on-site search signal is supported by Premium and Ultimate subscriptions.

{
  "signalType": "onSiteSearch",
  "name": "Product search in online store",
  "category": "Behavior",
  "numberOfResults": 9,
  "searchTerm": "paint with satin finish",
  "effect": "positive"
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "onSiteSearch"
          name: "Product search in online store"
          category: "Behavior"
          numberOfResults: 9
          searchTerm: "paint with satin finish"
          effect: "positive"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior. The category of the signal
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

If a search term returns results, send positive as the value. If there are no results, send negative.
nameString, up to 256 characters Assign a name to the signal to differentiate it from other signals.
numberOfResultsNumberThe number of results that matched the search term
searchTermStringThe word or phrase that the visitor searched for
signalTypeString. Valid value -
onSiteSearch.
The type of signal to import

Optional fields

FieldValuesDefinition
signalCustomAttributesArrayAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.

Order signal

This signal comes each time a contact places an order on your website. For each order, there is the total amount and a detailed breakdown by the product.

The order signal is supported by all types of Connect subscriptions (Pro, Premium and Ultimate).

{
  "signalType": "order",
  "name": "Online store order",
  "category": "Behavior",
  "currency": "USD",
  "effect": "positive",
  "orderDiscount": 0,
  "orderId": "02937-2025-XIA",
  "orderSubtotal": 89.47,
  "orderShippingHandling": 15.45,
  "orderValue": 98.44,
  "orderTax": 4.47,
  "orderedItems": [
    {
      "productId": "AC-PNT-WHT-SM",
      "productName": "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz",
      "quantity": 2,
      "unitPrice": 39.99,
      "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",
      "quantity": 1,
      "unitPrice": 9.49,
      "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": ""
    }
  ]
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "order"
          name: "Online store order"
          category: "Behavior"
          currency: "USD"
          effect: "positive"
          orderDiscount: 0
          orderId: "02937-2025-XIA"
          orderSubtotal: 89.47
          orderShippingHandling: 15.45
          orderValue: 98.44
          orderTax: 4.47
          orderedItems: [
            {
              productId: "AC-PNT-WHT-SM"
              productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
              quantity: 2
              unitPrice: 39.99
              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"
              quantity: 1
              unitPrice: 9.49
              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

FieldValuesDefinition
categoryString. Valid value - Behavior. The category of the signal
currency String. Valid values - ISO 4217 currency codes.The currency used for the order
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

We suggest sending positive for all order signals.
nameString, up to 256 characters Assign a name to the signal to differentiate it from other signals.
orderId StringAn identifier assigned to the order
signalTypeString. Valid value -
order.
The type of signal to import

Optional fields

FieldValuesDefinition
orderDiscountNumberDiscount from the original price
orderedItemsArray of objectsThe list of products in the order. You need a separate object for each product, but not each instance of the same product - three identical items would result in one object, with a quantity of 3.
orderShippingHandlingNumberThe shipping and handling amount for the order
orderSubtotalNumberThe subtotal amount for the order (net of discount)
orderTaxNumberThe tax amount for the order
orderValueNumberThe total value of the order
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.

Fields supported by objects within the orderedItems array

FieldValuesRequired?Definition
currencyString. Valid values - ISO 4217 currency codes.OptionalThe currency in which the price of the product is represented
discountNumberOptionalDiscount from the original price
imageUrlsArray of stringsOptionalThe URLs of product images
productCategoryStringOptionalThe category that the product falls in based on the product catalog
productDescriptionStringOptionalThe description of the product
productIdStringRequiredThe identifier of the product. It may coincide with the SKU.
productNameStringRequiredThe name of the product
productUrlsArray of stringsOptionalThe URLs of product pages
promotionIdStringOptionalFor the use case of on-site marketing like hero images and other calls-to-action, those calls-to-action would have a promotion ID that would "stick" to the behaviors after it.
quantityIntegerOptionalThe quantity of the product purchased
shoppingCartUrlStringOptionalThe URL of the shopping cart
unitPriceNumberRequiredIndicates how much the client paid for the product.
virtualCategoryStringOptionalThe category is based on how the visitor got to the product page, for example from "New arrivals" or "Sale".

Page view signal

This signal registers page views as users are browsing your website.

The page view signal is supported by Premium and Ultimate subscriptions.

{
  "signalType": "pageView", 
  "name": "Page view from online store",
  "category": "Behavior", 
  "url": "https://www.example.com/painting-and-decorating/tools/",
  "pageCategory": "Painting & Decorating",
  "effect": "positive" 
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "pageView"
          name: "Page view from online store"
          category: "Behavior"
          url: "https://www.example.com/painting-and-decorating/tools/"
          pageCategory: "Painting & Decorating"
          effect: "positive"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior.The category of the signal
effectString. Valid values:

- negative
- positive
Specify how to interpret the signal. The value will be used for engagement index scoring.
nameString, up to 256 charactersAssign a name to the signal to differentiate it from other signals.
signalTypeString. Valid value - pageView.The type of signal to import
urlStringThe URL of the page a user has opened

Optional fields

FieldValuesDefinition
pageCategoryStringThe category that the page belongs to

Product configuration signal

This signal tracks interactions on product pages (for example, selecting clothing size, checking FAQs or reviews, etc) that suggest customer engagement.

The product configuration signal is supported by Premium and Ultimate subscriptions.

{
   "signalType": "productConfiguration",
   "name": "Product configuration from online store",
   "category": "Behavior",
   "currency": "USD",
   "effect": "positive",
   "productId": "AC-DBL-BRSH-6",
   "productName": "AWESOME COLORS Double Thick Chip Paint Brush",
   "configurationType": "Size selection"
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "productConfiguration"
          name: "Product configuration from online store"
          category: "Behavior"
          currency: "USD"
          effect: "positive"
          productId: "AC-DBL-BRSH-6"
          productName: "AWESOME COLORS Double Thick Chip Paint Brush"
          configurationType: "Size selection"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior. The category of the signal
configurationTypeStringAssign a label to the interaction that happened. For example, you could name the product parameter (size, color, quantity) or identify the UI element (product option dropdown).
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

We suggest sending positive for all product configuration signals.
nameString, up to 256 characters Assign a name to the signal to differentiate it from other signals.
productIdStringThe identifier of the product. It may coincide with the SKU.
productNameStringThe name of the product
signalTypeString. Valid value -
productConfiguration.
The type of signal you are importing

Optional fields

FieldValuesDefinition
currencyString. Valid values - ISO 4217 currency codes.The currency in which the price of the product is represented
inventoryQuantityIntegerThe number of units available
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.

Product view signal

This signal records user activity on product pages. It offers insights into how much attention each product and product category is getting. This is crucial for segmentation. Also, it becomes possible to tie product interest to identified visitors.

The product view signal is supported by Premium and Ultimate subscriptions.

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

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior.The category of the signal
currencyString. Valid values - ISO 4217 currency codes. The currency in which the price of the product is represented on the website
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

We suggest sending positive for all product views.
nameString, up to 256 characters Assign a name to the signal to differentiate it from other signals.
productIdStringThe identifier of the product. It may coincide with the SKU.
productName StringThe name of the product
signalTypeString. Valid value -
productView.
The type of signal to import
unitPriceNumberThe unit price of the product.

If your product pages don't have prices (as is often the case in banking and insurance), use a placeholder.

Optional fields

FieldValuesDefinition
availabilityStringIndicates if the product is available for purchase, for example "In Stock", "Out of Stock", "Back Order".
brandNameStringThe brand name of the product
brandDescriptionStringThe description of the brand
dateAddedCombined date and time representation. Format: yyyy-MM-dd HH:mm:ss.SSS .The date when the product was added to the product catalog
discountNumberDiscount from the original price
imageUrlsArray of stringsThe URLs of product images
inventoryQuantityIntegerThe number of units available
modelStringThe number or description of the model
msrpNumber. Must be a decimal or float.Suggested retail price or original price
productCategoryStringThe category that the product falls in based on the product catalog
productDescriptionStringThe description of the product
productRatingNumberThe rating of the product
productStatusStringThe current lifecycle state of the product (for example, "Active", "Discontinued", "Upcoming")
productUrlsArray of stringsThe URLs of product pages
promotionIdStringFor the use case of on-site marketing like hero images and other calls-to-action, those calls-to-action would have a promotion ID that would "stick" to the behaviors after it.
shoppingCartUrlStringThe URL of the shopping cart that the add-to-carts are contributing to
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.
skuStringIf the product ID is different from the SKU, add this field.
virtualCategoryStringThe category is based on how the visitor got to the page, for example from "New arrivals" or "Sale".

Rich media interaction signal

This signal records user interactions with video and audio content on your website. The findings can be valuable for audience segmentation based on product (or product category) interest.

The rich media interaction signal is supported by Premium and Ultimate subscriptions.

{
   "signalType": "richMediaInteraction",
   "name": "Video review interaction in online store",
   "category": "Behavior",
   "mediaId": "jhaf6r76a",
   "effect": "positive",
   "interactionType": "launch",
   "mediaCategory": "video",
   "mediaName": "How I used AWESOME COLORS Brush to paint the ceiling",
   "url": "https://www.example.com/opinions/painting-and-decorating/"
}
mutation {
  createSignals(
    signals: [
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "richMediaInteraction"
          name: "Video review interaction in online store"
          category: "Behavior"
          mediaId: "jhaf6r76a"
          effect: "positive"
          interactionType: "launch"
          mediaCategory: "video"
          mediaName: "How I used AWESOME COLORS Brush to paint the ceiling"
          url: "https://www.example.com/opinions/painting-and-decorating/"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

FieldValuesDefinition
categoryString. Valid value - Behavior.The category of the signal
effectString. Valid values:

- negative
- positive
Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

Usually rich media interactions are interpreted as positive signals.
mediaIdStringThe URL of the media file
nameString, up to 256 charactersAssign a name to the signal to differentiate it from other signals.
signalTypeString. Valid value -
richMediaInteraction.
The type of signal to import

Optional fields

FieldValuesDefinition
interactionTypeString. Valid values:

- load
- launch
- pause
- continue
- complete
- stop
- enlarge
The type of user interaction with the media
mediaCategory StringThe category that the media falls into, for example, "video"
mediaName StringThe title of the audio or video file
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.
url StringThe URL of the page where the media file is embedded

Related pages

Enable real-time import of behavior signals for contacts