Memory API (v1) - Retrieval 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.
Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.
Retrieve Memories
Lookup Profiles
POST/v1/Stores/{storeId}/Profiles/{profileId}/Recall
Base url: https://memory.twilio.com (base url)
Tailored memory retrieval for agentic workloads. Supports hybrid semantic search, date ranges, and configurable result limits for different memory types. This endpoint is optimized for conversational AI and memory retrieval use cases. If a query is not specified then one is inferred from the conversation context. If neither a query nor a conversationId is provided, results are returned in most-recent order without relevance scores.
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/jsonRequired for session memory and query expansion.
conv_conversation_00000000000000000000000000Pattern: ^conv_conversation_[0-7][0-9a-z]{25}$Hybrid search query for finding relevant memories. Omit to use query expansion to generate query from previous 10 communications in conversation.
customer satisfaction feedbackMin length: 0Max length: 1024Start date for filtering memories (inclusive).
2025-01-01T00:00:00ZEnd date for filtering memories (exclusive).
2025-01-31T23:59:59ZMaximum number of conversational session memories to return. If omitted or set to 0, no session memories will be fetched.
0Example: 10Minimum: 0Maximum: 100Maximum number of observation memories to return. If omitted, defaults to 20. If set to 0, no observation memories will be fetched.
20Example: 20Minimum: 0Maximum: 100Maximum number of summary memories to return. If omitted, defaults to 5. If set to 0, no summary memories will be fetched.
5Example: 5Minimum: 0Maximum: 100Minimum relevance score threshold for observations and summaries to be returned. Only memories with a relevance score greater than or equal to this threshold will be included in the response. This threshold only applies when results are ranked by relevance. When results are returned in most-recent order, this field has no effect.
0Example: 0.5Minimum: 0Maximum: 1Memory retrieval results returned successfully.
Array of observation memories.
100Array of summary memories derived from observations at the end of conversations.
100Array of recent communication context.
0Max items: 1001// 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 createFetchProfileMemory() {11const recall = await client.memory.v112.recall(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000"15)16.create({17conversationId: "conv_conversation_00000000000000000000000000",18});1920console.log(recall.observations);21}2223createFetchProfileMemory();
Response
1{2"observations": [3{4"id": "mem_observation_00000000000000000000000001",5"content": "Customer expressed satisfaction with recent product update during support call.",6"source": "customer_service",7"occurredAt": "2025-01-15T10:15:30Z",8"createdAt": "2025-01-15T10:30:45Z",9"updatedAt": "2025-01-15T10:30:45Z"10}11],12"summaries": [],13"communications": [],14"meta": {15"queryTime": 15616}17}
POST/v1/Stores/{storeId}/Profiles/Lookup
Base url: https://memory.twilio.com (base url)
Find profiles that contain a specific identifier value (for example a phone number or email address). Submit an identifier object specifying the idType and value. The value is normalized using the configured identity resolution settings (such as phone number formatting) prior to matching. Multiple matches are returned if more than one profile is associated with the identifier. Returns canonical profile IDs (the earliest ID if profiles have been merged) along with the normalized value actually searched.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$application/jsonIdentifier type as configured in the service's Identity Resolution Settings.
phoneMin length: 2Max length: 30Raw value captured for the identifier. The service may normalize this value according to the normalization rule defined in the identifier settings before storage or matching (for example E.164 formatting for phone numbers).
+13175556789Max 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 createProfilesLookup() {11const lookup = await client.memory.v112.lookup("mem_store_00000000000000000000000000")13.create({14idType: "idType",15value: "value",16});1718console.log(lookup.normalizedValue);19}2021createProfilesLookup();
Response
1{2"normalizedValue": "normalizedValue",3"profiles": [4"mem_profile_00000000000000000000000000"5]6}