Publishing Interactions

Publish text, image, expert-reviewed, and user-action interaction payloads, then inspect or search raw interaction records.

Publishing Interactions

Use this page when you need examples for the interaction payload itself: text turns, images, screenshots, expert-reviewed content, and user action tracking. For method-level details, see the Interactions API Reference.

How this differs from Request Management

This page focuses on what goes inside interactions. Use Request Management when you need to choose session_id, source, or agent_version, inspect stored requests, filter by time, or delete request/session data.

Setup

import reflexio
import base64

client = reflexio.ReflexioClient()  # uses REFLEXIO_API_KEY env var
# Self-hosted: client = reflexio.ReflexioClient(url_endpoint="http://localhost:8081")

Which Example Should I Use?

Use case	Follow this example	What it teaches
Normal chat or support turns	Simple Conversations	Publish one user-agent turn per request while keeping the same session for the conversation.
The user shares a photo or visual artifact	Image-Based Interactions	Attach base64 image data alongside the user's text so Reflexio can learn from visual context.
Bug reports, UI feedback, or screen-level evidence	Screenshots and UI Feedback	Store screenshots with user comments and optional action details.
A human reviewer knows the ideal answer	Expert-Reviewed Conversations	Provide `expert_content` so Reflexio can learn from the preferred response, not only the agent's original answer.
You need behavior signals beyond messages	E-commerce Actions	Capture clicks, scrolls, page URLs, and lightweight action descriptions as interaction data.
You need to inspect raw stored interactions	Searching and Analyzing Interactions	Search or list raw interaction records for debugging, review, or offline analysis.

Text-Based Interactions

Use text examples for ordinary conversational traffic: chatbots, support agents, copilots, and assistants that exchange user and agent messages.

Simple Conversations

Use this pattern for ordinary multi-turn conversations. Keep the same session_id for all turns in the same conversation; see Request Management for naming and lifecycle guidance.

# Publishing a customer service conversation
# Each request contains a user message followed by agent response (one turn)
# Use the same session_id for all turns in a conversation thread

session_id = "support_session_001"

# Turn 1: User asks, agent responds
client.publish_interaction(
    user_id="customer_001",
    interactions=[
        {"role": "User", "content": "Hi, I'm having trouble with my account login"},
        {"role": "Agent", "content": "I'm sorry to hear that. Can you tell me what error message you're seeing?"}
    ],
    session_id=session_id,
    source="support_chat"
)

# Turn 2: User follows up, agent responds (same session_id)
client.publish_interaction(
    user_id="customer_001",
    interactions=[
        {"role": "User", "content": "It says 'Invalid credentials' but I'm sure my password is correct"},
        {"role": "Agent", "content": "Let me help you reset your password. I'll send you a reset link via email."}
    ],
    session_id=session_id,
    source="support_chat"
)

# Turn 3: User confirms resolution (same session_id)
client.publish_interaction(
    user_id="customer_001",
    interactions=[
        {"role": "User", "content": "Thank you! That worked perfectly."},
        {"role": "Agent", "content": "You're welcome! Is there anything else I can help you with?"}
    ],
    session_id=session_id,
    source="support_chat"
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "customer_001",
  "interaction_data_list": [
    {
      "role": "User",
      "content": "Hi, I'm having trouble with my account login"
    },
    {
      "role": "Agent",
      "content": "I'm sorry to hear that. Can you tell me what error message you're seeing?"
    }
  ],
  "session_id": "support_session_001",
  "source": "support_chat"
}
JSON

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "customer_001",
  "interaction_data_list": [
    {
      "role": "User",
      "content": "It says 'Invalid credentials' but I'm sure my password is correct"
    },
    {
      "role": "Agent",
      "content": "Let me help you reset your password. I'll send you a reset link via email."
    }
  ],
  "session_id": "support_session_001",
  "source": "support_chat"
}
JSON

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "customer_001",
  "interaction_data_list": [
    {
      "role": "User",
      "content": "Thank you! That worked perfectly."
    },
    {
      "role": "Agent",
      "content": "You're welcome! Is there anything else I can help you with?"
    }
  ],
  "session_id": "support_session_001",
  "source": "support_chat"
}
JSON

Use visual examples when the user's meaning depends on an image, screenshot, or other visual artifact. Include text whenever possible; the text helps explain what the image represents.

Image-Based Interactions

Use this when the visual artifact is part of the user's task, such as product photos, fashion styling, document images, or design review inputs.

# Function to encode images for Reflexio
def encode_image(image_path: str) -> str:
    """Encode image to base64 string."""
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# Example 1: Product review with image
product_image = encode_image("./product_photos/smartphone.jpg")

client.publish_interaction(
    user_id="reviewer_bob",
    interactions=[
        {
            "content": "This phone has an amazing camera quality! Look at this photo I took:",
            "image_encoding": product_image,
            "user_action": "none"
        }
    ],
    session_id="review_001",
    source="product_review"
)

