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), role (AI, human, tool), and message content. Zep stores the chat history and builds a user-level Context Graph from the messages.

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)

You can find additional arguments to thread.add_messages in the SDK reference. Notably, for latency sensitive applications, you can set return_context to true which will make thread.add_messages return a context block in the way that thread.get_user_context does (discussed below).

Ignore assistant messages

You can also pass in a list of roles to ignore when adding messages to a User Graph using the ignore_roles argument. For example, you may not want assistant messages to be added to the user graph; providing the assistant messages in the thread.add_messages call while setting ignore_roles to include “assistant” will make it so that only the user messages are ingested into the graph, but the assistant messages are still used to contextualize the user messages. This is important in case the user message itself does not have enough context, such as the message “Yes.” Additionally, the assistant messages will still be added to the thread’s message history.

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 be at most 4,096 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

An example of this can be found in the check data ingestion status cookbook.

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: Customize how Zep generates entity summaries for users in their Context Graph with up to 5 custom instructions per user.