How to Upload Conversations Manually

Step 1: Where to find Manual Upload (Conversations)

Follow these steps to open the manual conversation upload interface:

Go to the AI Admin Panel in your Avon AI dashboard.
In the sidebar, select Conversation Analysis.
Click the Upload Conversations button at the top of the page.
Choose one of the input methods: Paste JSON: paste a single conversation or multiple conversations in JSON/JSONL Upload File: select a local .json or .jsonl file
Click Validate to preview how the conversation(s) will be parsed and displayed.
If everything looks good, click Upload to add the conversations to the platform.

Notes:

Manual upload works even if you haven’t fully connected an agent yet,
but you will need the correct Agent_ID during the upload so the data is mapped to the right agent.
You can repeat manual uploads as needed; consider S3 integration for ongoing/automated ingestion.

Step 2: Conversation JSON Format

Before uploading your conversations, make sure the file follows the required JSON structure. This ensures the platform can properly parse, analyze, and associate each conversation with the correct agent.

What’s inside the file

conversation_id – A unique identifier for each conversation.
timestamp – The time when the conversation started.
agent_id – The unique ID of the agent or bot managing the conversation.
is_resolved – Whether the issue was resolved.
csat_score – The customer satisfaction rating (e.g., 4.5 out of 5).
missing_info – Information the customer did not provide (e.g., a hidden phone number).
user_data – Details about the customer, such as account type, subscription tier, language preferences, notifications, and last activity.
messages – A list of messages exchanged between the customer and the agent. Each message contains:
role – Whether the sender is the customer or the agent.
content – The message text.
timestamp – When the message was sent.
logs – Internal records documenting events during the conversation, such as lookups or actions.

Example JSON File

[
	{
		"conversation_id": "avon-ai-example-conv-001",
		"timestamp": "2025-01-15T14:30:00.000Z",
		"agent_id": "agent-avon-ai-001",
		"is_resolved": true,
		"csat_score": 4.5,
		"user_data": {
			"account_type": "premium",
			"subscription_tier": "professional",
			"preferences": {
				"language": "en-US",
				"notifications": true
			},
			"last_activity": "2025-01-14T14:30:00.000Z"
		},
		"messages": [
			{
				"message_id": "msg-001",
				"conversation_id": "avon-ai-example-conv-001",
				"role": "customer",
				"sender_id": "user-001",
				"content": "Hello, I need help with my account billing. I see some charges I don't understand.",
				"timestamp": "2025-01-15T14:30:00.000Z",
				"logs": [
					{
						"name": "User Input Source",
						"content": "Web chat interface via desktop browser"
					},
					{
						"name": "Session Info",
						"content": "Session ID: sess-001, Duration: 0ms"
					},
					{
						"name": "Device Details",
						"content": "Chrome 120.0, Windows 11"
					}
				]
			},
			{
				"message_id": "msg-002",
				"conversation_id": "avon-ai-example-conv-001",
				"role": "agent",
				"sender_id": "agent-avon-ai-001",
				"content": "I'd be happy to help you understand your billing charges. Let me review your account details.",
				"timestamp": "2025-01-15T14:30:30.000Z",
				"logs": [
					{
						"name": "Account Lookup",
						"content": "Successfully retrieved customer billing details"
					},
					{
						"name": "Database Query",
						"content": "3 billing records found in customer profile"
					},
					{
						"name": "Processing Time",
						"content": "245ms"
					}
				]
			},
			{
				"message_id": "msg-003",
				"conversation_id": "avon-ai-example-conv-001",
				"role": "customer",
				"sender_id": "user-001",
				"content": "Thank you! That breakdown was very helpful.",
				"timestamp": "2025-01-15T14:32:00.000Z",
				"logs": [
					{
						"name": "Satisfaction Analysis",
						"content": "Positive sentiment detected in customer response"
					},
					{
						"name": "Confidence Score",
						"content": "95% confidence level"
					},
					{
						"name": "Resolution Status",
						"content": "Issue successfully resolved"
					}
				]
			}
		]
	}
]