# Example 2: Fashion styling consultation
outfit_image = encode_image("./fashion/outfit_1.jpg")

client.publish_interaction(
    user_id="fashion_client",
    interactions=[
        {
            "role": "Client",
            "content": "What do you think about this outfit for a business meeting?",
            "image_encoding": outfit_image
        }
    ],
    session_id="styling_001",
    source="styling_consultation"
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "reviewer_bob",
  "interaction_data_list": [
    {
      "content": "This phone has an amazing camera quality! Look at this photo I took:",
      "image_encoding": "<encode_image_result>",
      "user_action": "none"
    }
  ],
  "session_id": "review_001",
  "source": "product_review"
}
JSON

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "fashion_client",
  "interaction_data_list": [
    {
      "role": "Client",
      "content": "What do you think about this outfit for a business meeting?",
      "image_encoding": "<encode_image_result>"
    }
  ],
  "session_id": "styling_001",
  "source": "styling_consultation"
}
JSON

Screenshots and UI Feedback

Use this when the image is evidence for a product experience: bug reports, screen-level feedback, UX confusion, or actions the user took in the interface.

# Publishing UI/UX feedback with screenshots
ui_screenshot = encode_image("./screenshots/app_interface.png")

client.publish_interaction(
    user_id="beta_tester",
    interactions=[
        {
            "content": "The new dashboard layout is confusing. The navigation menu is hard to find.",
            "image_encoding": ui_screenshot,
            "user_action": "none"
        }
    ],
    session_id="ui_feedback_001",
    source="ui_testing"
)

# Publishing bug report with screenshot
bug_screenshot = encode_image("./bugs/error_screen.png")

client.publish_interaction(
    user_id="qa_tester",
    interactions=[
        {
            "content": "Application crashes when clicking the export button. Error details in screenshot.",
            "image_encoding": bug_screenshot,
            "user_action": "click",
            "user_action_description": "clicked export button in reports section"
        }
    ],
    session_id="bug_report_001",
    source="bug_reports"
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "beta_tester",
  "interaction_data_list": [
    {
      "content": "The new dashboard layout is confusing. The navigation menu is hard to find.",
      "image_encoding": "<encode_image_result>",
      "user_action": "none"
    }
  ],
  "session_id": "ui_feedback_001",
  "source": "ui_testing"
}
JSON

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "qa_tester",
  "interaction_data_list": [
    {
      "content": "Application crashes when clicking the export button. Error details in screenshot.",
      "image_encoding": "<encode_image_result>",
      "user_action": "click",
      "user_action_description": "clicked export button in reports section"
    }
  ],
  "session_id": "bug_report_001",
  "source": "bug_reports"
}
JSON

Expert Content Interactions

Use expert content when a reviewer, evaluator, or domain specialist can provide the answer the agent should have given. This is especially useful for improving playbooks from high-quality corrections.

If you want an imitation-learning-style workflow where the agent learns from an expert's answer for a specific case, publish the original agent answer together with the expert's ideal answer in expert_content. Reflexio compares the two responses and extracts playbook guidance that teaches the agent to handle similar cases more like the expert next time.

Use this when you have gold-standard answers, reviewer corrections, compliance review, QA examples, or historical expert-written responses that you want to turn into durable agent behavior.

Publishing Expert-Reviewed Conversations

Attach expert_content to the agent interaction that needs correction. Keep the original agent content too; the contrast between the agent's response and the expert's response is the learning signal.

In this example, the agent gives a short but incomplete return-policy answer. The expert answer adds the important conditions, exceptions, and refund timing, so Reflexio can turn that gap into reusable guidance for future return-policy questions.

# Provide expert ideal responses for agent learning
# Expert content triggers a specialized playbook extraction pipeline
session_id = "expert_review_batch_001"

# Expert reviews a customer service conversation
client.publish_interaction(
    user_id="customer_001",
    interactions=[
        {"role": "User", "content": "What is your return policy for electronics?"},
        {
            "role": "Agent",
            "content": "You can return electronics within 30 days of purchase.",
            "expert_content": (
                "Electronics can be returned within 30 days of purchase with the original receipt. "
                "Items must be in original packaging and include all accessories. "
                "Opened software and personal care electronics are final sale. "
                "For defective items, the return window extends to 90 days. "
                "Refunds are processed to the original payment method within 5-7 business days."
            )
        }
    ],
    session_id=session_id,
    source="expert_review",
    agent_version="v1.0"
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "customer_001",
  "interaction_data_list": [
    {
      "role": "User",
      "content": "What is your return policy for electronics?"
    },
    {
      "role": "Agent",
      "content": "You can return electronics within 30 days of purchase.",
      "expert_content": "Electronics can be returned within 30 days of purchase with the original receipt. Items must be in original packaging and include all accessories. Opened software and personal care electronics are final sale. For defective items, the return window extends to 90 days. Refunds are processed to the original payment method within 5-7 business days."
    }
  ],
  "session_id": "expert_review_batch_001",
  "source": "expert_review",
  "agent_version": "v1.0"
}
JSON

