Skip to main content

​
Initial set up

Import required modules for Threads, Messages, Feedback, and Users. More details about these concepts and data types can be found on the overview page. Find our SDKs on GitHub: Python | TypeScript 
from melodi.melodi_client import MelodiClient
from melodi.feedback.data_models import Feedback
from melodi.threads.data_models import Message, Thread
from melodi.users.data_models import User

​
Set up the Melodi client

Your API key can be found in Settings. For more information, see API Access. 
import os

os.environ["MELODI_API_KEY"] = "<YOUR_KEY>"

client = MelodiClient(verbose=True)

​
Create a project

Projects can also be created via the UI. 
new_project = client.projects.create("Melodi SDK Test")

print(new_project.id)

​
Create a thread in Melodi

Threads are a flexible data format that support customizable message types, including user, AI response, RAG lookup, and other. You can optionally specify when a thread was created using the createdAt field. 
melodiClient = MelodiClient(verbose=True)

threadExternalId = "external-thread-id-1"

externalUser = User(
    externalId="test-user-id-1",
    name="Test User",
    email="test-user@example.com",
    segments={
      "team": "engineering",
    }
)

message1 = Message(
    externalId="1",
    role='user',
    content='Hello!',
)

message2 = Message(
    externalId="2",
    role='assistant',
    content='Hi! How can I help you today?',
)

message3 = Message(
    externalId="3",
    role='user',
    content="What's the company's primary brand color?",
)

message4 = Message(
    externalId="4",
    role='RAG lookup',
    type='json',
    jsonContent={
        "BrandColorInfo": {
            "type": "primary",
            "color": "blue",
            "hexCode": "#1570EF"
        }
    }
)

message5 = Message(
    externalId="5",
    role='assistant',
    content="The company's primary brand color is blue #1570EF.",
)

thread = Thread(
    projectName="Melodi SDK Test",
    externalId=threadExternalId,
    messages=[message1, message2, message3, message4, message5],
    externalUser=externalUser,
    createdAt=datetime(2024, 1, 1, 12, 0, 0)  # Example date
)
melodi_thread = melodiClient.threads.create_or_update(thread)

print(melodi_thread)

​
Add feedback to the thread

​
Add basic positive/negative feedback

Feedback can be added to a thread to provide additional context about the conversation. 
feedback = Feedback(
    # externalThreadId is required if providing an externalMessageId
    externalThreadId=threadExternalId,
    feedbackText="I don't understand",
    feedbackType="NEGATIVE"
)

melodi_feedback = melodiClient.feedback.create(feedback)
print(melodi_feedback)

​
Add feedback with attributes

Attributes are additional metadata that can be added to feedback that becomes filterable in the UI. Feedback attributes can be created from the Settings page.
These attributes and options need to already exist in your organization or this call will fail
feedback_with_attributes = Feedback(
    externalThreadId=threadExternalId,
    feedbackText="This is so funny",

    # These attributes and options need to already exist in your organization
    # Or this call will fail
    attributes={
      "Humor Level": "High",
    }
)

melodi_feedback_with_attributes = melodiClient.feedback.create(feedback_with_attributes)
print(melodi_feedback_with_attributes)

​
Create or update a user

You can create or update users in Melodi to associate with threads. 
user = User(
    externalId="test-user-id-2",
    name="Different User",
    email="differentuser@example.com",
    segments={
      "team": "sales",
    }
)

melodi_user = client.users.create_or_update(user)
print(melodi_user)

​
Backdate threads

When importing historical conversations or maintaining accurate timestamps, you can specify when a thread was created using the createdAt field. This is particularly useful when:
  • Importing historical conversations from another system
  • Maintaining accurate timestamps for analytics
  • Recording conversations that happened in the past
thread = Thread(
    projectName="Melodi SDK Test",
    externalId=threadExternalId,
    messages=[message1, message2, message3, message4, message5],
    externalUser=externalUser,
    createdAt=datetime(2024, 1, 1, 12, 0, 0)  # Example date
)
⌘I