Contentsquare
Hi, how can we help?
Popular help topics: CS Live, Metrics List, Request an Integration

What's New? Releases & Updates How do I install the Contentsquare tag?

help center results

technical documentation

Français 日本語

Articles in this section

Connect Ada to Conversational Intelligence

Overview

Conversation Intelligence uses Ada's Data Export API to read customer interaction data for analysis. This integration is read-only; Conversation Intelligence reads conversation and message data for analysis and doesn't create, edit, or delete data in Ada.

To set up this integration, you will need to provide an API key and base URL for Ada's Data Export API. 

Access to the Data Export API depends on your Ada subscription. If the connection check fails because of an access error, ask your Ada account team to enable Data Export API access.

Ada API keys

We recommend creating a dedicated API key for Conversation Intelligence so you can control, audit, rotate, or revoke its access independently.

Ada's current API keys are general-purpose keys. They grant read and write access to Ada APIs, and Ada doesn't currently provide a new key with read-only or Data-Export-only permissions. Conversation Intelligence only uses the key with Ada's read and export endpoints.

For more information, see Ada's authentication documentation.

Setup

Step 1: Find your Ada base URL

Your Ada base URL follows this format:

https://<your-bot-handle>.ada.support
  1. Sign in to your Ada Dashboard.
  2. Look at the URL in your browser's address bar.
  3. Copy your base URL. For example: https://acme-corp.ada.support.

Step 2: Generate an Ada API key

  1. In the Ada Dashboard, open the API key settings:
    • Generative AI Agent: Go to Config > Platform > API keys.
    • Scripted Bot: Go to Settings > Integrations > APIs.
  2. Click New API key. If this is your first key, click Get started instead.
  3. Give the key a clear, descriptive name, such as Conversation Intelligence Integration.
  4. Click Generate key.
  5. Copy and securely save the key immediately. Ada displays the key only once. Use a dedicated key for this integration.

Step 3: Connect Ada in the onboarding wizard

  1. Set the csq_eligible conversation variable to true in Ada for the conversations you want to ingest. See the CSQ eligible tag guide for more information.
  2. Open the Conversation Intelligence onboarding wizard.
  3. Select Ada as the platform.
  4. Enter your Ada base URL and API key.
  5. Click Submit to connect.

Conversation Intelligence verifies the API key immediately. If the key can't be verified, you are prompted to enter it again.

After the key and connection details are verified, Conversation Intelligence can read the Ada data required for ingestion and analysis.

Ingestion scope and eligibility

Channels

The integration ingests chat and email conversations. A conversation is treated as email when its Ada ada_email_is_source metavariable is true. All other conversations are treated as chat. Both channels are read through Ada's Data Export API.

Eligibility requirements

A conversation is eligible for ingestion only when all of the following conditions are met:

  • It hasn't been escalated to an agent, meaning is_escalated = false. Escalated conversations are expected to be ingested from the downstream CRM, such as Zendesk or Salesforce.
  • No message in the transcript is from a human agent. This provides an additional check for conversations that were escalated.
  • It contains at least one customer message.
  • It isn't from a test user, meaning is_test_user = true.
  • When csq_eligible filtering is enabled, the conversation variable csq_eligible is set to true.

Ingestion timing

Conversation Intelligence ingests each Ada conversation approximately 48 hours after it occurs. This delay allows late-arriving transcript updates to be included before analysis.

Available history

Ada's Data Export API exposes the previous 12 months of data. Conversations older than 12 months aren't available for initial ingestion.

Required data access

Conversation Intelligence reads the following data through Ada's Data Export API to reconstruct and analyze bot conversations:

Data Conversation Intelligence reads How it is used
Conversation ID Uniquely identifies each conversation.
Created time Identifies when the conversation started.
Escalation flag, is_escalated Determines whether the conversation was handed off to an agent and supports eligibility filtering.
Bot handle time Measures how long the bot handled the conversation.
CSAT Provides the customer satisfaction score when one is available.
Generated topic Provides Ada's topic classification when one is available.
Bot and customer messages Provides the transcript text and message turns for analysis.
Sender Identifies whether each message was sent by the bot or the customer. Conversations containing a human agent message are excluded.
Message timestamps Provides timing for each message.
Conversation variables and metavariables Controls which conversations are ingested, including csq_eligible, and provides optional brand, region, or queue attributes when available.

Ada environments vary by configuration. Fields that aren't available in your environment are ignored as long as the required conversation and message data is available.

Security and setup guidance

  • Store your API key securely and share it only through approved onboarding channels.
  • Regenerate the key if it is exposed or no longer meets your internal security standards.
  • If your Ada team rotates API keys on a schedule, update the integration with the new key to avoid an interruption in data ingestion.
  • To stop the integration, revoke or delete the API key in Ada. Conversation Intelligence can no longer read your data once the key is invalid.
  • Confirm that the base_url points to the correct Ada environment before completing onboarding.
  • Personal fields, including customer email addresses, names, contact details, and access tokens, are cleared during ingestion and aren't stored by Conversation Intelligence.