User Action Tracking

Use action tracking when user behavior matters even without a natural-language message. This is useful for commerce, onboarding, product analytics, and UI flows where clicks or navigation reveal intent.

E-commerce Actions

This example publishes several actions from one shopping session so Reflexio can learn both what the user did and what they said while browsing.

# Tracking user shopping behavior
shopping_actions = [
    {
        "user_action": "click",
        "user_action_description": "clicked on 'Laptops' category",
        "interacted_image_url": "https://store.example.com/categories/laptops"
    },
    {
        "user_action": "scroll",
        "user_action_description": "scrolled through laptop listings page"
    },
    {
        "user_action": "click",
        "user_action_description": "clicked on MacBook Pro 16-inch product page",
        "interacted_image_url": "https://store.example.com/products/macbook-pro-16"
    },
    {
        "content": "This laptop looks perfect for my video editing work",
        "user_action": "none"
    },
    {
        "user_action": "click",
        "user_action_description": "added MacBook Pro 16-inch to cart",
        "content": "Added to cart"
    }
]

client.publish_interaction(
    user_id="shopper_dave",
    interactions=shopping_actions,
    session_id="shopping_session_001",
    source="ecommerce"
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "shopper_dave",
  "interaction_data_list": [
    {
      "user_action": "click",
      "user_action_description": "clicked on 'Laptops' category",
      "interacted_image_url": "https://store.example.com/categories/laptops"
    },
    {
      "user_action": "scroll",
      "user_action_description": "scrolled through laptop listings page"
    },
    {
      "user_action": "click",
      "user_action_description": "clicked on MacBook Pro 16-inch product page",
      "interacted_image_url": "https://store.example.com/products/macbook-pro-16"
    },
    {
      "content": "This laptop looks perfect for my video editing work",
      "user_action": "none"
    },
    {
      "user_action": "click",
      "user_action_description": "added MacBook Pro 16-inch to cart",
      "content": "Added to cart"
    }
  ],
  "session_id": "shopping_session_001",
  "source": "ecommerce"
}
JSON

Searching and Analyzing Interactions

Use these examples when you need to inspect raw interaction records. For agent-facing learned context, use Searching Learned Context instead.

Semantic Search Across Interactions

Use semantic search when you know the topic you want to investigate, but not the exact request id or timestamp.

# Search for specific topics across all user interactions
search_results = client.search_interactions(
    user_id="customer_001",
    query="password reset login issues"
)

print(f"Found {len(search_results.interactions)} relevant interactions:")
for interaction in search_results.interactions:
    print(f"[{interaction.role}]: {interaction.content}")
    print(f"  Source: {interaction.request_id}")
    print(f"  Action: {interaction.user_action}")
    print("---")

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_interactions" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "customer_001",
  "query": "password reset login issues"
}
JSON

Analyzing User Behavior Patterns

Use listing and local analysis when you need counts, summaries, or custom offline diagnostics over a user's raw interaction history.

# Get all interactions for behavior analysis
all_interactions = client.get_interactions(
    user_id="shopper_dave",
    top_k=100
)

# Analyze interaction patterns
interaction_sources = {}
action_types = {}
content_themes = []

for interaction in all_interactions.interactions:
    # Count by source
    source = interaction.request_id.split('_')[0]  # Extract source prefix
    interaction_sources[source] = interaction_sources.get(source, 0) + 1

    # Count by action type
    action = interaction.user_action.value
    action_types[action] = action_types.get(action, 0) + 1

    # Collect content for theme analysis
    if interaction.content:
        content_themes.append(interaction.content)

print("Interaction Sources:", interaction_sources)
print("Action Types:", action_types)
print(f"Total content items: {len(content_themes)}")

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_interactions" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "shopper_dave",
  "top_k": 100
}
JSON

Time-Based Interaction Analysis

Use this when the question is time-oriented, such as recent activity, progress over a week, or behavior around a launch window.

from datetime import datetime, timedelta

# Search for recent interactions (last 7 days)
week_ago = int((datetime.now() - timedelta(days=7)).timestamp())
now = int(datetime.now().timestamp())

recent_interactions = client.search_interactions(
    user_id="student_eve",
    query="learning progress course completion"
    # Note: Add time filtering if supported by your API version
)

# Group interactions by day
daily_activity = {}
for interaction in recent_interactions.interactions:
    day = datetime.fromtimestamp(interaction.created_at).date()
    if day not in daily_activity:
        daily_activity[day] = []
    daily_activity[day].append(interaction)

print("Daily Learning Activity:")
for day, interactions in sorted(daily_activity.items()):
    print(f"{day}: {len(interactions)} interactions")
    for interaction in interactions[:3]:  # Show first 3
        print(f"  - {interaction.content[:50]}...")

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_interactions" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "student_eve",
  "query": "learning progress course completion"
}
JSON