---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/conversations/memory/segment-customer-memory-integration#article
headline: Segment Conversation Memory Integration
description: Connect Twilio Segment with Conversation Memory to give human and AI agents long-term customer data and real-time conversation context for personalization.
url: https://www.twilio.com/docs/conversations/memory/segment-customer-memory-integration
inLanguage: en
dateModified: 2026-09-25T18:57:30.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Segment Conversation Memory Integration

> \[!NOTE]
>
> The Segment Conversation Memory Integration is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

> \[!WARNING]
>
> Customers must request deletion separately from both Segment and Conversation Memory for account-level deletion requests and individual deletion requests, including data subject rights requests. Deleting data in one system does not automatically delete it from the other. For more information, consult with your legal counsel or visit our [Privacy Policy](https://www.twilio.com/en-us/legal/privacy).

The Segment Conversation Memory Integration connects [Twilio Segment](/docs/segment), a Customer Data Platform (CDP), with Conversation Memory. The integration provides agents—human or AI—with both long-term customer data and real-time conversational context, enabling personalized and context-aware customer experiences.

Conversation Memory supplies agents with real-time, "in-the-moment" context, but it's not the system of record for customer data. Segment fills that role by providing identity resolution, consent management, historical traits, and real-time events.

By connecting Segment and Conversation Memory, each agent gains:

* Continuous visibility into the current conversation.
* Access to long-term customer history and preferences.
* The ability to maintain context across channels and over time.

## Key benefits

The integration provides the following benefits:

* Agents see customer history from the first interaction, so customers don't need to repeat information, which eliminates cold starts.
* You reuse existing Segment profiles without rebuilding data infrastructure.
* Context flows seamlessly across multiple channels over time, which enables continuous conversations.

## Understand the two systems

### Segment CDP: Long-term system of record

Segment unifies identity and events, manages consent and traits, and powers audiences and activation.

The systems differ in the following ways:

| Aspect            | Details                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| Tracks            | What customers **do** (clicks, purchases, lifetime value, preferences)                                              |
| Use for           | Understanding who the customer is and how to target them                                                            |
| Emphasizes        | Completeness, governance, and cross-channel orchestration                                                           |
| Data latency      | Seconds to minutes (optimized for profile resolution and orchestration)                                             |
| Primary use cases | Single view of the customer, ad optimization, personalized communications, retention campaigns, and data governance |

### Conversation Memory: Real-time working memory

Conversation Memory captures context across calls, chats, and messages. It distills observations and conversation history into a working memory that agents carry into future interactions.

| Aspect            | Details                                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| Tracks            | What customers **say** (conversation history, insights, and real-time context)                              |
| Use for           | Providing agents with full conversation history so they never start from zero                               |
| Emphasizes        | Relevant context recalled at any interaction                                                                |
| Data latency      | Sub-second (\< 100 ms), optimized for a large language model (LLM) or Voice AI inner loop                   |
| Primary use cases | Customer support, sales conversations, client advising, post-purchase support, and conversational AI agents |

## How the systems work together

* Segment provides long-term customer understanding (identity, preferences, purchase history, and segmentation).
* Conversation Memory supplies short-term conversational context (recent dialog, observations, and unresolved issues).

Combined, agents receive a unified view that merges long-term customer behavior with the short-term context of their latest conversation with your agents.

## Set up steps

To set up the Segment and Conversation Memory integration, follow these steps:

1. [Create or select a memory store](#step-1-create-or-select-a-memory-store)
2. [Find a profile in a memory store](#step-2-find-a-profile-in-a-memory-store)
3. [Connect your Twilio account to Segment](#step-3-connect-your-twilio-account-to-segment)
4. [Create mappings](#step-4-create-mappings)

### Step 1: Create or select a memory store

1. Sign in to the [Twilio Console](https://1console.twilio.com).
2. In the sidebar, select **Products and Services** > **Conversation Memory** > **Memory Stores**.
3. To create a memory store, choose **Create New Store**. To select an existing store, review the memory stores and select one from the list.

### Step 2: Find a profile in a memory store

1. Open the desired memory store to view its profiles.
2. On the **Profiles** tab, select the **Filter by ID or identifier** option.
3. Enter any configured identifier (for example, phone or email) or the profile ID (for example, `mem_profile_000000000000000`) to locate the profile.

### Step 3: Connect your Twilio account to Segment

1. Open Twilio Segment.
2. Go to **Unify** > **Conversation Memory Sync**.
3. Enter your Twilio **API Key**, **API Secret**, and **Account SID**.
4. After a successful connection, review the overview screen.
5. Go to **Settings** > **Basic Settings** and enable the integration.

### Step 4: Create mappings

1. In **Mappings**, select **Add Mapping**.
2. Choose the target **memory store**.
3. Map Segment traits and identifiers to the corresponding Conversation Memory traits and identifiers.
   **Note**: You must define at least two mappings and map at least one identifier.
4. For identifiers, use the default **Last Added** strategy, or change the strategy to **First Added** or **All**. Traits don't use a strategy. They always reflect the latest synced value.
5. Select **Save and Enable**.
6. Edit existing mappings at any time from the **Mappings** screen.

When you configure a new mapping, Segment deducts one audience usage credit.

### Manage the connection

To enable, disable, or delete the connection, follow these steps:

1. Open Segment.
2. Go to **Unify** > **Conversation Memory Sync**.
3. Select the integration you've set up, then go to **Settings** > **Basic Settings**.

To view or update connection details, like Account SID, API Key, or API Secret, follow these steps:

1. Open Segment.
2. Go to **Unify** > **Conversation Memory Sync**.
3. Select the integration you've set up then go to **Connection Settings**.

## How Twilio syncs profiles

### Synchronization criteria

A profile must meet both of the following conditions to synchronize:

1. The profile isn't anonymous (it contains at least one identifier such as email, phone, or `userId`).
2. The profile has traits or identifiers that match an established mapping.

Twilio only writes mapped traits to your memory store.

### Sync types

* Full Sync or Resync is a one-time operation that syncs all valid profiles according to the active mappings. This runs each time you create or enable a mapping.
* Profile Updates are real-time updates triggered whenever a mapped trait changes in Segment.

### Monitoring

The Conversation Memory Sync sends profile update events to the memory store in batches of up to 1,000 events. To monitor profile update events, go to [Delivery Overview](/docs/segment/connections/delivery-overview), where you can filter by memory store and date range.

## Integration limits

* Twilio only supports one connection per Segment space.
* You can create up to five mappings.
* Each mapping can contain up to 30 rows.
* A mapping references only one memory store.
* One sync instance per Segment space.
* Each mapping must include at least two mapped rows and one mapped identifier.

## Frequently asked questions

### How does data flow between Segment and Conversation Memory?

The integration provides unidirectional syncs from Segment to Conversation Memory:

* Profile data flows in one direction: Segment CDP > Conversation Memory.
* Updates occur in real time when mapped traits change.
* Events processed in batches of up to 1,000 events.

### Why can't I send Segment profiles directly to my AI agent?

Segment profiles are designed for identity resolution and cross-channel activation, not for real-time conversational AI.

Segment profiles contain extensive data including traits, audience memberships, computations, predictions, and event histories. Sending an entire profile to a large language model (LLM) increases latency and cost because the LLM must process all of that information with every request.

Conversational agents typically need only specific traits. For example:

* A support agent needs contact details (name, email, and location).
* A lead-qualification agent needs lead information (lead score or funnel stage).

The Segment Conversation Memory integration addresses this by:

* Syncing only the traits you map, eliminating unnecessary data transfer.
* Abstracting conversations into concise observations and summaries.
* Reducing token consumption by 10 to 15 times compared with sending full profiles.
* Delivering response latency of under 100 ms.

Additionally, your Segment profiles aren't duplicated. Each system stores only what it needs:

* Conversation Memory holds specific traits for real-time conversational context.
* Segment retains the complete historical data for marketing activation and analytics.

### How do I decide which traits to map?

Your mapping strategy should align with your use case. The following table lists recommended trait groups and custom traits for common scenarios:

| Use case                   | Value unlocked                                                                                                         | Essential trait groups                                         | Custom traits to consider                                                               |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Lead qualification & sales | Pre-load lead context to avoid discovery questions; reduces handle time by 30 s or more per call                       | Marketing<br />Account                                         | `lead_status`<br />`lead_score`<br />`funnel_stage`<br />`next_followup_date`           |
| Full-cycle AI agent        | Enables autonomous transactions across voice, SMS, and WhatsApp without cold starts or repeated identity verification. | Contact<br />Account<br />Consent                              | `order_id`<br />`order_status`<br />`payment_method`<br />`service_history`             |
| Human copilot              | Dynamically tailors prompts by segment, language, or VIP status; prevents compliance violations                        | Demographics<br />Firmographics<br />Consent<br />Localization | `vip_status`<br />`sentiment_score`<br />`assigned_agent`<br />`preferred_contact_time` |
| After-hours support        | Provides identity and account context for self-service flows and appointment booking                                   | Contact<br />Account<br />Localization                         | `preferred_appointment_time`<br />`service_type`<br />`last_service_date`               |

### How often does data sync? Will the data become stale?

The integration pushes real-time updates for all mapped traits. When a customer updates their preferences or completes a purchase, the changes flow through Segment to Conversation Memory immediately, so agents always work with the latest context.

### Can I add more traits later or modify what I'm syncing?

Yes. Trait mappings are flexible, you can change them at any time.

Twilio recommends that you take the following approach:

1. Start with a pilot use case and a small set of traits.
2. Validate results with real conversations.
3. Gradually expand to additional traits and use cases.

You can edit mappings at any time from the **Mappings** screen in the Segment app.

## Monitor sync activity and observability

You can track sync activity in Segment's [Delivery Overview](/docs/segment/connections/delivery-overview).

To monitor sync activity:

1. Go to **Overview** > **Delivery Overview**.
2. Filter by memory store and date range to view specific sync activity.
3. Review event batches (processed in groups of up to 1,000 events).

The dashboard lists all profile-update events sent from Segment to your memory stores, providing full visibility into the synchronization process.

### Understand Delivery Overview pipeline statuses

The Segment Delivery Overview displays profile update events with two pipeline view statuses:

* **Failed Delivery**: Profile update events that Segment attempted to deliver to your Conversation Memory store but ultimately failed. This may indicate an issue with the connection, such as invalid credentials, rate limits, or error statuses from the API.
* **Successful Delivery**: Profile update events that Segment successfully delivered to your Conversation Memory store. You'll see the updated or created profile in your memory store.

### Filter Delivery Overview by memory store

You can view delivery overview details based on your memory stores for which you have mappings created and enabled.

To filter by memory store, first establish a connection between Segment and Conversation Memory:

1. Go to the **Overview** tab in Delivery Overview.
2. Select the **Memory Stores** dropdown.
3. The dropdown displays the memory stores for which mappings are created and enabled.
4. Select one memory store to filter the delivery overview for that store.

## Set up Conversation Memory with Segment's Public API

Use Segment's Public API to programmatically create destinations, audiences, and activations. This lets you automate setup or reproduce configurations across workspaces.

All requests use the base URL `https://api.segmentapis.com` with the `Authorization: Bearer <token>` header. The required `Content-Type` header is shown in each example.

### Prerequisites

Gather the following before you begin:

* A Segment Public API token with read/write access to Sources, Destinations, and Engage (Audiences) (**Settings > Workspace settings > Access Management > Tokens**)
* Your Engage Space ID (format `spa_XXXXXXXXXXXXX`) from your Segment web app URL
* Your Twilio API Key and API Secret (**Console** > **Builder tools** > **API Key & creds**)
* Your Twilio Account SID
* Your Conversation Memory Store ID

### List Engage sources

Run the following to list your Engage (Personas) sources and find the one with metadata name `Personas`:

```bash
curl -s "https://api.segmentapis.com/sources" \
  -H "Authorization: Bearer $SEGMENT_TOKEN" | \
  jq -r '.data.sources[] | select(.metadata.name == "Personas") | "\(.id)  \(.name)"'
```

Note the `sourceId` returned which you'll use when you create the destination. If your workspace has multiple Engage sources, select the source connected to the space you're configuring.

### Create a destination

To retrieve the destination metadata (Conversation Memory metadata ID: `695d30cdac2addbdcc3baf7f`):

```bash
curl -s "https://api.segmentapis.com/catalog/destinations/695d30cdac2addbdcc3baf7f" \
  -H "Authorization: Bearer $SEGMENT_TOKEN" | \
  jq '.data.destinationMetadata | {name, slug, actionId: .actions[0].id, actionSlug: .actions[0].slug}'
```

Then, create the destination:

```bash
curl -s -X POST "https://api.segmentapis.com/destinations" \
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "<SOURCE_ID>",
    "metadataId": "695d30cdac2addbdcc3baf7f",
    "name": "Conversation Memory",
    "enabled": true,
    "settings": {
      "username": "<TWILIO_API_KEY>",
      "password": "<TWILIO_API_SECRET>",
      "twilioAccount": "<TWILIO_ACCOUNT_ID>"
    }
  }'
```

The destination's authentication settings map to your Twilio credentials as follows:

| Setting       | Value              | Location                                      |
| ------------- | ------------------ | --------------------------------------------- |
| username      | Twilio API Key     | Go to **Builder tools** > **API Key & creds** |
| password      | Twilio API Secret  | Display when you create the API Key           |
| twilioAccount | Twilio Account SID | Display on the Twilio Console homepage        |

Save the destination ID from the response. Use a unique, descriptive name for the destination to identify it and enable reuse.

### Create an audience

To create an audience in your Engage space using Compute Query Language (CQL):

```bash
curl -s -X POST "https://api.segmentapis.com/spaces/<SPACE_ID>/audiences" \
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
  -H "Content-Type: application/vnd.segment.v1alpha+json" \
  -d '{
    "name": "Conversation Memory Audience",
    "audienceType": "USERS",
    "enabled": true,
    "description": "Profiles synced to Conversation Memory",
    "definition": {
      "query": "trait('"'"'firstName'"'"').exists() OR trait('"'"'firstName'"'"').absent()"
    },
    "options": { "includeHistoricalData": true }
  }'
```

Save the audience ID from the response.

### Connect the destination to the audience and configure ID sync

Use the following to create a destination connection on the audience. The `idSyncConfiguration` array controls which external identifiers Segment syncs to Conversation Memory and the resolution strategy for each:

```bash
curl -s -X POST \
  "https://api.segmentapis.com/spaces/<SPACE_ID>/audiences/<AUDIENCE_ID>/destination-connections" \
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
  -H "Content-Type: application/vnd.segment.v1alpha+json" \
  -d '{
    "destination": { "id": "<DESTINATION_ID>", "type": "destination" },
    "idSyncConfiguration": [
      { "externalId": "user_id", "strategy": "first" },
      { "externalId": "email", "strategy": "first" },
      { "externalId": "phone", "strategy": "first" }
    ]
  }'
```

| External ID | Strategy | Description                                  |
| ----------- | -------- | -------------------------------------------- |
| user\_id    | first    | Sync the first known user ID for the profile |
| email       | first    | Sync the first known email for the profile   |
| phone       | first    | Sync the first known phone for the profile   |

Save the connection ID from the response.

### Activate the audience with trait enrichments

To create an activation on the connection, run the following. The `destinationMapping` maps profile traits to Conversation Memory fields using `@path` expressions. Use the `actionId` you retrieved from the catalog metadata earlier, and your Conversation Memory Store ID:

```bash
curl -s -X POST \
  "https://api.segmentapis.com/spaces/<SPACE_ID>/audiences/<AUDIENCE_ID>/destination-connections/<CONNECTION_ID>/activations" \
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
  -H "Content-Type: application/vnd.segment.v1alpha+json" \
  -d '{
    "activationName": "memora_audience_sync",
    "activationType": "Audience Membership Changed",
    "enabled": true,
    "performResync": true,
    "destinationMapping": {
      "actionId": "<ACTION_ID>",
      "settings": {
        "memora_store": "<MEMORA_STORE_ID>",
        "enable_batching": true,
        "batch_size": 1000,
        "profile_identifiers": {
          "Contact.$.email": { "@path": "$.traits.email" },
          "Contact.$.phone": { "@path": "$.traits.phone" }
        },
        "profile_traits": {
          "Contact.$.firstName": { "@path": "$.traits.firstName" },
          "Contact.$.lastName":  { "@path": "$.traits.lastName" },
          "Contact.$.city":      { "@path": "$.traits.city" },
          "Contact.$.country":   { "@path": "$.traits.country" }
        }
      }
    }
  }'
```

Conversation Memory organizes traits into trait groups, so each destination field uses the `TraitGroupName.$.traitName` format (for example, `Contact.$.email`). Map at least one identifier trait. Every event must include at least one non-null identifier and at least two total non-null fields.

Once the activation is created and enabled, Segment syncs audience members to your Conversation Memory Store. You can confirm delivery in [Delivery Overview](/docs/segment/connections/delivery-overview).