Integrating Conversational AI Apps with Netmera

Overview

This guide explains how to connect a conversational AI app — built on ChatGPT, Claude, or any AI-powered chat interface — to Netmera using REST API integration. Once integrated, user actions inside the AI app flow into Netmera as structured events, enrich customer profiles, and trigger omnichannel campaigns.

What this guide covers:

• How the integration works at a conceptual level

• Prerequisites for both technical and non-technical stakeholders

• How your backend receives data from the AI app (Tool Calling)

• Step-by-step implementation for developers

• Event design guidelines

• Campaign activation for marketing and product teams

• Troubleshooting and validation

---

How the Integration Works

Conversational AI apps do not embed Netmera's SDK. Integration happens at the backend level: when a user takes a meaningful action inside the AI app (searches, selects, saves, converts), your app's backend sends a structured event to Netmera's REST API.

User action in AI app
        ↓
AI platform calls your backend (Tool Call)
        ↓
Your backend processes the action
AND sends event to Netmera REST API
        ↓
Netmera customer profile updated
        ↓
Campaign or journey triggered

This approach works regardless of which AI platform hosts the app — ChatGPT, Claude, or a custom interface.

---

Prerequisites

For Developers

• Netmera account with REST API access enabled

• Netmera API key (available in Settings > API Keys)

• An app backend that processes user actions

• HTTPS endpoint capability for outbound API calls

For Product / Marketing Teams

• Defined event taxonomy before development begins (see Event Design section)

• Understanding of which user actions are meaningful for segmentation and campaign triggers

• Journey Builder access in Netmera to configure downstream campaigns

---

Step 1 — Define Your Event Taxonomy

Before writing any code, align on which user actions should be tracked. Every event sent to Netmera should represent a business-meaningful action, not a UI interaction.

User Action	Event Name	Key Parameters
Starts a conversation	ai_session_started	platform, entry_point
Performs a search or query	ai_query_submitted	query_text, category, filters
Views a product or result	ai_result_viewed	item_id, item_name, price
Saves or bookmarks	ai_item_saved	item_id, item_type
Completes a conversion	ai_conversion_completed	item_id, revenue, currency, source_event
Abandons without converting	Inferred via session timeout	—

Rule: If marketing cannot act on an event, do not send it. Keep the taxonomy tight.

---

Step 2 — Identify and Register the User

Netmera requires a user identity to attach events to a profile. At the start of each session, your backend must either match the user to an existing Netmera profile or create a new one.

Identify by external ID (recommended):

curl -X POST <https://restapi.netmera.com/rest/3.0/setProfileAttributes> \\
  -H "X-netmera-api-key: YOUR_REST_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '[
    {
      "extId": "user_98765",
      "profile": {
        "name": "John",
        "email": "[email protected]",
        "source": "chatgpt_app",
        "first_seen_channel": "conversational_ai"
      }
    }
  ]'

If the user is anonymous, generate a temporary session ID and merge it with a known identity after authentication.

---

Step 3 — Send Events from Your App Backend

Each time a tracked user action occurs inside your tool handler, send a structured event to Netmera. Events originate from your server — not from the AI platform directly.

Example: User submits a query

curl -X POST <https://restapi.netmera.com/rest/3.0/fireEvents> \\
  -H "X-netmera-api-key: YOUR_REST_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '[
    {
      "extId": "user_98765",
      "name": "AIQuerySubmitted",
      "platform": "chatgpt",
      "queryText": "5-day trip to Barcelona under $2000",
      "category": "travel_planning"
    }
  ]'

Example: User completes a conversion

curl -X POST <https://restapi.netmera.com/rest/3.0/fireEvents> \\
  -H "X-netmera-api-key: YOUR_REST_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '[
    {
      "extId": "user_98765",
      "name": "AIConversionCompleted",
      "itemId": "FLIGHT-BCN-001",
      "revenue": 540.00,
      "currency": "USD",
      "sourceEvent": "AIQuerySubmitted"
    }
  ]'

Implementation notes:

• Always send events server-side. Never expose your API key in client-side code.

• Use ISO 8601 format for all timestamps.

• Keep eventName values consistent with your defined taxonomy. Inconsistent naming breaks segmentation.

• Include source_event on conversion events to enable attribution.

---

Step 4 — Validate Data Flow

Before configuring campaigns, confirm that events are reaching Netmera correctly.

1. Trigger a test event from your backend using a known externalId

2. In Netmera, navigate to Profiles > Search and locate the user by external ID

3. Confirm the event appears in the user's event history with correct parameters

4. Check that profile attributes updated as expected

If events are not appearing, verify:

• API key is valid and has write permissions

• Request headers include Content-Type: application/json

• externalId format matches what Netmera has on record for that user

• Server clock is in sync (timestamp drift can cause rejection)

---

Step 5 — Activate Campaigns in Netmera

Once events flow in, the marketing or product team configures downstream actions in Netmera. No additional development is required for standard journeys.

Segment Users Based on AI Behavior

In Segments, create filters using the events sent from your AI app. Example: users who triggered ai_item_saved but not ai_conversion_completed in the last 7 days.

Build Journeys Triggered by AI Events

In Journey Builder, set the entry trigger to a specific event name. Example flow:

Trigger: ai_item_saved
Wait: 24 hours
Condition: ai_conversion_completed not fired
Action: Send push notification — "Your saved item is still available"
Wait: 48 hours
Condition: ai_conversion_completed still not fired
Action: Send email with alternative recommendations

Attribution

Conversion events that include a source_event parameter are attributed back to the originating AI interaction in Netmera's analytics. Use Funnel Analysis to measure drop-off between ai_query_submitted → ai_item_saved → ai_conversion_completed.

---

Troubleshooting

Symptom	Likely Cause	Action
Events not appearing in profile	Wrong externalId format	Match the ID format used during registration
Profile not merged	Anonymous session not resolved	Implement identity merge after user authenticates
Journey not triggering	Event name mismatch	Compare exact event name in Journey Builder vs. API payload
Revenue not attributed	Missing source_event field	Add originating event reference to conversion payload
API returning 401	Expired or incorrect API key	Regenerate key in Settings > API Keys
High latency on tool calls	Netmera call is blocking response	Switch to async / fire-and-forget pattern

---

Summary

Step	Owner
Define event taxonomy	Product / Marketing
Implement user registration call	Developer
Define tools in AI platform	Developer
Implement event calls inside tool handlers	Developer
Validate data in Netmera Profiles	Developer + Product
Configure segments and journeys	Marketing / Product
Monitor attribution in analytics	Product