Memory API (v1) - Observations endpoints
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. 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. 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.
Create Observations
List Observations
Retrieve Observation
List Observation Revisions
POST/v1/Stores/{storeId}/Profiles/{profileId}/Observations
Base url: https://memory.twilio.com (base url)
Create one or more transient observations associated with the specified profile. Supports both single observation creation and batch creation of up to 10 observations. Supports request compression for large batch operations and response compression for the response. All observations will be automatically indexed for semantic search capabilities. The content can be up to 4KB in length and should contain relevant information about the profile. The createdAt and updatedAt timestamps will be automatically set to the current time. Each observation will be created with a unique ID in Twilio Type ID (TTID) format.
Compression algorithms supported by the client (e.g., gzip, deflate, br)
gzip, deflate, brPattern: ^[a-zA-Z0-9, .-]*$Max length: 200Compression algorithm used for the request body (e.g., gzip, deflate, br)
gzipPossible values: gzipdeflatebrcompressA unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$application/jsonArray of observations to create in a single batch operation.
1Max items: 10Observation creation accepted and is being processed.
Confirmation message for the operation.
Observations creation acceptedMin length: 1Max length: 2551// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createProfileObservation() {11const observation = await client.memory.v112.observations(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000"15)16.create({17observations: [18{19content: "content",20occurredAt: "2009-07-06T20:30:00Z",21source: "conversational-intelligence",22conversationIds: ["conv_conversation_00000000000000000000000000"],23},24],25});2627console.log(observation.message);28}2930createProfileObservation();
Response
1{2"message": "message"3}
GET/v1/Stores/{storeId}/Profiles/{profileId}/Observations
Base url: https://memory.twilio.com (base url)
Retrieve a paginated list of transient observations for a specific profile. Observations are sorted by creation time in descending order by default. Results can be filtered by source parameter. Supports response compression for large datasets.
Compression algorithms supported by the client (e.g., gzip, deflate, br)
gzip, deflate, brPattern: ^[a-zA-Z0-9, .-]*$Max length: 200A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$The maximum number of items to return per page, maximum of 1000.
50Minimum: 1Maximum: 1000Either 'ASC' or 'DESC' to sort results ascending or descending respectively.
DESCPossible values: ASCDESCFilter by source. Allows letters, numbers, spaces, and URL-safe symbols. Excludes URL-unsafe characters like quotes, angle brackets, and control characters.
customer service platformPattern: ^[a-zA-Z0-9 _.-]+$Min length: 1Max length: 100Filter observations created after this timestamp (inclusive).
2025-01-01T00:00:00ZFilter observations created before this timestamp (exclusive).
2025-01-31T23:59:59Z1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listProfileObservations() {11const observations = await client.memory.v112.observations(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000"15)16.list({17orderBy: "DESC",18limit: 20,19});2021observations.forEach((o) => console.log(o.content));22}2324listProfileObservations();
Response
1{2"meta": {3"key": "key",4"pageSize": 50,5"nextToken": "nextToken",6"previousToken": "previousToken"7},8"observations": [9{10"content": "content",11"occurredAt": "2009-07-06T20:30:00Z",12"source": "conversational-intelligence",13"conversationIds": [14"conv_conversation_00000000000000000000000000"15],16"id": "mem_observation_00000000000000000000000000",17"createdAt": "2009-07-06T20:30:00Z",18"updatedAt": "2009-07-06T20:30:00Z"19}20]21}
GET/v1/Stores/{storeId}/Profiles/{profileId}/Observations/{observationId}
Base url: https://memory.twilio.com (base url)
Retrieve a specific transient observation by its ID for the given profile.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$The observation ID.
mem_observation_00000000000000000000000000Pattern: ^mem_observation_[0-7][0-9a-z]{25}$Observation retrieved successfully.
The main content of the observation.
Customer expressed satisfaction with recent product update during support call.Min length: 1Max length: 4096The timestamp when the observation originally occurred.
2025-01-15T10:15:30ZThe source system that generated this observation. Allows letters, numbers, spaces, and URL-safe symbols. Excludes URL-unsafe characters like quotes, angle brackets, and control characters.
conversational-intelligencePattern: ^[a-zA-Z0-9 _.-]+$Min length: 1Max length: 100Array of conversation IDs associated with this observation.
10A unique identifier for the observation using Twilio Type ID (TTID) format.
mem_observation_00000000000000000000000000Pattern: ^mem_observation_[0-7][0-9a-z]{25}$The timestamp when the observation was created.
2025-01-15T10:30:45ZThe timestamp when the observation was last updated.
2025-01-15T10:30:45Z1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchProfileObservation() {11const observation = await client.memory.v112.observations(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000",15"mem_observation_00000000000000000000000000"16)17.fetch();1819console.log(observation.content);20}2122fetchProfileObservation();
Response
1{2"id": "mem_observation_00000000000000000000000001",3"content": "Customer expressed frustration with billing process during call on 2025-01-15. Mentioned difficulty understanding charges.",4"source": "customer_service",5"occurredAt": "2025-01-15T14:30:00Z",6"conversationIds": [7"conv_conversation_00000000000000000000000000"8],9"createdAt": "2025-01-15T10:30:45Z",10"updatedAt": "2025-01-15T10:30:45Z"11}
PATCH/v1/Stores/{storeId}/Profiles/{profileId}/Observations/{observationId}
Base url: https://memory.twilio.com (base url)
Update a specific transient observation by its ID. Only provided fields will be updated. The updated timestamp will be automatically set. This allows for selective updates without needing to provide all fields.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$The observation ID.
mem_observation_00000000000000000000000000Pattern: ^mem_observation_[0-7][0-9a-z]{25}$application/jsonThe main content of the observation.
Customer expressed satisfaction with recent product update during support call.Min length: 1Max length: 4096The timestamp when the observation originally occurred.
2025-01-15T10:15:30ZThe source system that generated this observation. Allows letters, numbers, spaces, and URL-safe symbols. Excludes URL-unsafe characters like quotes, angle brackets, and control characters.
conversational-intelligencePattern: ^[a-zA-Z0-9 _.-]+$Min length: 1Max length: 100Array of conversation IDs associated with this observation.
10Observation update accepted and is being processed.
Observation update acceptedMax length: 5121// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function patchProfileObservation() {11const observation = await client.memory.v112.observations(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000",15"mem_observation_00000000000000000000000000"16)17.patch({18content: "content",19occurredAt: "2009-07-06T20:30:00Z",20source: "conversational-intelligence",21});2223console.log(observation.message);24}2526patchProfileObservation();
Response
1{2"message": "message"3}
DELETE/v1/Stores/{storeId}/Profiles/{profileId}/Observations/{observationId}
Base url: https://memory.twilio.com (base url)
Delete a specific transient observation by its ID. This action is irreversible.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$The observation ID.
mem_observation_00000000000000000000000000Pattern: ^mem_observation_[0-7][0-9a-z]{25}$Observation deletion accepted and is being processed.
Observation deletion acceptedMax length: 2551// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteProfileObservation() {11await client.memory.v112.observations(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000",15"mem_observation_00000000000000000000000000"16)17.remove();18}1920deleteProfileObservation();
Response
1{2"message": "message"3}
GET/v1/Stores/{storeId}/Profiles/{profileId}/Observations/{observationId}/Revisions
Base url: https://memory.twilio.com (base url)
Retrieve a chronologically ordered list of all past revisions of a specific observation by its ID. Revisions represent the complete history of updates and modifications made to an observation, with each revision capturing the full state at the time of change. Revisions are sorted by update time in descending order (newest first), allowing you to track how an observation has evolved through updates over time.
Compression algorithms supported by the client (e.g., gzip, deflate, br)
gzip, deflate, brPattern: ^[a-zA-Z0-9, .-]*$Max length: 200A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$The observation ID.
mem_observation_00000000000000000000000000Pattern: ^mem_observation_[0-7][0-9a-z]{25}$The maximum number of items to return per page, maximum of 1000.
50Minimum: 1Maximum: 1000The token for the page of results to retrieve.
500A chronologically ordered list of observation revisions.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listObservationRevisions() {11const revisions = await client.memory.v112.revisions(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000",15"mem_observation_00000000000000000000000000"16)17.list({ limit: 20 });1819revisions.forEach((r) => console.log(r.content));20}2122listObservationRevisions();
Response
1{2"revisions": [3{4"id": "mem_observation_00000000000000000000000001",5"content": "Updated: Customer expressed satisfaction with recent product update during support call. Follow-up scheduled.",6"source": "customer_service",7"occurredAt": "2025-01-15T14:30:00Z",8"createdAt": "2025-01-15T10:30:45Z",9"updatedAt": "2025-01-15T14:20:15Z"10},11{12"id": "mem_observation_00000000000000000000000001",13"content": "Customer expressed frustration with billing process during call on 2025-01-15. Mentioned difficulty understanding charges.",14"source": "customer_service",15"occurredAt": "2025-01-15T14:30:00Z",16"createdAt": "2025-01-15T10:30:45Z",17"updatedAt": "2025-01-15T10:30:45Z"18}19],20"meta": {21"pageSize": 2,22"nextToken": "eyJlYXN0ZXIiOiJlZ2cifQ",23"key": "revisions"24}25}