API reference
Help centerCommunityDevelopersAcademyStatus

Enable real-time import of behavior signals for contacts

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

    • Connect Pro: 3 signals
    • Connect Premium and Ultimate: 9 signals

  • Signal format: Each signal must follow our predefined format (see Prepare signal content for import)

  • 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).

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.

Basic mutation structure

mutation {
  createSignals(
    signals: [
      {
        appKey: "your-app-key-here"
        identifiableAttributes: { contactKey: "AAUN-132417508" }
        sessionId: "OOII97671461464332a1111"
        signalContent: {
          signalType: "addToCart"
          name: "Add product to cart in online store"
          category: "Behavior"
          signalTimestamp: "2025-09-21T08:29:30.001Z"
          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"
          ]
        }
      }
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "OOII97671461464332a1112"
        signalContent: {
          signalType: "pageView"
          name: "Sample product view"
          category: "Behavior"
          signalTimestamp: "2025-09-22T10:35:07.001Z"
          effect: "positive"
          url: "https://example.com/shoes/sandal-beige"
          pageCategory: "Shoes"
        }
      }
    ]
  ) {
    signalIds
  }
}

Mutation arguments

ArgumentTypeRequired?Description
signalsArray of objectsRequiredCreate an object for each signal you want to import

Signals object fields

  • 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 (see Prepare signal content for import)
  • test: Boolean - Flag for importing test signals (default: false)

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

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 timestamp to make it unique (e.g., OOII97671461Jgfa9999 becomes OOII97671461Jgfa9999.1751479037630)

When you skip sessionId:

  • Signals appear in contacts' activity feed
  • Signals not used for aggregate reports

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

Response fields

  • signalIds (required): Array of strings - Unique identifiers assigned to imported signals (share with support for troubleshooting)

Verification methods

Method 1: Contact details

  1. Log in to Acoustic Connect.
  2. Navigate to Data management > Audience.
  3. Select contact from All contacts tab.
  4. Find signals in activity feed.
Imported 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

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

Method 3: Sessions (Connect Ultimate only)

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

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

🚧

Important

Sessions with external system-generated IDs are not searchable.

Contact mapping behavior

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

  1. 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.

  2. 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.

  3. New contact w/ contact key: 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.

Example usage

Import shopping behavior signals

mutation {
  createSignals(
    signals: [
      {
        appKey: "your-app-key-here"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "shopping-session-001"
        signalContent: {
          signalType: "addToCart"
          name: "Added item to cart"
          category: "Behavior"
          signalTimestamp: "2025-09-21T14:30:00.000Z"
          effect: "positive"
          productId: "PROD-001"
          productName: "Premium Headphones"
          unitPrice: 199.99
          itemQuantity: 1
        }
      }
    ]
  ) {
    signalIds
  }
}

Import test signals for validation

mutation {
  createSignals(
    signals: [
      {
        appKey: "your-app-key-here"
        identifiableAttributes: { contactKey: "TEST-CONTACT-001" }
        test: true
        signalContent: {
          signalType: "pageView"
          name: "Test page view"
          category: "Behavior"
          signalTimestamp: "2025-09-21T15:00:00.000Z"
          effect: "positive"
          url: "https://example.com/test-page"
        }
      }
    ]
  ) {
    signalIds
  }
}

Related pages

Prepare signal content for import