Segment Conversation Memory Integration

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.

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

The systems differ in the following ways:

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.

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

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

1. Create or select a memory store
2. Find a profile in a memory store
3. Connect your Twilio account to Segment
4. Create mappings

1. Sign in to the Twilio Console.
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.

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.

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.

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.

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.

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.

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

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, where you can filter by memory store and date range.

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

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.

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.

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

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.

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.

You can track sync activity in Segment's 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.

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.

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.

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.

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

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

1
curl -s "https://api.segmentapis.com/sources" \
2
  -H "Authorization: Bearer $SEGMENT_TOKEN" | \
3
  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.

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

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

Then, create the destination:

1
curl -s -X POST "https://api.segmentapis.com/destinations" \
2
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "sourceId": "<SOURCE_ID>",
6
    "metadataId": "695d30cdac2addbdcc3baf7f",
7
    "name": "Conversation Memory",
8
    "enabled": true,
9
    "settings": {
10
      "username": "<TWILIO_API_KEY>",
11
      "password": "<TWILIO_API_SECRET>",
12
      "twilioAccount": "<TWILIO_ACCOUNT_ID>"
13
    }
14
  }'

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

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

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

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

Save the audience ID from the response.

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:

1
curl -s -X POST \
2
  "https://api.segmentapis.com/spaces/<SPACE_ID>/audiences/<AUDIENCE_ID>/destination-connections" \
3
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
4
  -H "Content-Type: application/vnd.segment.v1alpha+json" \
5
  -d '{
6
    "destination": { "id": "<DESTINATION_ID>", "type": "destination" },
7
    "idSyncConfiguration": [
8
      { "externalId": "user_id", "strategy": "first" },
9
      { "externalId": "email", "strategy": "first" },
10
      { "externalId": "phone", "strategy": "first" }
11
    ]
12
  }'

Save the connection ID from the response.

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:

1
curl -s -X POST \
2
  "https://api.segmentapis.com/spaces/<SPACE_ID>/audiences/<AUDIENCE_ID>/destination-connections/<CONNECTION_ID>/activations" \
3
  -H "Authorization: Bearer $SEGMENT_TOKEN" \
4
  -H "Content-Type: application/vnd.segment.v1alpha+json" \
5
  -d '{
6
    "activationName": "memora_audience_sync",
7
    "activationType": "Audience Membership Changed",
8
    "enabled": true,
9
    "performResync": true,
10
    "destinationMapping": {
11
      "actionId": "<ACTION_ID>",
12
      "settings": {
13
        "memora_store": "<MEMORA_STORE_ID>",
14
        "enable_batching": true,
15
        "batch_size": 1000,
16
        "profile_identifiers": {
17
          "Contact.$.email": { "@path": "$.traits.email" },
18
          "Contact.$.phone": { "@path": "$.traits.phone" }
19
        },
20
        "profile_traits": {
21
          "Contact.$.firstName": { "@path": "$.traits.firstName" },
22
          "Contact.$.lastName":  { "@path": "$.traits.lastName" },
23
          "Contact.$.city":      { "@path": "$.traits.city" },
24
          "Contact.$.country":   { "@path": "$.traits.country" }
25
        }
26
      }
27
    }
28
  }'

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.