Adding Messages

You can add both messages and business data to User Graphs.

Adding Messages

Add your chat history to Zep using the thread.add_messages method. thread.add_messages is thread-specific and expects data in chat message format, including a name (e.g., user’s real name), a role of user, assistant, system, function, tool, or norole, and message content. Zep stores the chat history and builds a user-level Context Graph from the messages.

thread.add_messages is the recommended path for live conversation turns. To backfill past conversations, use zep-ingest. For an individual business-data write, use graph.add. Ingest compares the paths.

Basic example

The example below adds messages to Zep for the user in the given thread:

1
from zep_cloud.client import Zep
2
from zep_cloud.types import Message
3
4
zep_client = Zep(
5
    api_key=API_KEY,
6
)
7
8
messages = [
9
    Message(
10
        name="Jane",
11
        role="user",
12
        content="Who was Octavia Butler?",
13
    )
14
]
15
16
response = zep_client.thread.add_messages(thread_id, messages=messages)

The SDK reference lists all thread.add_messages arguments. Set return_context to true to ingest messages and retrieve a Context Block in one request.

Ignore assistant messages

Use ignore_roles to exclude specified roles from graph ingestion. For example, set ignore_roles=["assistant"] to ingest only user messages.

Excluded assistant messages remain in the thread history. Zep also uses them to provide context for user messages such as “Yes.”

1
response = zep_client.thread.add_messages(
2
    thread_id,
3
    messages=messages,
4
    ignore_roles=["assistant"]
5
)

Creating messages with metadata

Messages can have metadata attached to store additional information like sentiment scores, source identifiers, processing flags, or other custom data. Metadata is preserved when getting threads, individual messages, and when searching episodes.

You can attach metadata when creating messages by including a metadata field in your message objects:

1
from zep_cloud.client import Zep
2
from zep_cloud.types import Message
3
4
zep_client = Zep(
5
    api_key=API_KEY,
6
)
7
8
messages = [
9
    Message(
10
        name="Jane",
11
        role="user",
12
        content="I need help with my account.",
13
        metadata={
14
            "sentiment": "frustrated",
15
            "source": "mobile_app",
16
            "priority": "high"
17
        }
18
    )
19
]
20
21
response = zep_client.thread.add_messages(thread_id, messages=messages)

Updating message metadata

You can update the metadata of an existing message using the message UUID. This is useful for adding or modifying metadata after a message has been created, such as updating sentiment analysis results or processing status.

1
from zep_cloud.client import Zep
2
3
zep_client = Zep(
4
    api_key=API_KEY,
5
)
6
7
# Update message metadata
8
updated_message = zep_client.thread.message.update(
9
    message_uuid="message-uuid-here",
10
    metadata={
11
        "sentiment": "positive",
12
        "resolved": True,
13
        "resolution_time": "2m 30s"
14
    }
15
)

Setting message timestamps

When creating messages via the API, you should provide the created_at timestamp in RFC3339 format. The created_at timestamp represents the time when the message was originally sent by the user. Setting the created_at timestamp is important to ensure the user’s Context Graph has accurate temporal understanding of user history (since this time is used in our fact invalidation process).

1
from zep_cloud.client import Zep
2
from zep_cloud.types import Message
3
4
zep_client = Zep(
5
    api_key=API_KEY,
6
)
7
8
messages = [
9
    Message(
10
        created_at="2025-06-01T13:11:12Z",
11
        name="Jane",
12
        role="user",
13
        content="What's the weather like today?",
14
    )
15
]
16
17
response = zep_client.thread.add_messages(thread_id, messages=messages)

Message limits

When adding messages to a thread, there are limits on both the number of messages and message size:

• Messages per call: You can add at most 30 messages in a single thread.add_messages call
• Message size limit: Each message can contain 4,096 characters by default. Accounts with the larger-message entitlement can send up to 14,000 characters.

If you exceed these limits, the API will return a 400 Bad Request error. If you need to add more than 30 messages or have messages exceeding the character limits, you’ll need to split them across multiple API calls or truncate the content accordingly. Our additional recommendations include:

• Have users attach documents rather than paste them into the message, and then process documents separately with graph.add
• Reduce the max message size for your users to match our max message size
• Optional: allow users to paste in documents with an auto detection algorithm that turns it into an attachment as opposed to part of the message

Check when messages are finished processing

You can use the message UUIDs from the response to poll the messages and check when they are finished processing:

1
response = zep_client.thread.add_messages(thread_id, messages=messages)
2
message_uuids = response.message_uuids

The check data ingestion status cookbook provides an example.

Adding Business Data

You can also add JSON or unstructured text to a User Graph using our Graph API.

Customizing Graph Creation

Zep offers two ways to customize how context is created. You can read more about these features at their guide pages:

• Custom entity and edge types: Feature allowing use of Pydantic-like classes to customize creation/retrieval of entities and relations in the Context Graph.
• User summary instructions: Specify how Zep generates user summaries with up to five instructions per user.