Acoustic Connect can consume behavior signals originating from external systems. It happens in near real-time. They 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. For example, you may want to merge signals from two sources when the Connect library does not have access to an area of the user journey that relies on a third-party component, such as a payment processor or ticket management solution.

How it works

• You can import the signals supported by your Connect subscription: 3 signals for Connect Pro or 9 signals for Connect Premium and Ultimate.
• Each signal must follow our predefined format. See Prepare signal content for import for details.
• Each signal must be mapped to a contact. You can use any of the following attributes for mapping: contact key, email or phone number. The phone number can be from the WhatsApp or SMS channel.
• A mutation can contain up to 500 signals.

Before you begin

Have your application key handy. It maps imported signals to an application.

• If your company has a Pro subscription for Connect, the key was provided during onboarding.
• Premium and Ultimate subscription holders can generate the key through the Connect interface. For instructions, 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 structure

Use the createSignals mutation to import behavior signals to the audience. Here is an example.

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"
          ]
        }
      }
      {
        appKey: "00000000000xxx000000000xxxx"
        identifiableAttributes: { email: "[email protected]" }
        sessionId: "OOII97671461464332a1112"
        signalContent: {
          signalType: "pageView"
          name: "Sample product view"
          category: "Behavior"
          effect: "positive"
          url: "https://example.com/shoes/sandal-beige"
          pageCategory: "Shoes"
        }
      }
    ]
  ) {
    signalIds
  }
}

{
  "data": {
    "createSignals": {
      "signalIds": [
        "b83c94d0-10f1-4b56-aaaa-000000000000",
        "ec51bf96-b2d5-4b58-bbbb-000000000000"
      ]
    }
  }
}

Arguments

The mutation supports the following arguments.

Fields supported by objects within the signals argument

Field	Values	Required?	Definition
appKey	String	Required	The identifier of your application in Connect
identifiableAttributes	Object	Required	You must submit one attribute for mapping: contact key, email address or phone number (SMS or WhatsApp).
sessionId	String	Optional	The ID of the session that the signal belongs to. It lets you group signals associated with the same contact. If you provide a session ID, the system registers the session as if it was generated by the Connect library. In that case signals from the session are included in aggregate reports and in-market interest calculation. We'll append a timestamp to the session ID you originally submit. This lets us uniquely distinguish it from other sessions from the past that might have used it. For example, in Connect session OOII97671461Jgfa9999 changes to OOII97671461Jgfa9999.1751479037630. If you skip sessionId, the imported signals will be displayed in contacts' activity feed, but they won't be used for aggregate reports.
signalContent	JSON object	Required	The content of the signal you are importing. See Prepare signal content for import.

Fields supported by the identifiableAttributes object

Fields

Fields returned by the createSignals mutation

Verification

There are two ways to make sure the import is working as expected.

Option A: through contact details

To confirm that the signals have been imported, do the following:

1. Log in to your Acoustic Connect subscription.
2. Go to Data management > Audience.
3. On the All contacts tab, select the contact that the signals are associated with.
4. Find the signals in the activity feed.

🚧

Important

When you expand a user session, you can see 5 most recent signals associated with it. All in all, the activity feed displays the last 1000 signals or signals from the last 30 days. In some cases newly added signals may not be immediately visible.

Option B: through sessions (Connect Ultimate)

If your company has an Ultimate subscription for Connect and the imported signals are supplementing a replay-able session generated by the Connect library, you can view the actual JSON payload.

1. In your Connect account, navigate to Insights > Sessions > Session search.
2. Find your session by the ID and select the checkmark next to it.
3. Click Inspect signals.

4. Find the signal content you have imported.

🚧

Important

If the session ID was generated by an external system, the session won't be searchable.

Related pages

Prepare signal content for import