Skip to content Skip to navigation Skip to topbar

Retrieve Memories

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

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.

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredPIIDescription

accept-Encodingstring

Optional

Compression algorithms supported by the client (e.g., gzip, deflate, br)

Example: gzip, deflate, brPattern: ^[a-zA-Z0-9, .-]*$Max length: 200

content-Encodingenum<string>

Optional

Compression algorithm used for the request body (e.g., gzip, deflate, br)

Example: gzipPossible values:

gzipdeflatebrcompress

Path parameters

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}$

profileIdstring

required

The unique identifier for the profile using Twilio Type ID (TTID) format.

Example: mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

conversationIdstring

Optional

Required for session memory and query expansion.

Example: conv_conversation_00000000000000000000000000Pattern: ^conv_conversation_[0-7][0-9a-z]{25}$

querystring

Optional

Hybrid search query for finding relevant memories. Omit to use query expansion to generate query from previous 10 communications in conversation.

Example: customer satisfaction feedbackMin length: 0Max length: 1024

beginDatestring<date-time>

Optional

Start date for filtering memories (inclusive).

Example: 2025-01-01T00:00:00Z

endDatestring<date-time>

Optional

End date for filtering memories (exclusive).

Example: 2025-01-31T23:59:59Z

communicationsLimitinteger

Optional

Maximum number of conversational session memories to return. If omitted or set to 0, no session memories will be fetched.

Default: 0Example: 10Minimum: 0Maximum: 100

observationsLimitinteger

Optional

Maximum number of observation memories to return. If omitted, defaults to 20. If set to 0, no observation memories will be fetched.

Default: 20Example: 20Minimum: 0Maximum: 100

summariesLimitinteger

Optional

Maximum number of summary memories to return. If omitted, defaults to 5. If set to 0, no summary memories will be fetched.

Default: 5Example: 5Minimum: 0Maximum: 100

relevanceThresholdnumber<double>

Optional

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

Default: 0Example: 0.5Minimum: 0Maximum: 1

Responses

200308400401403404429500503

Memory retrieval results returned successfully.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

observationsarray[object]

Optional

Array of observation memories.

Max items: 100

Show observations properties

summariesarray[object]

Optional

Array of summary memories derived from observations at the end of conversations.

Max items: 100

Show summaries properties

communicationsarray[object]

Optional

Array of recent communication context.

Min items: 0Max items: 100

Show communications properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Unique communication identifier.

Example: conv_communication_00000000000000000000000000Pattern: ^conv_communication_[0-7][0-9a-z]{25}$

channelIdstring

Optional

Channel-specific ID (optional).

Example: SM00000000000000000000000000000000Max length: 256

contentobject

Optional

Content of a communication.

Show content properties

createdAtstring<date-time>

Optional

When communication was created.

Example: 2025-01-15T10:15:30Z

updatedAtstring<date-time>

Optional

When communication was last updated.

Example: 2025-01-15T10:20:30Z

authorobject

Optional

Show author properties

recipientsarray[object]

Optional

Communication recipients

Max items: 100

Show recipients properties

metaobject

Optional

Metadata about the retrieval operation.

Show meta properties

This resource has moved.

Schema

Property nameTypeRequiredPIIDescriptionChild properties

messagestring

Optional

Default: This resource has moved.Example: This resource has moved.Max length: 255

uristring

Optional

Example: https://memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000Max length: 2048

Bad Request

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Unauthorized

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Forbidden

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Not Found

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Internal Server Error

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Service Unavailable

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Request examples

Retrieve Memories

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createFetchProfileMemory() {
11  const recall = await client.memory.v1
12    .recall(
13      "mem_store_00000000000000000000000000",
14      "mem_profile_00000000000000000000000000"
15    )
16    .create({
17      conversationId: "conv_conversation_00000000000000000000000000",
18      query: "customer satisfaction feedback",
19      communicationsLimit: 10,
20      observationsLimit: 20,
21      summariesLimit: 5,
22    });
23
24  console.log(recall.observations);
25}
26
27createFetchProfileMemory();

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": 156
16  }
17}