Skip to content Skip to navigation Skip to topbar

Memory API (v1) - Event 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. 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.

Overview

Tag description

Endpoints

/v1/Stores/{storeId}/Profiles/{profileId}/Events

Add events to a specific profile

Add events to a specific profile

POST/v1/Stores/{storeId}/Profiles/{profileId}/Events

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

Multiple events can be added to a profile in a single request. The maximum number of events per request is 1000 and they will be processed asynchronously.

Any traits that are configured for identifier promotion will be set as an identifier value on the profile.

Types of events:

twilio-communication-event - Twilio communication event, used for tracking multi-channel communications.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

storeIdstring

required

The storeId identifier

profileIdstring

required

The profileId identifier

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

typeenum<string>

required

The type of event being sent.

Example: twilio-comms-lifecyclePossible values:

twilio-communication-eventtwilio-comms-lifecycle

events

array(oneOf):

required

Max items: 1000

Show events properties

Property nameTypeRequiredPIIDescriptionChild properties

timestampstring<date-time>

required

The time the event occurred in ISO8601 format with millisecond resolution. Defaults to received time if not provided.

Example: 2025-01-01T12:00:00.000Z

lifecyclestring

required

The lifecycle event type of the communication.

Example: COMMUNICATION_SENTMax length: 50

conversationIdstring

required

The unique identifier for the conversation.

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

communicationIdstring

Optional

The unique identifier for the communication.

Example: comms_communication_00000000000000000000000000Pattern: ^comms_communication_[0-7][0-9a-z]{25}$

communicationTypestring

required

The communication channel type.

Example: SMSMax length: 20

communicationStatusstring

Optional

The lifecycle status of the communication.

Example: SENTMax length: 20

directionenum<string>

Optional

The direction of the communication.

Example: OUTBOUNDPossible values:

INBOUNDOUTBOUND

senderobject

Optional

Show sender properties

recipientobject

Optional

Show recipient properties

errorCodestring

Optional

Error code for FAILED communication status.

Example: 30001Max length: 10

errorMessagestring

Optional

Error message for FAILED communication status.

Example: phone number is invalidMax length: 512

Responses

202400404429500503

Events accepted for processing.

Schema

Property nameTypeRequiredPIIDescriptionChild properties

messagestring

Optional

Example: Events accepted for processing.Max length: 1024

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

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

Add events to a specific profile

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 createProfileEvents() {
11  const event = await client.memory.v1.events("storeId", "profileId").create({
12    type: "twilio-comms-lifecycle",
13    events: [
14      {
15        timestamp: "2009-07-06T20:30:00Z",
16        lifecycle: "lifecycle",
17        conversationId: "conv_conversation_00000000000000000000000000",
18        communicationId: "comms_communication_00000000000000000000000000",
19        communicationType: "communicationType",
20        communicationStatus: "communicationStatus",
21        direction: "OUTBOUND",
22        sender: {
23          address: "address",
24          participantId: "comms_participant_00000000000000000000000000",
25        },
26        recipient: {
27          address: "address",
28          participantId: "comms_participant_00000000000000000000000000",
29        },
30        errorCode: "errorCode",
31        errorMessage: "errorMessage",
32      },
33    ],
34  });
35
36  console.log(event.message);
37}
38
39createProfileEvents();

Response

1{
2  "message": "message"
3}