Additional Implementation Notes

Each uploaded file must include the "agent_id" field to link data correctly.
JSONL (one conversation per line) is also supported.
Use ISO 8601 timestamp format (YYYY-MM-DDTHH:MM:SSZ).
Validate your JSON file before uploading to ensure proper structure.
Include logs and metadata when possible — they enhance analysis accuracy and conversation insights.

Step 3: Finding and Using the Agent ID

Every conversation file must include an "agent_id" that matches the agent defined in your Avon AI platform. The Agent ID is a unique identifier that links all data — conversations, tests, and analytics — to a specific agent.

Follow these steps to locate your Agent ID:

Go to the AI Admin Panel in your Avon AI dashboard.
In the sidebar, select Agents.
Find the agent you want to connect your conversations to.
Click the three-dot menu (⋮) next to that agent.
Select Configure or Integrate.
In the General section, you’ll see the Agent ID field.

Copy this Agent ID and paste it into the agent_id field in your conversation JSON file.

Example: "agent_id": "agent-avon-ai-001"

Notes:

Each agent has a unique ID automatically generated by the system.
You do not need to manually create or modify the ID.
Using the correct Agent ID ensures conversations, analytics, and tests are all associated with the right agent.
If you upload a conversation without a valid Agent ID, it will not be linked to any agent in the platform.

Step 4: Validate and Preview

Before completing the upload, always use the “Validate” option to make sure your JSON file is correctly formatted and all fields are recognized by the platform.

After selecting your JSON or JSONL file (or pasting JSON text), click the Validate button.
The system will process the file and display a Preview of the conversation data.

What to check in the preview:

Each conversation appears with a unique conversation_id.
agent_id is correctly populated and matches your agent in the platform.
messages are ordered chronologically and show both user and agent roles.
user_data fields appear as expected (account type, subscription, etc.).
logs (if included) are shown in context with each message.
No parsing errors or missing fields are reported.

If validation fails, review the error message to identify which field or structure needs correction:

Missing or invalid agent_id
Incorrect timestamp format (must be ISO 8601: YYYY-MM-DDTHH:MM:SSZ)
Invalid JSON syntax (commas, brackets, or quotation marks)
Unsupported field names or nested structures

Once validation passes successfully, click Upload to continue to the final step.

Notes:

Validation ensures the file can be processed without issues after upload.
Always validate before uploading large or multiple conversation files.
If your JSON passes validation, it will appear in the preview exactly as it will be stored in the platform.

Step 5: Upload and Verify Status

Once your JSON file passes validation, you can proceed to upload the conversations directly into the Avon AI platform.

After successful validation, click the Upload button.
The upload process will begin — you’ll see a status indicator for progress.

Upload Status:

Succeeded – The conversation data was successfully uploaded and linked to your agent.
Failed – There was an issue with the upload. Hover over or click the status icon to view details.
Partial Success – Some conversations uploaded successfully, while others failed (check the error logs).

Common upload issues:

Invalid or missing agent_id
Incorrect timestamp format
File exceeds maximum allowed size (50 MB per file)
Unsupported file format (must be .json or .jsonl)
Network timeout during upload

After a successful upload:

The conversation will automatically appear in Conversation Analysis under your linked agent.
You can filter or search by conversation_id, timestamp, or agent_id.
Uploaded conversations are available for quality evaluation, validation alerts, and analytics.

Notes:

If multiple uploads are needed, repeat the process for each file (manual uploads are not automated).
Consider switching to the S3 Integration feature in Data Import for continuous ingestion of large datasets.
Always verify that your uploaded data appears in the Conversation Analysis view before proceeding with analysis or validation.

Step 1: Where to find Manual Upload (Conversations)

Step 2: Conversation JSON Format

Step 3: Finding and Using the Agent ID

Step 4: Validate and Preview

Step 5: Upload and Verify Status

After a successful upload:​

After a successful upload: