Skip to contentSkip to navigationSkip to topbar

Memory API (v1) - Trait Group endpoints


(information)

Legal information

Conversation Memory, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum(link takes you to an external page). For more details on AI usage and data, see the AI Nutrition Facts.

Conversation Memory is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

Conversation Memory is not intended for use with sensitive information about individuals. Twilio does not control what information comes from conversation channels and relies on you to ensure the data in customer profiles aligns with our acceptable use policy. Twilio does have limited guardrails in the form of a prompt exclusion that is designed to provide a minimal screening against inclusion of GDPR special category data(link takes you to an external page). As a reminder our profile technology uses generative artificial intelligence. Because generative artificial intelligence can make mistakes, review all outputs to ensure that the profile is correct.

Conversations products are only available in the new Twilio Console(link takes you to an external page). If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

Overview

overview page anchor

Tag description

Endpoints


Create a Trait Group

create-trait-group page anchor

POST/v1/ControlPlane/Stores/{storeId}/TraitGroups

Base url: https://memory.twilio.com (base url)

Creates a Trait Group with declarative trait schemas for this Memory Store.

Request

create-trait-group-request page anchor

Path parameters

create-trait-group-path-parameters page anchor
Property nameTypeRequiredPIIDescription
storeIdstring
required
Not PII

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
displayNamestring
required

Unique name of the Trait Group

Example: ContactPattern: ^[a-zA-Z0-9_\-\.]+$Min length: 1Max length: 64

descriptionstring

Optional

description of the Trait Group

Example: This Trait Group contains traits related to contact information.Max length: 1024

traitsobject

Optional

Map of traits belonging to this Trait Group, keyed by trait name.

Example: {"email":{"dataType":"STRING","description":"User's email address"},"dob":{"dataType":"STRING","description":"User's date of birth"}}Max properties: 95
202400404429500503

TraitGroup creation request accepted.

Schema
Property nameTypeRequiredPIIDescriptionChild properties
messagestring

Optional

Example: TraitGroup creation request accepted.Max length: 512

statusUrlstring

Optional

URI to check operation status.

Max length: 512
Create a Trait GroupLink to code sample: Create a Trait Group
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createTraitGroup() {
11
const traitGroup = await client.memory.v1
12
.traitGroups("mem_store_00000000000000000000000000")
13
.create({
14
displayName: "Contact",
15
});
16
17
console.log(traitGroup.message);
18
}
19
20
createTraitGroup();

Response

Note about this response
1
{
2
"message": "message",
3
"statusUrl": "statusUrl"
4
}

GET/v1/ControlPlane/Stores/{storeId}/TraitGroups

Base url: https://memory.twilio.com (base url)

Returns a list of Trait Groups for this Memory Store, with optional traits information.

Property nameTypeRequiredPIIDescription
storeIdstring
required

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
Property nameTypeRequiredPIIDescription
includeTraitsboolean

Optional

Whether to include trait definitions in the response

Default: false

pageSizeinteger

Optional

The maximum number of items to return per page, maximum of 100.

Default: 50Minimum: 1Maximum: 100

pageTokenstring

Optional

The token for the page of results to retrieve.

Max length: 500

orderByenum<string>

Optional

Either 'ASC' or 'DESC' to sort results ascending or descending respectively.

Default: DESCPossible values:
ASCDESC
200400404429500503

List of TraitGroups retrieved successfully

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
traitGroupsarray[object]

Optional

Max items: 50

metaobject

Optional

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listTraitGroups() {
11
const traitGroups = await client.memory.v1
12
.traitGroups("mem_store_00000000000000000000000000")
13
.list({
14
orderBy: "DESC",
15
limit: 20,
16
});
17
18
traitGroups.forEach((t) => console.log(t.displayName));
19
}
20
21
listTraitGroups();

Response

Note about this response
1
{
2
"meta": {
3
"key": "key",
4
"pageSize": 50,
5
"nextToken": "nextToken",
6
"previousToken": "previousToken"
7
},
8
"traitGroups": [
9
{
10
"displayName": "Contact",
11
"description": "description",
12
"traits": {},
13
"version": 3
14
}
15
]
16
}

Retrieve a Trait Group

fetch-trait-group page anchor

GET/v1/ControlPlane/Stores/{storeId}/TraitGroups/{traitGroupName}

Base url: https://memory.twilio.com (base url)

Retrieve a specific Trait Group by its unique name for this Memory Store, with optional traits information.

Property nameTypeRequiredPIIDescription
storeIdstring
required

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$

traitGroupNamestring
required

A unique Name of the TraitGroup

Example: ContactMin length: 1Max length: 64
Property nameTypeRequiredPIIDescription
includeTraitsboolean

Optional

Whether to include trait definitions in the response

Default: true

pageSizeinteger

Optional

The maximum number of items to return per page, maximum of 100.

Default: 50Minimum: 1Maximum: 100

pageTokenstring

Optional

The token for the page of results to retrieve.

Max length: 500

orderByenum<string>

Optional

Either 'ASC' or 'DESC' to sort results ascending or descending respectively.

Default: DESCPossible values:
ASCDESC
200400404429500503

TraitGroup retrieved successfully

Schema
Property nameTypeRequiredPIIDescriptionChild properties
traitGroupobject

Optional


metaobject

Optional

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchTraitGroup() {
11
const traitGroup = await client.memory.v1
12
.traitGroups("mem_store_00000000000000000000000000", "traitGroupName")
13
.fetch({
14
includeTraits: true,
15
orderBy: "DESC",
16
});
17
18
console.log(traitGroup.traitGroup);
19
}
20
21
fetchTraitGroup();

Response

Note about this response
1
{
2
"meta": {
3
"key": "key",
4
"pageSize": 50,
5
"nextToken": "nextToken",
6
"previousToken": "previousToken"
7
},
8
"traitGroup": {
9
"displayName": "Contact",
10
"description": "description",
11
"traits": {},
12
"version": 3
13
}
14
}

PATCH/v1/ControlPlane/Stores/{storeId}/TraitGroups/{traitGroupName}

Base url: https://memory.twilio.com (base url)

Partially updates a Trait Group. Only the fields provided in the request body will be updated. For traits: existing traits with matching keys will be updated, new keys will be added. To remove a trait, set its dataType to an empty string ("") - this serves as an explicit deletion marker.

Property nameTypeRequiredPIIDescription
if-Matchstring

Optional

Allows for optimistic concurrency control by making the request conditional. Server will only act if the resource's current Entity Tag (ETag) matches the one provided, preventing accidental overwrites.

Example: "eyJpZCI6ImFuX2lkIiwidiI6MX0"Max length: 100
Property nameTypeRequiredPIIDescription
storeIdstring
required

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$

traitGroupNamestring
required

A unique Name of the TraitGroup

Example: ContactMin length: 1Max length: 64
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
descriptionstring

Optional

Updated description of the Trait Group

Example: Updated Trait Group contains traits related to contact information.Max length: 1024

traitsobject

Optional

Map of traits to add, update, or remove in this Trait Group, where the key is the trait name. - To update/add a trait: provide the complete TraitDefinition object - To remove a trait: set dataType to an empty string ("")

Max properties: 95
202400404429500503

TraitGroup update request accepted for processing.

Schema
Property nameTypeRequiredPIIDescriptionChild properties
messagestring

Optional

Example: TraitGroup update request accepted.Max length: 512

statusUrlstring

Optional

URI to check operation status.

Max length: 512
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function patchTraitGroup() {
11
const traitGroup = await client.memory.v1
12
.traitGroups("mem_store_00000000000000000000000000", "traitGroupName")
13
.patch({
14
description: "description",
15
});
16
17
console.log(traitGroup.message);
18
}
19
20
patchTraitGroup();

Response

Note about this response
1
{
2
"message": "message",
3
"statusUrl": "statusUrl"
4
}

Delete a Trait Group

delete-trait-group page anchor

DELETE/v1/ControlPlane/Stores/{storeId}/TraitGroups/{traitGroupName}

Base url: https://memory.twilio.com (base url)

Deletes the Trait Group and all associated Traits from the Memory Store.

Property nameTypeRequiredPIIDescription
storeIdstring
required

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$

traitGroupNamestring
required

A unique Name of the TraitGroup

Example: ContactMin length: 1Max length: 64
202400404409429500503

TraitGroup deletion request accepted.

Schema
Property nameTypeRequiredPIIDescriptionChild properties
messagestring

Optional

Example: TraitGroup deletion request accepted.Max length: 512

statusUrlstring

Optional

URI to check operation status.

Max length: 512
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function deleteTraitGroup() {
11
await client.memory.v1
12
.traitGroups("mem_store_00000000000000000000000000", "traitGroupName")
13
.remove();
14
}
15
16
deleteTraitGroup();

Response

Note about this response
1
{
2
"message": "message",
3
"statusUrl": "statusUrl"
4
}